Callbacks (WebHooks)

Callbacks are notifications that you 've asked Routee to send back to you (well, in your web service).

There are two type of callbacks:

Voice Messaging Callbacks##

Voice callbacks are generated when the status of a Voice message is changing. They can be used either when sending only one Voice message or a campaign.

Your callback service will receive a POST HTTP request with the following request body for an individual message progress of the Voice campaign:

{
  "messageId": "string",
  "campaignTrackingId": "string",
  "to": "string",
  "groups": [
    "string"
  ],
  "campaignName": "string",
  "from": "string",
  "country": "string",
  "applicationName": "string", 
  "price": "number",
  "originatingService": "string",
  "status": {
    "name": "string",
    "updatedDate": "string"
  },
  "direction": "string",
  "audioMessage": {
    "text": "string",
    "language": "string",
    "gender": "string"
  },
  "fileURL": "string",
  "hangupDelay": "number",
  "respectQuietHours": "boolean",
  "duration": "number",
  "createdAt": "date",
  "chargeInterval": "number"
}

KEY	DESCRIPTION
messageId	The trackingId of the Voice message.
campaignTrackingId	The trackingId of the campaign.
to	The recipient of the Voice message (in E.164 format).
from	The senderId of the Voice 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 Voice Campaign.
status	The full status object of the Voice message.
status.name	The status name of the Voice message.
status.updatedDate	The date of the last status change of the Voice.
applicationName	The name of the application that was used to send this message.
price	The cost of the Voice.
direction	The direction of the Voice.
originatingService	The service that sent this message.
audioMessage.text	The message that was sent.
audioMessage.gender	The gender of the voice message to be played. VALUES: "male", "female".
audioMessage.language	The language of the voice message to be played. VALUES: "en-US", "de-DE", "fr-FR", "it-IT", "pt-BR", "es-ES", "es-LA", "en-GB", "el-GR", "bg-BG", "pl-PL", "hu-HU", "sv-SE".
fileURL	The Url that was sent.
hangUpDelay	The time to wait for the call to be answered
respectQuietHours	Indicates if the call should respect the quiet hours, default value: false.
createdAt	The time the message was created.
chargeInterval	The time interval used for charging this voice message (in seconds).

Voice Campaign Callback##

When used for a voice 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 Voice messages, changes status (OnChange).
Your callback service will receive a POST HTTP request with the following request body:

{
  "trackingId": "string",
  "name": "string",
  "totalRecipients": "string",
  "campaignStatus": "string",
  "messageStatuses": {
    "Unknown": "string",
    "Queued": "string",
    "Initiated": "string" ,
    "Ringing": "string" ,
    "InProgress": "string" ,
    "Completed": "string",
    "Busy": "string",
    "NoAnswer": "string",
    "Failed": "string" 
  },
  "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 Voice per message status.
callbackInfo	Defines the notification callback information for the progress of the bulk send out - campaign
callbackInfo.url	The URL that will be called when an update occurs
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 a Voice message is changing status (or a percentage in campaign callback).

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

Be careful when you enable Voice 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 Voice message is changing status. Depending on the number of recipients this will end up in a large amount of requests.

👍
Callback retry policy
When Routee POSTs back to your service, an HTTP 200 OK response must be returned within 2 seconds. If Routee doesn't receive a 200 OK response within 2 seconds will drop the connection and will try to POST again (up 12 retries for 24 hours max) with the following retry policy after the initial callback attempt:
1st retry: 30 sec
2nd retry: 1 minute
3rd retry: 2 minutes
4th retry: 5 minutes
5th retry: 10 minutes
6th retry: 15 minutes
7th retry: 30 minutes
8th retry: 1 hour
9th retry: 2 hours
10th retry: 4 hours
11th retry: 8 hours
12th retry: 24 hours

🚧
Whitelist IP for callback service
Whitelist all the IPs that resolve to the following domain:
callbacksallow.routee.net
in order to be able to receive callback requests from Routee

Callbacks (WebHooks)

Voice Messaging Callbacks##

Voice Campaign Callback##

Callback Strategy##

👍
Callback retry policy

🚧
Whitelist IP for callback service

Voice Messaging Callbacks##

Voice Campaign Callback##

Callback Strategy##

👍Callback retry policy

🚧Whitelist IP for callback service

👍
Callback retry policy

🚧
Whitelist IP for callback service