Callbacks (Webhooks)

Voice conversation status notifications

Callbacks are notifications that you've asked Routee to send back to you.

Status Callbacks

Your callback service will receive a POST HTTP request with the following request body for an individual voice conversation progress:

{
  "messageId": "string",
  "conversationTrackingId": "string",
  "to": "string",
  "from": "string",
  "status": {
    "name": "string",
    "updatedDate": "string"
  },
  "direction": "string",
  "originatingService": "string",
  "respectQuietHours": "boolean",
  "duration": "number",
  "price": "number"
}
KEYDESCRIPTION
messageIdThe trackingId of the voice message.
conversationTrackingIdThe trackingId of the voice conversation.
toThe recipient of the Call (in E.164 format).
fromThe initiator of the Call.
statusThe full status object of the voice conversation.
status.nameThe status name of the voice conversation.
status.updatedDateThe date of the last status change of the voice conversation.
directionThe direction of the voice conversation (Inbound or Outbound).
originatingServiceThe service that sent this message.
respectQuietHoursIndicates if the Call should respect the quiet hours, default value: false.
durationThe duration of the voice conversation.
priceThe cost of the voice conversation.

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

OnChange: A callback is sent every time a Voice message changes status

OnCompletion: A callback is sent only when a voice conversation has reached its final status.

Callbacks for Dialplan Handling

When a COLLECT verb with defined "eventUrl" is present in your dialplan, then you will receive another type of callback notifications, in order to handle the call according to the collected DTMF tones.

These callbacks are generated and sent when:

  • "submitOnHash" is true inside the COLLECT verb and Hash (#) is pressed.
  • A tone is pressed during a verb with "bargeIn" set to true.
  • The call has been completed.

Your callback service will receive a POST HTTP request with the following request body:

{
  "from": "+231xxxxxxx",
  "to": "+140xxxxxxxx",
  "messageId": "string",
  "conversationTrackingId": "string",
  "collectedTones": "string"
}
KEYDESCRIPTION
fromThe initiator of the call.
toThe recipient of the call.
messageIdThe trackingId of the voice message.
conversationTrackingIdThe trackingId of the voice conversation.
collectedTonesThe collected DTMF tones, separated by comma (eg "1,2,3").

In case Routee receives a valid dialplan as a response from the provided eventUrl of the COLLECT verb, the initial dialplan will be overwritten by the second one.

Machine Detection callbacks

When a "machineDetection" object with "Continue" strategy is present in your dialplan, then Routee will send a callback to the "eventUrl" that you defined in the "machineDetection" object. In this way you are informed about the machine detection status and you are able to change the dialplan.

When Routee detects that the call is answered by a machine, then a machine detection callback is sent and the execution of the dialplan is interrupted. As response to the callback request, Routee awaits a new valid dialplan.

Your callback service at "eventUrl" will receive a POST HTTP request with the following request body:

{
    "messageId": "string",
    "conversationTrackingId": "string",
    "detectMachineStatus": "string"
}
KEYDESCRIPTION
messageIdThe trackingId of the voice message.
conversationTrackingIdThe trackingId of the voice conversation.
detectMachineStatusIndicates if the call is answered by human or machine. Possible values: "HUMAN", "MACHINE", "UNKNOWN".

Callbacks for recorded files

The callbacks for recordings are sent once the recorded files are generated.
In order to record a conversation, you have to set the "record" parameter to "true" inside a DIAL verb.
Your callback service (you have to provide it as "recordingCallbackUrl" inside the DIAL verb) will receive a POST HTTP request with the following request body:

{
  "trackingId": "string",
  "conversationTrackingId": "string",
  "voiceTrackingIds": [
    "string",
    "string"
  ],
  "from": "string",
  "to": "string",
  "start": "string",
  "end": "string",
  "duration": "number",
  "format": "string",
  "url": "string"
}
KEYDESCRIPTION
trackingIdThe tracking Id of the recorded file.
conversationTrackingIdThe tracking Id of the voice conversation.
voiceTrackingIdsAn array with the tracking Ids of the voice messages related to the conversation.
fromThe initiator of the call.
toThe recipient of the call.
startThe start time of the recording (ISO-8601 date-time format).
endThe end time of the recording (ISO-8601 date-time format).
durationThe duration of the recording (in seconds).
formatThe format of the recorded file (WAV or MP3).
urlThe url to download the recorded file.

👍

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 the IP that resolves to the following domain:
callbacksallow.routee.net
in order to be able to receive callback requests from Routee