When utilising our API, we recommend the use of webhooks to receive back status updates and replies into your system. This article will detail some recommended templates you can use for this purpose, to return back all the relevant information. This will show 2 templates for both replies & status updates, depending on a URL encoded version or a JSON version.
Getting in Replies (MO’s) – URL Encoded
Go into Configuration > Webhooks > New Webhook.
In the top section:
- Event – Set this as SMS – Receive an SMS
- HTTP Method – Make this a GET
- URL – Enter in your webhook endpoint
Leave the headers blank and move to content. This is where you setup all the information you want returned to your webhook. Please note all of these are optional, so you can pick and choose which ones you want, but we do recommend them all.
Create 5 parameters and set them up with the following key and value combination:
Parameter Key |
Parameter value |
Description |
from |
$esc.url($!sourceAddress) |
The recipient mobile |
to |
$!esc.url($destinationAddress) |
Your SMS Broadcast dedicated number. If you do not have a dedicated number, this will return blank. |
message |
$esc.url($moContent) |
The content of the reply |
ref |
$!esc.url($!metadata.apiClientRef) |
Your custom ref in your API submission |
msgref |
$!esc.url($!metadata.apiSmsRef) |
The reference generated by us on submission |
Once setup, hit save webhook. This will create a string like the following:
https://webhook.site/0da5461e-07fc-4b19-80d3-bfa559e9e57e?from=$esc.url($!sourceAddress)&to=$!esc.url($destinationAddress)&message=$esc.url($moContent)&ref=($!metadata.apiClientRef)&msgref=($!metadata.apiSmsRef)
And an example of this populated is as follows:
https://webhook.site/0da5461e-07fc-4b19-80d3-bfa559e9e57e?from=%2B61400000000&message=Reply%205&msgref=%28971221653%29&ref=%281214%29&to=
Getting in Replies (MO’s) – JSON Encoded
Go into Configuration > Webhooks > New Webhook.
In the top section:
- Event – Set this as SMS – Receive an SMS
- HTTP Method – Make this a POST
URL – Enter in your webhook endpoint:
Leave the headers blank and move to content. This is where you setup all the information you want returned to your webhook. Please note all of these are optional, so you can pick and choose which ones you want, but we do recommend them all.
Create 5 parameters and set them up with the following key and value combination:
Parameter Key |
Parameter value |
Description |
from |
$esc.json($!sourceAddress) |
The recipient mobile |
to |
$!esc.json($destinationAddress) |
Your SMS Broadcast dedicated number. If you do not have a dedicated number, this will return blank. |
message |
$esc.json($moContent) |
The content of the reply |
ref |
$!esc.json($!metadata.apiClientRef) |
Your custom ref in your API submission |
msgref |
$!esc.json($!metadata.apiSmsRef) |
The reference generated by us on submission |
Once setup, hit save. The webhook page will show the creation, but you cannot see the JSON body. Below is an example of how the JSON structure will populate:
{
"from": "+61400000000",
"to": "",
"message": "Reply 8",
"ref": "12145",
"msgref": "971235068"
}
Getting in Delivery Status Updates (DR’s) – URL Encoded
Go into Configuration > Webhooks > New Webhook.
For events, we recommend you pick the following for status updates:
- Message has expired
- Message is rejected
- Message has failed
- Message is delivered
The method should be a GET and enter in your webhook:
Leave the headers blank and move to content. This is where you setup all the information you want returned to your webhook. Please note all of these are optional, so you can pick and choose which ones you want, but we do recommend them all.
Create 4 parameters and set them up with the following key and value combination:
Parameter Key |
Parameter value |
Description |
to |
$esc.url($!sourceAddress) |
The recipient mobile |
status |
$esc.url($status) |
The status of the message. Can be Delivered, Failed, Rejected, Expired. |
ref |
$!esc.url($!metadata.apiClientRef) |
Your custom ref in your API submission |
smsref |
$!esc.url($!metadata.apiSmsRef) |
The reference generated by us on submission |
Once setup, hit save webhook. This will create a string like the following:
https://webhook.site/0da5461e-07fc-4b19-80d3-bfa559e9e57e?to=$esc.url($!sourceAddress)&status=$esc.url($status)&ref=$!esc.url($!metadata.apiClientRef)&smsref=$!esc.url($!metadata.apiSmsRef)
Below is an example of this populated:
https://webhook.site/0da5461e-07fc-4b19-80d3-bfa559e9e57e?ref=12145&smsref=971245453&status=delivered&to=%2B61400000000
Getting in Delivery Status Updates (DR’s) – JSON Encoded
Go into Configuration > Webhooks > New Webhook.
For events, we recommend you pick the following for status updates:
- Message has expired
- Message is rejected
- Message has failed
- Message is delivered
The method should be a POST and enter in your webhook:
Leave the headers blank and move to content. This is where you setup all the information you want returned to your webhook. Please note all of these are optional, so you can pick and choose which ones you want, but we do recommend them all.
Create 4 parameters and set them up with the following key and value combination:
Parameter Key |
Parameter value |
Description |
to |
$esc.json($!sourceAddress) |
The recipient mobile |
status |
$esc.json($status) |
The status of the message. Can be Delivered, Failed, Rejected, Expired. |
ref |
$!esc.json($!metadata.apiClientRef) |
Your custom ref in your API submission |
smsref |
$!esc.json($!metadata.apiSmsRef) |
The reference generated by us on submission |
Hit save to create this. You won’t be able to see the JSON body once created, but below is an example of what would be returned:
{
"to": "+61488001112",
"status": "delivered",
"ref": "121452",
"smsref": "971254134"
}