Personalised Messaging
With personalised SMS, messages are customised for each message destination. This only requires composing a single message template which specifies the parts of the message text where values will be substituted for customising the message for each destination.
Sending personalised SMS requires providing values for the parameters
for sending non-personalised SMS, as was discussed under Non Personalised Messaging,
as well as value for an additional parameter name values which is used to
set values that will be used to customise messages for each destination.
Message Template
To send personalised SMS, a single message template needs to be composed. The message template should contain variables in parts of the message where values will be different for each of the message destinations. During processing, values specified for each destination will be substituted in place of the variables to generate a customised message for each message destination.
Message Variables
A variable is defined in a message template with an opening curly brace {
followed by the dollar sign $, followed by a descriptive name for the
variable, and then ending it with a closing curly brace }.
A variable name must begin with a letter or underscore followed by other alpha-numeric characters. The following are valid variable names that can be defined in the message template.
{$name}, {$age}, {$_balance}.
Suppose we want to send messages to customers to alert them of their account balances. We can compose a single template message such as the following:
Hello {$name}. Your current balance is ${$balance}
The message template can then be set as the value for the text parameter
as text=MESSAGE_TEXT_WITH_VARIABLES. The following code fragement shows the text parameter
being set to a message text with variables.
key=API_KEY&text=Hello {$name}. Your current balance is ${$balance}&type=0&sender=SENDER_ID&to=PHONE_NUMBER
If the HTTP GET will be used to send the message, then message text should be URL encoded
before setting to the text parameter in the request data values.
key=API_KEY&text=Hello+%7B%24name%7D.+Your+current+balance+is+%24%7B%24balance%7D&type=0&sender=SENDER_ID&to=PHONE_NUMBER
Recall also that with HTTP GET request, the request data values need to be appended to the request URI
with the character ? as a separator.
https://api.smsonlinegh.com/v5/message/sms/send?key=API_KEY&text=Hello+%7B%24name%7D.+Your+current+balance+is+%24%7B%24balance%7D&type=0&sender=SENDER_ID&to=PHONE_NUMBER
The above request data is a partial data for sending personalised SMS. It is missing the values that will be used for variable substitution in order to customise the message for each destination. We discuss how to set the personalised values next.
Note
The value set as sender must exist in the list of user message sender names. If the
name has not been added in user message sender names, then the message will not be submitted.
The sender name must be requested from the user account under SMS Messaging menu option.
Destination Values
The values to be used in customising the message for each destination must be provided
in the order in which their corresponding variables were defined in the message template.
The values for a destination need to be separated with the character sequence __@.
That is, __ (double underscore), followed by @.
Single Destination Values
Consider the example message template stated earlier:
Hello {$name}. Your current balance is ${$balance}
The message text contains two variables labelled name and balance.
When providing values for a particular message destination, the values to be
used for substitution must be provided in the order in which the variables are
provided. For example:
Daniel__@450.00
Notice that the values Daniel and 450.00 are being separated by the
character sequence __@. If there are more variables, they will need to be
separated the same way.
Multiple Destination Values
As indicated earlier, the concatenated values for a particular destination must be provided
separated by __@. For example:
Daniel__@450.00
The above concatenated values applies to a single message destination. If there are
multiple destinations, then the concatenated values for each destination must be
separated by the character sequence __#. That is, __ (double underscore), followed by #.
Suppose there are three destinations with the following values:
Daniel__@450.00
Albert__@367.35
Mabel__@420.85
The concatenated values for all the destinations can be composed into a single value as:
Daniel__@450.00__#Albert__@367.35__#Mabel__@420.85
Notice the individual concatenated values are being joined together by __#.
Setting Values
The composed values should be set to the parameter values in the request data values.
key=API_KEY&text=Hello {$name}. Your current balance is ${$balance}&type=0&sender=SENDER_ID&to0246314915,0242053072,233207729851&values=Daniel__@450.00__#Albert__@367.35__#Mabel__@420.85
Recall that when submitting request through HTTP GET method, values for key,
text, sender, values must be URL encoded.
GET https://api.smsonlinegh.com/v5/message/sms/send?key=API_KEY&text=Hello+%7B%24name%7D.+Your+current+balance+is+%24%7B%24balance%7D&type=0&sender=SENDER_ID&to0246314915,0242053072,233207729851&values=Daniel__%40450.00__%23Albert__%40367.35__%23Mabel__%40420.85
Host: smsonlinegh.com
Content-Type application/x-www-form-urlencoded
Accept: application/json
URL encoding of parameters is not required when submitting the request
through HTTP POST method.
POST https://api.smsonlinegh.com/v5/message/sms/send
Host: smsonlinegh.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
key=API_KEY&text=Hello {$name}. Your current balance is ${$balance}&type=0&sender=SENDER_ID&to0246314915,0242053072,233207729851&values=Daniel__@450.00__#Albert__@367.35__#Mabel__@420.85
A Note on Correspondence
It is very important to ensure consistency between the order in which phone numbers and destination values are provided. For multiple destinations, the first phone number corresponds to the first destination values, the second phone number corresponds to the second destination values, etc.
Consider the previous example request data:
key=API_KEY&text=Hello {$name}. Your current balance is ${$balance}&type=0&sender=SENDER_ID&to0246314915,0242053072,233207729851&values=Daniel__@450.00__#Albert__@367.35__#Mabel__@420.85
It can be observed that three phone numbers have been provided and set to the to parameter.
to=0246314915,0242053072,233207729851
Additionally, three destination values have been provided and set to the values paremeter.
values=Daniel__@450.00__#Albert__@367.35__#Mabel__@420.85
If we decompose the values with __# as the separator we get the following:
Daniel__@450.00
Albert__@367.35
Mabel__@420.85
In this case, the first destination values Daniel__@450.00 apply to the phone number 0246314915,
the second destination values Albert__@367.35 apply to the phone number 0242053072,
and the third destination values Mabel__@420.85 apply to the phone number 233207729851.
When composing the complete values to be set to the values parameter, the order in which
the different destination values are appended must match the order in which the phone numbers
are appended to ensure that each destination gets the right customised message.