Webhooks (Web Services)

Configure a URL for posting replies and sent data

INTRODUCTION

The SMS API gateway can post SMS delivery status and replies, and shortcode messages to your server. Instead of polling for updates, the API can push this data to a server in real time.

Where do I set the URL for the API to post to?

Login to your SMS gateway provider's website, where you created your account.

  1. Select ‘Account Settings’ in the menu
  2. Go to section ‘Forwarding’
  3. Add a valid URL for ‘Post sent items to URL’
  4. Add a valid URL for ‘Post replies to URL’
  5. Save the changes.

How to Use
An accessible web page on a server is required for the API to send data to. The web page will process the received data. The web page can be created in any programming language and must be capable of reading data out of a URL, also known as the query string.
Your web page must output the word ‘True’ to the page. This will tell the API that the post was successfully received. Not returning ‘True’ will be seen as a permanent post failure and reposts will not be attempted.

Security
To improve your security, you may decide to limit the traffic allowed to your servers. Our posts will originate from the following IP addresses:

  • 84.22.178.192
  • 84.22.178.193
  • 62.233.96.216
  • 62.233.96.217

📘

Please ensure your servers are reachable from these addresses.

What will the API post do to my web page?
Sent items includes delivery statuses for sent SMS, replies to outgoing SMS and received short code messages.

SENT ITEMS (DLR’s) - URL POST

The API will post a URL, similar to the following example, to a web page, containing information about the sent item for a previously sent SMS.

http://yourdomain.com/sentitems.html?ID=9120243&EventID=1&Phonenumber=27000000001&DataType=Sms&Data=Sample+Message&Flash=False&SentDataTime=16%2fOct%2f2020+12%3a25%3a34&Status=DELIVRD&CustomerID=Test_v1FXTTJoG2EwT8NQg0hsYenL6qPhLqTFSXz3dZTZ7aP0tA2&MsgCount=1&GRPName=Test+group+name&GRPDesc=Test+group+description&NumberValue1=Test+value+1&NumberValue2=Test+value+2&NumberValue3=Test+value+3&NumberValue4=Test+value+4&NumberValue5=Test+value+5&NumberValue6=Test+value+6

FieldDescription
ID This is a unique value (integer) for this specific line item
EventID The eventid is the same id that was provided by the API for the original outgoing SMS batch
Phonenumber The number the message was sent to
DataType ‘SMS’ only
Data The message sent
FlashAlways set to False.

Deprecated but maintained for Backwards compatibility
SentDataTime The status date and time in the format ‘dd/MMM/yyyy HH:mm:ss’
Status Status can be ‘DELIVRD’, ‘UNDELIV’, ’EXPIRED’, ’UNKNOWN’
CustomerID This is a value that was passed in when you sent your data via the API
MsgCountThe number of message parts
SentMessageGRPNameThe name of the group the data was stored in. This will only be populated if the message was generated from the website
SentMessageGRPDescThe description of the group the data was stored in. This will only be populated if the message was generated from the website
NumberValue1The Value1 data of the number. This will only be populated if the message was generated from the website
NumberValue2The Value2 data of the number. This will only be populated if the message was generated from the website
NumberValue3The Value3 data of the number. This will only be populated if the message was generated from the website
NumberValue4The Value4 data of the number. This will only be populated if the message was generated from the website
NumberValue5The Value5 data of the number. This will only be populated if the message was generated from the website
NumberValue6The Value6 data of the number. This will only be populated if the message was generated from the website

The process will post the message and read the response (output HTML) of your page. You need to output the phrase ‘True’ into the HTML, otherwise the SMS gateway will post again. 5 retries are attempted.

We would suggest storing the ID along with your data and only updating your records if the ID is not present in your table.

Most clients will perform the matching based on the ‘customerid’ parameter.

SHORT CODE - URL POST

The API will post a URL, similar to the following example, to a webpage, containing information about the received short code messages.

http://yourdomain.com/shortcodeitems.html?ID=322004213&Message=Example+SC+Message&SC=12345&keyword=MatchedKeyword&mobile=27830123456

FieldDescription
ID The Short Code Message ID
Message The Message Sent
SC The Short Code
Keyword The matched keyword
Mobile The mobile number that sent the message

The process will post the message and read the response (output HTML) of your page. You need to output the phrase ‘True’ into the HTML, otherwise the SMS gateway will post again. 5 retries are attempted.

We would suggest storing the ID along with your data and only updating your records if the ID is not present in your table.

REPLIES - URL POST

The API will post a URL, similar to the following example, to a web page, containing information about the reply received for a previously sent SMS.

http://yourdomain.com/replyitems.html?IncomingID=5990992&Phonenumber=27000000001&IncomingData=Sample+response&IncomingDataTime=16%2fOct%2f2020+12%3a58%3a50&SentID=7823007&EventID=1&SentData=Sample+message&SentDataTime=16%2fOct%2f2020+12%3a58%3a50&CustomerID=Test_ceqPytLpx_wLXTNpZVIEUf8dknQjl8G0seitXwiXhHPUcw2&Campaign=Test+campaign+name&SentMessageGRPName=Test+group+name&SentMessageGRPDesc=Test+group+description&NumberValue1=Test+value+1&NumberValue2=Test+value+2&NumberValue3=Test+value+3&NumberValue4=Test+value+4&NumberValue5=Test+value+5&NumberValue6=Test+value+6

FieldDescription
IncomingID This is a unique value (integer) for this specific line item
Phonenumber The number the message was sent to
IncomingData Data received in the reply
IncomingDataTime When the message was received by the server in the format ‘dd/MMM/yyyy HH:mm:ss’
SentID This is a unique value (integer) for this specific outgoing line item
EventID The eventid is the same ID that was provided by the API for the original outgoing SMS batch
SentData The message content sent
SentDataTime The status date and time in the format ‘dd/MMM/yyyy HH:mm:ss’
CustomerID This optional variable can be an external user supplied reference
CampaignThis optional variable can be an external user supplied reference
SentMessageGRPName The name of the group the data was stored in. This will only be populated if the message was generated from the website
SentMessageGRPDesc The description of the group the data was stored in. This will only be populated if the message was generated from the website
NumberValue1 The Value1 data of the number. This will only be populated if the message was generated from the website
NumberValue2 The Value2 data of the number. This will only be populated if the message was generated from the website
NumberValue3 The Value3 data of the number. This will only be populated if the message was generated from the website
NumberValue4 The Value4 data of the number. This will only be populated if the message was generated from the website
NumberValue5 The Value5 data of the number. This will only be populated if the message was generated from the website
NumberValue6 The Value6 data of the number. This will only be populated if the message was generated from the website

HOW IS POSTING MANAGED BY THE API?

The process will post the message and read the response (output HTML) of your page. You need to output the phrase ‘True’ into the HTML. Not returning ‘True’ will be seen as a permanent post failure and reposts will not be attempted. Temporary post failures will be attempted 5 times.

We would suggest storing the ID along with your data, and only updating your records if the ID is not present in your table to handle multiple submissions of the same event.

What else should my webpage do?
Apart from outputting the phrase ‘True’, we also recommend the following:
The data you receive should be stored (cached/queued) and processed separately from the response given. Any complex processing, involving databases or other complex logic, could cause a timeout and you may not receive the posted data again.

Please use the customerid to match previously sent SMSes to the delivery receipts (DLRs) or replies.