Non-Personalised Messaging

With non-personalised messaging, each phone number added to the destinations list receives the same message content as received by others. In this section, we wil be looking at how to send non-personalised messages.

As earlier emphasised, SMS requests must be submitted using the POST request method to the following request URL.

  https://api.sms.jbsaleshub.com/v5/message/sms/send

Specifically, the request header will look like the following.

  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

Recall that the Content-Type should be set to the request data format. For instance, if the request data is XML, then the Content-Type will be set to application/xml. Similarly, the Accept header must be set to the data format in which the client application wants to receive the response.

The following data shows a minimal sample SMS message data that can be sent as the POST data.

JSON
XML

{
    "text" : "Hello world!",
    "type" : 0,
    "sender" : "TEST",
    "destinations": ["233241234567", "0501234567"]
}

<request>
    <text>Hello world!</text>
    <type>0</type>
    <sender>TEST</sender>
    <destinations>
        <to>233241234567</to>
        <to>0501234567</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.

Example Request

<?php 
    // set up the request headers
    $headers = [
        'Host: api.sms.jbsaleshub.com',
        'Content-Type: application/json',
        'Accept: application/json',
        'Authorization: key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128'
    ];
	
    // set up the message data
    $messageData = [
        'text'=>'This is a test message',
        'type'=> 0,	// GSM default
        'sender'=> 'TEST',
        'destinations'=> ['0246314915', '0242053072']
    ];
	
    // initialise cURL
    $ch = curl_init('https://api.sms.jbsaleshub.com/v5/sms/send');
    
    // set cURL optionS
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($messageData));
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    // Execute for response
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

    // close curl
    curl_close($ch);

if ($httpCode == 200){
    var_dump($response);
}

import json
import http.client as httpClient

try: 
    host = 'api.sms.jbsaleshub.com'
    requestURI = 'http://api.sms.jbsaleshub.com/v5/message/sms/send'
    apiKey = 'd5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128'

    headers = dict()
    headers['Host'] = host
    headers['Content-Type'] = 'application/json'
    headers['Accept'] = 'application/json'
    headers['Authorization'] = f'key {apiKey}'

    # message data
    msgData = dict()
    msgData['text'] = 'This is a test message'
    msgData['type'] = 0
    msgData['sender'] = 'TEST'
    msgData['destinations'] = ['0246314915', '0242053072']

    httpConn = httpClient.HTTPConnection(host)
    httpConn.request('POST', requestURI, json.dumps(msgData), headers)

    # get the reponse
    response = httpConn.getresponse()

    # check the status
    status = response.status

    if status == 200:
        responseData = response.read()
        print(responseData)
    else:
        print('Request was unsuccessful')

except Exception as e:
    print(str(e))

const axios = require('axios');

try {
    let host = 'api.sms.jbsaleshub.com';
    let endPoint = `http://${host}/v5/message/sms/send`;

    // the message data
    let msgData = {
        text: 'This is a test message',
        type: 0,    // GSM default
        sender: 'TEST',
        destinations: ['0246314915', '0242053072']
    };

    axios.request({
        method: 'POST',
        url: endPoint,
        data: msgData,
        headers: {
            'Host': `${host}`,
            'Content-Type': 'application/json',
            'Accept': 'application/json',
            'Authorization': 'key d5c683a1b4c3d2f278be3d4c03c23191b2f133378b12b6e197c1ad5d9b34c128'
        }
    })
    .then(function (response) {
        console.log(response);

        let httpStatus = response.status;

        if (response.status == 200) {
            let handshake = response.data.handshake;
            let respData  = response.data.data;
			
            console.log(respData);
        }
    })
    .catch(function (error) {
        console.log(error.stack);
    });
}

Applications will need to check the HTTP Status Code after submitting a request. If the request was successful and understood, the HTTP Status Code will be set to 200. However, this does not necessarily mean the request was successful. The status of handshake section of the response data must also be checked to ensure that it has the id value of 0 and label value of HSHK_OK.

Example Response

After submitting the message, a message response data will be submitted as follows:

JSON
XML

{
    "handshake" : {
        "id" : 0,
        "label" : "HSHK_OK"
    },
    "data": {
        "batch" : "cfa19ba67f94fbd6b19c067b0c87ed4f",
        "category": 1,
        "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>key</id>
        <label>HSHK_OK</label>
    </handshake>
    <data>
        <batch>cfa19ba67f94fbd6b19c067b0c87ed4f</batch>
        <category>1</category>
        <delivery>false</delivery>
        <destinations>
            <item>
                <id>093841e5-578a-41f4-5f5f-2f3910886c12</id>
                <to>233241234567</to>
                <status>
                    <id>2105</status>
                    <label>DS_PENDING_ENROUTE</label>
                </status>
            </item>
            <item>
                <id>4abfa3bd-93f9-b8a1-4bbd-78725ca3e488</id>
                <to>233501234567</to>
                <status>
                    <id>2105</status>
                    <label>DS_PENDING_ENROUTE</label>
                </status>
            </item>
        </destinations>
    </data>
</response>

As can be seen, the data section of the message response is returned as an array of Message Units.

The section on Message Responses takes an in-depth look at understanding and processing message responses. For applications that process message responses, it is advised that readers go through the discussions for processing message responses.