Callbacks (Webhooks)

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

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

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

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

👍

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