The best way to get immediate notification on the events like SMS delivery or incoming messages, is to set up callback URLs. We will notify this URL immediately after the event occurs and, if the call was unsuccessful, we will retry a few times later. We perform a GET request.

Callbacks can be set in several different places within your account.

  • In the SETTINGS section of your account
    Callbacks set there are the default for the account.
  • In the send-sms API call
    Callbacks for DLR and reply can be set as parameters when you make the send-sms call.
  • Forward to URL in Inbound Options for a dedicated virtual number (Reply Callback)
  • Forward to URL in Keyword Options (Reply Callback)Forward to URL in List Automation (List Action Callback)

Callback Priority

Which callback URL is notified is prioritised as follows. Duplicate callbacks will not be sent.

  1. send-sms call
  2. Forward to URL on feature
  3. Default URL in SETTINGS

If you are finding that a callback is not firing from SETTINGS or a Forward to URL. It is likely you have one set on the send-sms call.

Callback Retries

If we should not be able to reach your configured http callback endpoint, we will retry the attempt a maximum of 4 times with an increasing delay of 1 minute, 5 minute, 1 hour and finally 24 hours.

Delivery (DLR) Callback

DLR's or Delivery Receipts, are notifications received from the carriers relating to the success or otherwise of an attempted SMS Delivery. Your DLR Callback URL is the default URL we post incoming DLR's to. You can also set the DLR Callback URL separately for individual messages. This is done using a parameter on the send-sms call

Parameters we include in our delivery callback request:

message_idYour message ID
mobileRecipient mobile number
datetimeDate/time of delivery. UTC
statusdelivered - Delivered to handset
pending - No delivery report received from carrier. Allow up to 72hrs or use validity in send-sms call to process.
soft-bounce - Message was undeliverable due to handset switched off, out of range or other temporary deliverability issue.
hard-bounce - Handset was disconnected
user_idYour account ID

Example 12:10:00&status=delivered&user_id=123456

Reply Callback

Incoming SMS are broadly similar, with 2 subtly different forms:

  • SMS Replies: are messages received 'in response' to an SMS message sent by you. Responses can come in on both the System Shared Number Pool or any Dedicated Virtual Number, and will be posted to the Callback URL above if there was no URL set as a parameter in the send-sms call.
  • Inbound SMS: are messages that are received originating from a users mobile phone and are not in response to a message sent. Inbound SMS can only be received on a Dedicated Virtual Number and will only be posted to the Default URL supplied above.

Parameters we include in our reply callback request:

user_idYour account ID
message_idYour message ID
mobileSender’s mobile
longcodeThe virtual number message was sent to
datetime_entryDate/time that message was received. UTC
responseMessage text
response_idID assigned to incoming message
is_optoutOpt-out flag. ‘yes’ or ‘no’

Example is my reply&response_id=35566670&mobile=61438333061&longcode=61429997672&datetime_entry=2020-05-16 12:10:00&is_optout=no

Link Hits Callbacks

The default link hits callback URL is used to notify when a URL defined in a message is clicked.

Parameters we include in our link hits callback request:

list_idYour list ID
message_idYour message ID
mobileSender’s mobile
longcodeThe number message was delivered to
datetimeDate/time that the click was recorded
messageMessage text
user_idAccount ID
link_hitsLink hit count
firstnameFirstname of contact that clicked
lastnameLastname of contact that clicked

Example 13:23:46&firstname=Brad&lastname=Down&link_hits=1&list_id=3201749&longcode=TRANSMITSMS&message=This is a link hit callback test

List Action Callback

A notification for contacts added too, or removed from lists is available via the Forward to URL option in the AUTOMATION settings for a list.

Parameters we include in our list action callback request:

typeAdd or Delete
datetime_entryDate/time of action. UTC.
list_idID of list.
mobileMobile of number actioned
firstnameFirstname of contact
lastnameLastname of contact
Custom field 1-10Custom field names and values will be added also

Example[email protected]&Handset=iPhone 7&datetime_entry=2020-05-16 13:13:20&firstname=Harrison&lastname=Down&list_id=4026600&mobile=61447775960&type=delete