HTTP API

Application to Person (A2P)

Overview.

IntouchSMS's HTTP API enables you to send and receive text messages to and from users using simple REST APIs.
  • Programmatically send and receive high volumes of SMS globally.
  • Receive SMS using local numbers.
  • Scale your applications with familiar web technologies.
  • Pay only for what you use, nothing more.

    This section contains the following sub sections. You can click on the link below to quickly jump to that section:

  • Concepts
  • Usage
  • Format Guide
  • Send SMS
  • Send SMS Status Request

  • Concepts.

    Before using the IntouchSMS SMS API, familiarize yourself with the following:
    Number format - The SMS API requires phone numbers in E.164 format.
    Authentication - The SMS API authenticates using your account API key and secret.
    API Architecture - REpresentational State Transfer (REST) framework.

    Usage.

    Create An Account

    First, sign up for an IntouchSMS account if you don't already have one, and make a note of your username and password. You can use this same username/password pair to log into your dashbord and also to connect via the HTPP API.

    Replace the following placeholder values in the sample code:
    username: Your intouchSMS username.
    password: Your intouchSMS password.


    Write your code

    Messages can be sent using HTTP “POST” issued by your gateway or server. The URL to use to send messages is: https://www.intouchsms.co.rw/api/sendsms/.json

    Download the full HTPP API Reference from the link below, to guide you on how to structure your code:

    HTTP API Reference Guide

    Format Guide.

    Change Sender ID.

    How to change where your SMS appears to come from.

    The sender parameter in the request can only contain numeric or alphanumeric values that obey certain rules:

    Numeric.
  • Must be a telephone number of up to 15 digits
  • Must be in international format
  • Cannot include the leading + or 00

    Alphanumeric.
  • Must be a string of up to 11 supported characters.

    Note: If the value in your sender parameter does not obey these rules it might be modified in transit or not delivered at all.


    Maximum Number of Characters.

    The maximum length of a single SMS message is 140 bytes, which equates to 160 standard GSM 7-bit characters or 70 UCS-2 16-bit characters. A message longer than that is split into parts.


    Concatenation.

    If you send a message that contains more than the maximum number of characters per message, IntouchSMS sends a concatenated SMS. A concatenated SMS contains multiple SMS parts that are connected by segmentation information in the User Data Header (UDH).

    This segmentation information tells the handset the number of message parts that make up the concatenated SMS and the position of each message part within it. When the handset has received all of the message parts, it presents them to the recipient as a single text.

    For more information, the read the section below about Multipart SMS.

    The message body of a long SMS is split into chunks of 132 bytes (152 GSM characters or 66 Unicode characters), excluding headers.

    The maximum length of a single SMS body is 140 bytes. The length of the body of a multi-part SMS is reduced because those extra 8 bytes are needed to hold 'segmentation information' that is sent along with the body of the sms, so that the handset knows how to put all the parts back together again into a single long message.

    Due to the nature of SMS, and networks in general, the different parts may arrive in any order, so this segmentation information is vital for the handset to be able to re-construct the message properly.

    One final thing to consider with long SMS, it's not always the case that 160 characters will fit into a single GSM-encoded SMS. There are some characters in the GSM alphabet that require 2 characters because they are 'extended alphabet' characters. So they need an 'escape' char + a char. A good example is the £ sign or Euro symbol. These 'escape' characters are also taken into account when deciding where to split the message into parts.


    Delivery Reports.

    When you make a successful request to the HTTP SMS API, it returns an array of message objects, one for each message. the repsonse will contain a statuscode indicating success or failure, and a description to indicate the reason why the message failed to be sent in case it's a failure.

    The status code will be one of the two below:

    200 Ok. No error encountered.

    400 Bad Request. Error encountered.

    Download the full HTPP API Reference from the link below, to guide you on how to structure your code:

    HTTP API Reference Guide
    Status Request.

    You could also use the Status Request API to query indovidual message delivery status. Please refer to the API Reference Document on how to structure this request. This request requires a message ID to be sent as a parameter.

    The parameters included in this request are:
    username: your intouchSMS account username.
    password: your intouchSMS account password.
    messageid: The message ID returned in the sendSMS response.

    The Status Request is sent to https://www.intouchsms.co.rw/api/getsmsstatus/.json

    The SMS Gateway will respond with a status of the message, represented by a letter as shown below:
    P - Message still being processed.
    D - Message has been delivered successfully.
    Q - Message is still in Queue.
    E - Message has Errored.
    S - Message has been sent to the carrier for delivery
    U - Message Unsent by the carrier.


  • Send SMS.

    Messages can be sent using HTTP “POST” issued by your gateway or server. The URL to use to send messages is: https://www.intouchsms.co.rw/api/sendsms/.json

    A send SMS request to the gateway to be sent should be encoded as a json string. Below are the necessary parameters to be passed with the URL.

    Parameter Data Format Description
    username string Username assigned to your account Intouch
    password string Password provided by Intouch for your account associated with your username.
    recipients string Phone numbers of the recipient(s) if more than one they should be separated by commas
    sender string From Name. Can be Alphanumeric
    message string Contents of the message. eg. test sms.

    Python Code.


    
                         data={
                                'recipients':'0785971082,0782300441',
                                'message':'Hello World',
                                'sender':'Intouch'
                             }'
    
                         r=requests.post(
                                    'https://www.intouchsms.co.rw/api/sendsms/.json',
                                    data,
                                    auth=(username,password)
                                    )
    
                         print (r.json(), r.status_code)
                        

    PHP Code.


    
                         $data=array(
                                      "sender"=>'Intouch',
                                      "recipients"=>"0722404528",
                                      "message"=>"helloworld",
                                    );
    
                         $url="https://www.intouchsms.co.rw/api/sendsms/.json";
                         $data=http_build_query($data);
                         $username="username";
                         $password="password";
    
                         $ch=curl_init();
                         curl_setopt($ch,CURLOPT_URL,$url);
                         curl_setopt($ch,CURLOPT_USERPWD,$username.":".$password);
                         curl_setopt($ch,CURLOPT_POST,true);
                         curl_setopt($ch,CURLOPT_RETURNTRANSFER,1);
                         curl_setopt($ch,CURLOPT_SSL_VERIFYPEER,0);
                         curl_setopt($ch,CURLOPT_POSTFIELDS,$data);
                         $result=curl_exec($ch);
                         $httpcode=curl_getinfo($ch,CURLINFO_HTTP_CODE);
                         curl_close($ch);
    
                         echo $result;
    
                         echo $httpcode;
    
                        

    Send SMS Response.


    The IntouchSMS gateway will respond with json response. Below is the format of the response:

    
                         {
                                'details':[
                                        {
                                            'status':'P',
                                            'message':'Hello',
                                            'cost':18.0,
                                            'receipient':
                                            '+250785971082',
                                            'messageid':238254
                                         }
                                ],
                            'success':True,
                            'summary':{
                                            'message':'Hello',
                                            'balance':U1617.0,
                                            'cost':18.0,
                                            'totalmessages':1,
                                            'time':u'2015U08U27T16:19:58.398'
                                        }
                        }
    
    
                        

    A response will have a status code to indicate wether the send message request was successfull or not. The response will also include a description to indicate the reason why the message failed to be sent in case it's a failure.

    The status code will be one of the two below:

    200 Ok. No error encountered.

    400 Bad Request. Error encountered.


    Send SMS Status Request.

    A send SMS status request to the gateway to be sent should be encoded as a json string. This request is used to track the status of the message wether it has been delivered, errored, queued etc.

    Below are the necessary parameters to be passed with the URL.

    Parameter Data Format Description
    username string Username assigned to your account Intouch
    password string Password provided by Intouch for your account associated with your username.
    messageid string The message id returned in the send smsresponse.

    Python Code.


    
                            data={'messageid':$238254}
    
                            r=requests.post(
                                            'https://www.intouchsms.co.rw/api/getsmsstatus/.json',
                                             data,auth=(username,password)
                                            )
    
                            print (r.json(),r.status_code)
                            print r.status_code
    
                        

    PHP Code.


    
                            $data=array(
                                        "messageid"=>"223750",
                                       );
    
                            $url="https://www.intouchsms.co.rw/api/getsmsstatus/.json";
                            $data=http_build_query($data);
                            $username="username";
                            $password="password";
    
                            $ch=curl_init();
                            curl_setopt($ch,CURLOPT_URL,$url);
                            curl_setopt($ch,CURLOPT_USERPWD,$username.":".$password);
                            curl_setopt($ch,CURLOPT_POST,true);
                            curl_setopt($ch,CURLOPT_RETURNTRANSFER,1);
                            curl_setopt($ch,CURLOPT_SSL_VERIFYPEER,0);
                            curl_setopt($ch,CURLOPT_POSTFIELDS,$data);
                            $result=curl_exec($ch);
                            $httpcode=curl_getinfo($ch,CURLINFO_HTTP_CODE);
                            curl_close($ch);
    
                            echo $result;
    
                            echo $httpcode;
                            

    Send SMS Status Response.


    The IntouchSMS gateway will respond with json response.

     
                            {
                                'results':{
                                    'status':'D',
                                    'created':'27U08U201504:16:19:58',
                                    'time':u'27U08U201504:16:41:47'
                                 },
                                'success':True
                            }
    
                        

    Meaning of Statuses returned by the SEND SMS status response:
    P - Message still being processed.
    D - Message has been delivered successfully.
    Q - Message is still in Queue.
    E - Message has Errored.
    S - Message has been sent to the carrier for Delivery
    U - Message Unsent by the carrier.