Callbaks (WebHooks)

Now that we have described the SMS and bulk messaging campaign statuses, we can see how callbacks work. In general, callbacks are notifications that you 've asked Routee to send back to you (well, in your web service).

You can check Routee Application Settings to learn how you can set the default Callback URL(s) of your application(s).

There are two type of callbacks:

SMS Callbacks

SMS callbacks are generated when the status of an SMS is changing, to inform you about the progress of your messages. They can be used either when sending one SMS or a bulk messaging campaign. Each part of a multipart SMS will generate a new payload. Your callback service will receive a POST HTTP request with the following request body:

{
   "messageId":"string",
   "smsId":"string",
   "campaignTrackingId":"string",
   "part":"number",
   "parts":"number",
   "label":"string",
   "to":"string",
   "from":"string",
   "country":"string",
   "operator":"string",
   "groups":[
      "string"
   ],
   "campaignName":"string",
   "status":{
      "name":"string",
      "reason":{
         "detailedStatus":"string",
         "description":"string"
      },
      "updatedDate":"string"
   },
   "message":"string",
   "applicationName":"string",
   "latency":"number",
   "parts":"number",
   "price":"number",
   "direction":"string",
   "originatingService":"string"
}
KEY
DESCRIPTION

messageId

The trackingId of the SMS (all the parts of a multipart SMS have the same messageId).

smsId

The unique id of each SMS part included in a message. If the message is multipart then these values will be different for each part.

campaignTrackingId

The trackingId of the campaign (if the SMS was send using the /sms/campaign resource).

part

The number of the current SMS part.

parts

The total number of SMS parts.

label

A generic label used for tagging the SMS.

to

The recipient of the SMS message (in E.164 format).

from

The senderId of the SMS message.

country

The country of the recipient.

operator

The operator of the recipient.

groups

All contact groups (tags) that this contact belongs to.

campaignName

The name of the SMS Campaign (if the SMS was part of a campaign).

status

The full status object of the SMS message.

status.name

The status name of the SMS message.

status.updatedDate

The date of the last status change of the SMS.

status.reason

The reason of the status

status.reason.detailedStatus

The detailed status.
Possible values: Sent, Delivered, Undelivered, Failed, Undelivered on Handset, Unknown Number, Roaming, Call Barred, Unknown Status, Carrier Violation

status.reason.description

The description of the detailed status

message

The message that was sent.

applicationName

The name of the application that was used to send this message.

latency

The overall delivery latency of the message.

parts

The total parts of the SMS that was sent.

price

The cost of the SMS.

direction

The direction of the SMS.

originatingService

The service that sent this message.

Bulk Messaging Campaign Callback

When used in a bulk campaign, the callback will be called when the campaign has received a final status (OnCompletion) or every time a total of 10% of the campaign SMSs, changes status (OnChange). Your callback service will receive a POST HTTP request with the following request body:

{
   "trackingId":"string",
   "name":"string",
   "totalRecipients":"number",
   "campaignStatus":"string",
   "messageStatuses":{
      "string":"number"
   },
   "callbackInfo":{
      "url":"string",
      "strategy":"string"
   }
}
KEY
DESCRIPTION

trackingId

The trackingId of the campaign

name

The name of the SMS campaign

totalRecipients

The number of recipients that participate in the campaign

campaignStatus

The status of the bulk campaign (see above)

messageStatuses

Defines the number of SMS per message status. Either Queued, Sent, Failed, Unsent, Delivered or Undelivered.

callbackInfo

Defines the notification callback information for the progress of the bulk send out - campaign

callbackInfo.url

The URL that Routee will POST to, each time your bulk send out - campaign status changes to one of the following: Scheduled, Queued, Sent, Running, Finished or Failed

callbackInfo.strategy

States when the URL will be called.
Choose one of the two options:
on every status change (OnChange)
or
when a final status arrives (OnCompletion)

Callback Strategy

For each callback type, you can define the callback strategy:

OnChange: A callback is sent every time an SMS is changing status (or a percentage in campaign callback).

OnCompletion: A callback is sent only when an SMS or a campaign has reached its final status.

Be careful when you enable SMS callbacks for a bulk messaging campaign, especially when you set the callback strategy to be OnChange. Routee will hit your web service every time an individual SMS is changing status. Depending on the number of the recipients this will end up in a large amount of requests.

HTTP Response

When Routee POSTs back to your service, an HTTP 200 OK response must be returned. If Routee doesn't receive a 200 OK response, it will try to POST again (up to 5 times).


Callbaks (WebHooks)