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.
- Select ‘Account Settings’ in the menu
- Go to section ‘Forwarding’
- Add a valid URL for ‘Post sent items to URL’
- Add a valid URL for ‘Post replies to URL’
- 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.
| 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 POST
The API will post a URL, similar to the following example, to a webpage, containing information about the received short code messages.
| 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 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.
| 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 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.
Updated about 4 years ago