Personalised Messaging

Personalised messaging involves customising the message content for each message destination. In this case, each destination receives a different message content customised to address that specific destination.

In this section, we will be looking at how to send personalised SMS through our HTTP REST API.

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.

Defining 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 in the message unit. The following code fragment shows the text property being set to a message text with variables.

JSON
XML

{
    "text" : "Hello {$name}. Your current balance is ${$balance}.",
    "type" : 0,
    "sender" : "TEST"
}

<text>Hello {$name}. Your current balance is ${$balance}.</text>
<type>0</type>
<sender>TEST</sender>

Destination Values

As with Non-Personalised Messaging, the list of destinations is added as an array and set to the destinations parameter for the message unit. In the case of personalised SMS however, an additional parameter must be set for the values that will substituted for customising the message for each destination.

The order in which the values are provided must match the order in which the variables are defined in the message template in order to receive the customised message as expected.

The complete request data that should be submitted will be as follows:

JSON
XML

{
    "text" : "Hello {$name}. Your current balance is ${$balance}.",
    "type" : 0,
    "sender" : "TEST",
    "destinations" : [
        {
            "number" : "0246314915",
            "values" : ["Daniel", 560.45]
        },
        {
            "number" : "0242053072",
            "values" : ["Emmanuel", 348.56]
        }
    ]
}

<request>
    <text>Hello {$name}. Your current balance is ${$balance}.</text>
    <type>0</type>
    <sender>TEST</sender>
    <destinations>
        <to>
            <number>0246314915</number>
            <values>
                <value>Daniel</value>
                <value>560.45</value>
            </values>
        </to>
        <to>
            <number>0501234567</number>
            <values>
                <value>Emmanuel</value>
                <value>348.56</value>
            </values>
        </to>
    </destinations>
</request>

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.

As with non-personalised messaging, the request header, assuming a JSON request data, can be setup as follows:

POST https://api.sms.jbsaleshub.com/v5/message/sms/send
Content-Type: application/json
Accept: application/json
Host: api.sms.jbsaleshub.com 
Authorization: key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128

From the sample request data, the following messages will be generated on the server after customisation is completed for submission to each message destination:

Hello Daniel. Your current balance is $560.45.

Hello Emmanuel. Your current balance is $348.56.

When submitted, the following response data will be returned

JSON
XML

{
    "handshake" : {
        "id" : 0,
        "label" : "HSHK_OK"
    },
    "data": {
    "batch" : "cfa19ba67f94fbd6b19c067b0c87ed4f",
    "delivery": false,
    "destinations: [
        {
            "id" : "093841e5-578a-41f4-5f5f-2f3910886c12",
            "to" : "233246314915",
            "status" : {
                "id" : 2105,
                "label" : "DS_PENDING_ENROUTE"
            }
        },
        {
            "id" : "4abfa3bd-93f9-b8a1-4bbd-78725ca3e488",
            "to" : "233242053072",
            "status" : {
                "id" : 2105,
                "label" : "DS_PENDING_ENROUTE"
                }
            }
        ]
    }
}

<response>
    <handshake>
        <id>0</id>
        <label>HSHK_OK</label>
    </handshake>
    <data>
        <batch>cfa19ba67f94fbd6b19c067b0c87ed4f</batch>
        <delivery>false</delivery>
        <destinations>
            <item>
                <id>093841e5-578a-41f4-5f5f-2f3910886c12</id>
                <to>233246314915</to>
                <status>
                    <id>2105</status>
                    <label>DS_PENDING_ENROUTE</label>
                </status>
            </item>
            <item>
                <id>4abfa3bd-93f9-b8a1-4bbd-78725ca3e488</id>
                <to>233242053072</to>
                <status>
                    <id>2105</status>
                    <label>DS_PENDING_ENROUTE</label>
                </status>
            </item>
        </destinations>
    </data>
</request>

The section on Message Response is a valuable resource that explains how to process responses with much emphasis on identifying the status of message units and message destinations.