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"
}

KEY

DESCRIPTION

messageId

The trackingId of the voice message.

conversationTrackingId

The trackingId of the voice conversation.

to

The recipient of the Call (in E.164 format).

from

The initiator of the Call.

status

The full status object of the voice conversation.

status.name

The status name of the voice conversation.

status.updatedDate

The date of the last status change of the voice conversation.

direction

The direction of the voice conversation (Inbound or Outbound).

originatingService

The service that sent this message.

respectQuietHours

Indicates if the Call should respect the quiet hours, default value: false.

duration

The duration of the voice conversation.

price

The 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"
}

KEY

DESCRIPTION

from

The initiator of the call.

to

The recipient of the call.

messageId

The trackingId of the voice message.

conversationTrackingId

The trackingId of the voice conversation.

collectedTones

The 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"
}

KEY

DESCRIPTION

messageId

The trackingId of the voice message.

conversationTrackingId

The trackingId of the voice conversation.

detectMachineStatus

Indicates 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"
}

KEY

DESCRIPTION

trackingId

The tracking Id of the recorded file.

conversationTrackingId

The tracking Id of the voice conversation.

voiceTrackingIds

An array with the tracking Ids of the voice messages related to the conversation.

from

The initiator of the call.

to

The recipient of the call.

start

The start time of the recording (ISO-8601 date-time format).

end

The end time of the recording (ISO-8601 date-time format).

duration

The duration of the recording (in seconds).

format

The format of the recorded file (WAV or MP3).

url

The 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