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

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

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

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

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

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

👍

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