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.

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

Field

Description

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

Flash

Always 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

MsgCount

The number of message parts

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

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.

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

Field

Description

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 (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.

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

Field

Description

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

Campaign

This 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 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.