Contact Us

Setting up a Webhook - Templates to use

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:



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:

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:

  1. Message has expired
  2. Message is rejected
  3. Message has failed
  4. 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:

  1. Message has expired
  2. Message is rejected
  3. Message has failed
  4. 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"
}