How to receive inbound Voice calls

With the numbers API, you are able to rent a new number and receive inbound Voice calls from your clients.

In order to receive your inbound Voice calls, you will have to define the "voiceInboundStrategy" by setting a valid "dialplanUrl". You are able to do so when you rent or update a number that supports Voice service.

Routee will forward your calls to the dialplanUrl.
You will receive a POST HTTP request with the following request body:

  "messageId": string,
  "conversationTrackingId": string,
  "from": string,
  "to": string
messageIdThe trackingId of the Voice message.
conversationTrackingIdThe trackingId of the conversation.
fromThe sender of the call.
toYour number that receives the call.

The response of this request should be a valid dialplan: an array of action Verbs (PLAY, SAY, DIAL, COLLECT), in JSON format.
You can create custom dialplans, by using combinations of these verbs, according to your needs. This is what your users, representatives, existing or potential customers, will hear when they call your number. Your audience is also able to interact with your system through the use of DTMF tones. According to the received DTMF tones, you can change dynamically the dial plan of the call (eg connect your client with the requested department, play a prerecorded voice message, give instructions by using Text to Speech).

For example, you could set your "dialplanUrl" to return a response as below:

    "verbs": [
        "type": "SAY",
        "message": {
          "text": "Hello. You have called Routee's support. We will connect you shortly. Please wait.",
          "gender": "male",
          "language": "en-US"
        "type" : "DIAL",
        "from" : "3069xxxxxxx",
        "to" : {
          "phone" : "+3069xxxxxxxx"

So, once a user calls your number, he will hear the message and then connect with the phone you have set.

You can check here for more information about dialplan verbs.