Webhooks (Callbacks)

Dialplan URL

When an inbound call is coming to a virtual number which belongs to a Routee account, and the user has set a Dialplan URL on the number, an HTTP POST request with the payload of the call will be sent to this URL. At this point, Routee will wait for 3 seconds to get a Dialplan in JSON format as a response to be executed. If Dialplan is not valid or has not a valid format, Routee drops the connection and nothing happens.

{
    "messageId": "",
    "conversationTrackingId": "",
    "from": "",
    "to": ""
}

KEY

DESCRIPTION

messageId

The trackingId of the voice message.

conversationTrackingId

The trackingId of the voice conversation.

from

The initiator of the Call.

to

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

Inbound Voice Callback URL

During an inbound voice call, Routee provides information about its state. In order to get this payload information, the user has to set on his Routee virtual number an inbound Voice Callback Url. Every time the state changes, a payload will be sent to this URL. An example payload structure is shown below.

Example inbound voice callback Url:

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

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 (in seconds).

price

The cost of the voice conversation (in the currency of the account).

Status Callback Url

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

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.

Example status callback:

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

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 (in seconds).

price

The cost of the voice conversation.

COLLECT Verb eventURL

After the collected DTMF tones are gathered (this can be achieved in two different ways, either if the Dialplan is completed or with the bargeIn variable inside a PLAY or SAY verb) a payload which contains the DTMF, will be sent to the eventURL. At this point, Routee waits for a valid Dialplan in JSON format as a response. (Dialplan as a response at eventURL is not required, the user should use it, only if he needs to have a continuation at his flow or if he wants to interrupt the first Dialplan). If a valid Dialplan will be given the eventUrl Dialplan will overwrite the first one.

Example collect callback

{
  "from" : "SenderID",
  "to" : "+3069xxxxxxxx",
  "messageId": "string",
  "conversationTrackingId": "string",
  "collectedTones": "string"
}

KEY

DESCRIPTION

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").

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:

Example recorded callback

{
  "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.

Machine Detection eventURL

In case the "machineDetection" object is present in your request, Routee will try to detect (in 1-2 sec) if the call is answered by a human or a machine.
If a human is detected in an answered call, then the flow won't change. If a machine is detected and the strategy is ‘continue’, the execution of the Diaplan will be interrupted and a different Dialplan will be executed which is provided to Routee from the machine detection eventURL. Otherwise, if the strategy is hang up the call will be terminated.
Your callback service at "eventUrl" will receive a POST HTTP request with the following request body:

Example machine detection callback

{
    "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".

👍

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

🚧

IP WhiteListing

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