Webhooks (HTTP)

Configure a URL for posting replies and sent data.

INTRODUCTION

The SMS API gateway can push SMS delivery statuses, 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 must process the received data as a GET request. 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 (GET)

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

https://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 (GET)

The API will push a URL, similar to the following example, to a web page, containing information about the received shortcode messages.

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

FieldDescription
IDThe Short Code Message ID
MessageThe Message Sent
SCThe Short Code
KeywordThe matched keyword
MobileThe 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 (GET)

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

https://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
IncomingIDThis is a unique value (integer) for this specific line item
PhonenumberThe number the message was sent to
IncomingDataData received in the reply
IncomingDataTimeWhen the message was received by the server in the format ‘dd/MMM/yyyy HH:mm:ss’
SentIDThis is a unique value (integer) for this specific outgoing line item
EventIDThe eventid is the same ID that was provided by the API for the original outgoing SMS batch
SentDataThe message content sent
SentDataTimeThe status date and time in the format ‘dd/MMM/yyyy HH:mm:ss’
CustomerIDThis optional variable can be an external user supplied reference
CampaignThis optional variable can be an external user supplied reference
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

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 web page 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.