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


What’s Next