Voice Calling API

Messagebird’s Voice Calling API enables VoIP features for your web application to make, receive, and monitor voice calls from a MessageBird voice-enabled virtual mobile number to and from any country around the world through a REST API.

The Voice Calling API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization. Request and response payloads are formatted as JSON using UTF-8 encoding and URL encoded values.

Looking for a VoIP tool but not a developer? Check out SIP Trunking on your MessageBird Dashboard.

If you are looking for specific documentation for a step you can directly jump to callflow step documentation.

Requests

API Endpoint

All URLs referenced in MessageBird's Voice Calling API documentation have the base URL in the code snippet on the right side:

https://voice.messagebird.com

Available HTTP methods

The MessageBird API uses HTTP verbs to understand if you want to read (GET), delete (DELETE), create (POST) or update (PUT) an object. When your web application cannot do a PUT, POST or DELETE, we provide the ability to set the method through the query parameter _method.

GET /call-flows/
POST /call-flows/
GET /call-flows/{id}
PUT /call-flows/{id}
DELETE /call-flows/{id}
GET /call-flows/{id}/numbers
POST /call-flows/{id}/numbers
PUT /call-flows/{id}/numbers
POST /calls/
GET /calls/
GET /calls/{callID}
PUT /calls/{callID}
DELETE /calls/{callID}
POST /calls/{callID}/{destination}
GET /calls/{callID}/legs
GET /calls/{callID}/legs/{legID}
DELETE /legs/{legID}
POST /legs/{legID}/hold
POST /legs/{legID}/unhold

GET /calls/{callID}/legs/{legID}/recordings
GET /recordings/{recordingID}
GET /recordings/{recordingID}.wav
# DEPRECATED:
GET /calls/{callID}/legs/{legID}/recordings/{recordingID}
GET /calls/{callID}/legs/{legID}/recordings/{recordingID}.wav

GET /recordings/{recordingID}/transcriptions
POST /recordings/{recordingID}/transcriptions
GET /transcriptions/{transcriptionID}
GET /transcriptions/{transcriptionID}.txt

# DEPRECATED:
GET /calls/{callID}/legs/{legID}/recordings/{recordingID}/transcriptions
GET /calls/{callID}/legs/{legID}/recordings/{recordingID}/transcriptions/{transcriptionID}
GET /calls/{callID}/legs/{legID}/recordings/{recordingID}/transcriptions/{transcriptionID}.txt
POST /calls/{callID}/legs/{legID}/recordings/{recordingID}/transcriptions

GET /webhooks/
GET /webhooks/{id}
POST /webhooks/
PUT /webhooks/{id}
DELETE /webhooks/{id}

POST/PUT

POST and PUT requests to the API should contain a JSON-formatted payload in the request body.

JSON Request Payload Example

{
  "steps": [
    {
      "id": "foo",
      "action": "transfer",
      "options": {
        "destination": "31612345678"
      }
    },
    {
      "id": "bar",
      "action": "hangup"
    }
  ]
}

Voice Calling API authentication

MessageBird's Voice Calling API uses API keys to authenticate requests. You can view and manage your API keys in your MessageBird dashboard

Test API keys have the prefix test_ and live API keys have the prefix live_

With each API call, you will need to set request headers including your access key to authenticate yourself.

Errors

Codes in the 2xx range indicate that a request was successfully processed and codes in the 4xx range indicate that there was an error that resulted from the information sent (e.g. authentication, no balance or a missing or wrong parameter).

In case of an error, the body of the response includes a json formatted response that tells you exactly what is wrong.

Attributes

Error Object Example

{
    "errors": [
      {
        "description": "The 'steps' parameter is required.",
        "code": 11
      }
    ]
  }

Limits

POST and PUT requests to the API should contain a JSON-formatted payload of less than 64KB in the request body.

HTTP status codes

MessageBird uses standard HTTP status codes to indicate success or failure of an API request.

Error codes (deprecated)

The following error codes have been deprecated in favor of relying on the status codes listed above.

Call flows

A call flow describes the flow of operations (steps) to be executed when handling an incoming call. Call flows can be assigned to multiple numbers. A number in this context is a purchased number that can be called on the traditional phone network. Each object in the steps array in a call flow describes an operation that executes during a call, e.g. transferring a call or playing back an audio file. The call flow must not exceed 32KB.

URI

https://voice.messagebird.com/call-flows

Available HTTP Methods

GET /call-flows/
POST /call-flows/
GET /call-flows/{id}
PUT /call-flows/{id}
DELETE /call-flows/{id}
GET /call-flows/{id}/numbers
POST /call-flows/{id}/numbers
PUT /call-flows/{id}/numbers

The call flow object

This is an object representing a voice call flow at MessageBird.com.

Attributes

Call Flow Object Example

{
  "id": "de3ed163-d5fc-45f4-b8c4-7eea7458c635",
  "record": true,
  "steps": [
    {
      "id": "3538a6b8-5a2e-4537-8745-f72def6bd393",
      "action": "transfer",
      "options": {
        "destination": "31612345678"
      },
    }
  ],
  "createdAt": "2017-03-06T13:34:14Z",
  "updatedAt": "2017-03-06T13:34:14Z"
}

List all call flows

This request retrieves a listing of all call flows.

Response

If successful, this request will return an object with a data, _links and pagination properties.

If the request failed, an error object will be returned.

The data property is an array of call flow objects, can be null if there are no call flows. The _links property is an object with HATEOAS links related to the object listing. The pagination property is an object with details about the result page count, total count, and pagination numbers.

Definition

GET https://voice.messagebird.com/call-flows

Example request

curl -X GET "https://voice.messagebird.com/call-flows" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"

Example response

{
  "data": [
    {
      "id": "de3ed163-d5fc-45f4-b8c4-7eea7458c635",
      "record": false,
      "steps": [
        {
          "id": "3538a6b8-5a2e-4537-8745-f72def6bd393",
          "action": "transfer",
          "options": {
            "destination": "31612345678"
          }
        }
      ],
      "createdAt": "2017-03-06T13:34:14Z",
      "updatedAt": "2017-03-06T13:34:14Z",
      "_links": {
        "self": "/call-flows/de3ed163-d5fc-45f4-b8c4-7eea7458c635"
      }
    }
  ],
  "_links": {
    "self": "/call-flows?page=1"
  },
  "pagination": {
    "totalCount": 1,
    "pageCount": 1,
    "currentPage": 1,
    "perPage": 10
  }
}

Viewing a call flow

This request retrieves a call flow resource.

The single parameter is the unique ID that was returned upon creation.

Required parameters

Response

If successful, this request will return an object with a data property, which is an array that has a single call flow object. If the request failed, an error object will be returned.

Definition

GET https://voice.messagebird.com/call-flows/{callflowID}

Example request

curl -X GET https://voice.messagebird.com/call-flows/de3ed163-d5fc-45f4-b8c4-7eea7458c635 \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"

Example response

{
  "data": [
    {
      "id": "de3ed163-d5fc-45f4-b8c4-7eea7458c635",
      "record": false,
      "steps": [
        {
          "id": "3538a6b8-5a2e-4537-8745-f72def6bd393",
          "action": "transfer",
          "options": {
            "destination": "31611223344"
          }
        }
      ],
      "createdAt": "2017-03-06T13:34:14Z",
      "updatedAt": "2017-03-06T15:02:38Z",
    }
  ],
  "_links": {
    "self": "/call-flows/de3ed163-d5fc-45f4-b8c4-7eea7458c635"
  }
}

Creating a call flow

Using JSON

Callflow parameters

Response

If successful, this request will return an object with a data property, which is an array that has a single call flow object. If the request failed, an error object will be returned.

Definition

POST https://voice.messagebird.com/call-flows

Example request

curl -X POST https://voice.messagebird.com/call-flows \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json" \
  -d $'{
    "record": true,
    "steps": [
      {
        "options": {
          "destination": "31612345678"
        },
        "action": "transfer"
      }
    ]
  }'

Example response

{
  "data": [
    {
      "id": "de3ed163-d5fc-45f4-b8c4-7eea7458c635",
      "record": true,
      "steps": [
        {
          "id": "2fa1383e-6f21-4e6f-8c36-0920c3d0730b",
          "action": "transfer",
          "options": {
            "destination": "31612345678"
          }
        }
      ],
      "createdAt": "2017-03-06T14:52:22Z",
      "updatedAt": "2017-03-06T14:52:22Z"
    }
  ],
  "_links": {
    "self": "/call-flows/de3ed163-d5fc-45f4-b8c4-7eea7458c635"
  }
}

Steps

Each step object describes an action that can be taken in a call flow and holds the parameters for that action.

If you are looking for specific documentation for a step you can directly use the links below:

• say step JSON, XML
• play step JSON, XML
• transfer step JSON, XML
• maskedTransfer step JSON
• pause step JSON, XML,
• record step JSON, XML
• fetchCallFlow step JSON, XML
• sendKeys step JSON, XML
• hangup step JSON, XML
• Answering Machine Detection / AMD
• Conditionals

The say step

The say step pronounces a text message with a given voice and language.

Parameters

Options object

{
    "steps": [
      {
        "action": "say",
        "options": {
          "payload": "Hello, I am a robot. This is an example message.",
          "language": "en-GB",
          "voice": "male",
          "repeat": 2
        },
        "onKeypressGoto": "bar",
        "onKeypressVar": "foo"
      }
    ]
  }

Supported languages

The table below contains a list of locales with the options for the voice attribute of the say step. M denotes male and F female.

If a voice provider is temporarily unavailable and it is necessary, we will automatically choose another text-to-speech engine to pronounce the provided text. This could temporarily change the type of voice and character of the pronunciation.

Supported languages by Engine

Not all text to speech engines provide the same combinations of languages and voices. By default we will automatically select an engine if one is not specified, or will fall back to a suitable engine if the one provided in the Say step does not have the appropriate language & voice combination. Before selecting a different engine, a different voice will be attempted first when the engine option is specified.

The record step

The record step initiates an audio recording during a call, e.g. for capturing a user response. The recording can be stopped by using one or more of the attributes maxLength, timeout, finishOnKey.

Parameters

Options object

{
    "steps": [
      {
        "action": "record",
        "options": {
          "onFinish": "https://messagebird.com/onfinish",
          "timeout": 10,
          "maxLength": 30,
          "finishOnKey": "any",
          "transcribe": true,
          "transcribeLanguage": "en-UK"
        }
      }
    ]
  }

The transfer step

The transfer step transfers the call to a different phone/server. When used with the steps option listed below, the transfer will be completed to the destination only after finishing those steps. For more information on this option and how to use it, see our guide on Call Screening.

Parameters

Options object

{
    "steps": [
      {
        "action": "transfer",
        "options": {
          "destination": "31612345678",
          "record": "both"
        }
      }
    ]
  }

The maskedTransfer step

The maskedTransfer step is used on inbound flows to create a number-masking call. When one of the numbers in the numbers array option is matched to the calling party (source) the call is transferred to the other number in this array. However the Calling Line Identity will be replaced with the number that this flow is connected to. If there is no match no transfer will happen and the inbound call will fail. For more masking options see Masking numbers.

Parameters

Options object

{
    "steps": [
      {
        "action": "maskedTransfer",
        "options": {
          "numbers": ["31612345678", "31612345679"]
        }
      }
    ]
  }

Masking numbers

There are three ways to mask numbers for calls you place using the Voice API depending on your use case. In all scenarios two parties A and B would be able to talk to each other without knowing each other's numbers but using a Proxy Number from Messagebird denoted as N.

1. maskedTransfer step
2. transfer step with mask option
3. transfer step with source option

maskedTransfer step

Use a maskedTransfer step in the callflow of an incoming call to recognize and link two parties together without exposing their numbers to each other. e.g. If N is a Proxy number you own and A and B are numbers that should talk to each other but remain anonymous you could achieve it by letting them both call number N, and setting the callflow of N to be the following:

{
  "steps": [
    {
      "action": "maskedTransfer",
      "options": {
        "numbers": ["A", "B"]
      }
    }
  ]
}

In that example if A calls N then B will receive the transferred call as coming from N. Equally, if B calls N then A would receive the call as coming from N.

transfer step with mask option

Set the mask option to true for a transfer step when you want any incoming call to be forwarded to the transfer destination appearing to come from the same number that they originally dialed-in. e.g. If N is a Proxy number you own and A called N you can transfer the call to B with both sides being anonymous by setting the callflow of N to be the following:

{
  "steps": [
    {
      "action": "transfer",
      "options":{
        "destination": "B"
      }
    }
  ]
}

This option is similar to the maskedTransfer above but behaves the same without requiring the caller's number in the callflow. Note that this convenience method does not work well for calls originated by the API but only incoming calls.

transfer step with source option

Set the source option for a transfer step when you want to have full control over how the transfer leg appears to the transfer destination. This is the suggested way when placing a call to party A and then transferring them to party B but requiring anonymity of the two parties. e.g. In the following example A is receiving a call from N and then gets transferred to B. B will see the caller of the transfer leg being C (you may also opt for reusing the number N as C).

{
  "destination": "A",
  "source": "N",
  "steps": [
    {
      "action": "transfer",
      "options":{
        "destination": "B",
        "source": "C"
      }
    }
  ]
}

The hangup step

The hangup step ends the call.

Parameters

{
    "steps": [
      {
        "action": "hangup"
      }
    ]
  }

The fetchCallFlow step

The fetchCallFlow step fetches a new call flow from the supplied URL and transfers control to that flow, see Dynamic call flows.

Parameters

Options object

{
    "steps": [
      {
        "action": "fetchCallFlow",
        "options": {
          "url": "https://messagebird.com/fetchcallflow",
          "timeout": 30
        }
      }
    ]
  }

The play step

The play step plays back an audio file.

Parameters

Options object

{
    "steps": [
      {
        "action": "play",
        "options": {
          "media": "https://messagebird.com/play.wav"
        },
        "onKeypressGoto": "bar",
        "onKeypressVar": "foo"
      }
    ]
  }

Supported Media Types

Messagebird supports media types with the following file extensions .wav, .mp3, .g722, .gsm, .alaw, .al, .pcm, .ulaw, .raw, .sln, .sln12, .sln16, .sln24, .sln32, .sln44, .sln48, .sln96, .sln192, .vox.

Play Step Media Caching

By default, the audio file provided in the media is cached on Messagebird's media server before being played for the user. We do this in order to ensure that the audio file is played more quickly for your users and will result in higher resilience when playing audio in the event that the source file's media server experiences latency or downtime. Messagebird's media server has a cache retention period of 7 days, however we will respect the caching policy as dictated by the source file. To make the most of (or override) Messagebird's caching, note that we preserve the following headers for the media file: Cache-Control, Max-Age, Etag, and Last-Modified.

The pause step

The pause step pauses (silently) for a given duration.

Parameters

Options object

{
    "steps": [
      {
        "action": "pause",
        "options": {
          "length": "2s"
        },
        "onKeypressGoto": "bar",
        "onKeypressVar": "foo"
      }
    ]
  }

The sendKeys step

The sendKeys step sends DTMF signals during a call.

Parameters

Options object

{
    "steps": [
      {
        "action": "sendKeys",
        "options": {
          "keys": "*101#",
          "duration": 500,
          "interval": 2000
        }
      }
    ]
  }

Using XML

Besides JSON, you can also create an XML based call flow. They offer the same features as JSON, but can be more readable, especially when using step conditions.

To use XML when creating a call flow, the Content-Type HTTP header needs to be set to application/xml. Upon creation, an XML call flow is parsed into a flat array of steps. Any conditional structures with If are ket intact.

By default, steps are sequentially executed. Using the onKeypressGoto attribute in tags, you can alter flow control by skipping to a specific part of the call flow.

XML Element tags and attributes are case-sensitive. For example, using <play> instead of <Play> will give an error.

Example request

curl -X POST https://voice.messagebird.com/call-flows \
   -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
   -H "Content-Type: application/xml" \
   -d $'<?xml version="1.0" encoding="UTF-8"?>
<CallFlow>
  <Say language="en-US" voice="male" onKeypressVar="foo" onKeypressGoto="bar">Hello! Press 1, 2, or 3 to continue.</Say>
  <Pause length="10s" onKeypressVar="foo" onKeypressGoto="bar"/>
  <Say language="en-US" voice="male">You did not press anything. Good bye!</Say>
<Hangup/>

    <If id="bar" condition="foo == 1">
        <Say language="en-US" voice="male">You pressed 1. Bye!</Say>
        <Hangup/>
    </If>
    <If condition="foo == 2">
        <Say language="en-US" voice="male">You pressed 2. Bye!</Say>
        <Hangup/>
    </If>
    <If condition="foo == 3">
        <Say language="en-US" voice="male">You pressed 3. Bye!</Say>
        <Hangup/>
    </If>

    <Say language="en-US" voice="male">You pressed something, but it was not 1, 2 or 3. Bye!</Say>
</CallFlow>'

Example response

{
  "data": [
    {
      "id": "9e568623-a158-45f5-aa71-d877349abafc",
      "record": false,
      "steps": [
        {
          "id": "800a9655-92b0-4f80-bdf7-63d5c7650ec6",
          "action": "say",
          "options": {
            "payload": "Hello! Press 1, 2, or 3 to continue.",
            "language": "en-US",
            "voice": "male"
          },
          "onKeypressGoto": "bar",
          "onKeypressVar": "foo"
        },
        {
          "id": "71090bab-0683-438b-af57-490d7cdb94c8",
          "action": "pause",
          "options": {
            "length": "10s"
          },
          "onKeypressGoto": "bar",
          "onKeypressVar": "foo"
        },
        {
          "id": "184019d3-5f58-4e7a-a770-cd1401440367",
          "action": "say",
          "options": {
            "payload": "You didn't press anything. Good bye!",
            "language": "en-US",
            "voice": "male"
          }
        },
        {
          "id": "3b903119-821e-4e4f-baa3-83beb898f427",
          "action": "hangup"
        },
        {
          "id": "bar",
          "action": "say",
          "options": {
            "payload": "You pressed 1. Bye!",
            "language": "en-US",
            "voice": "male"
          },
          "conditions": [
            {
              "variable": "foo",
              "operator": "==",
              "value": "1"
            }
          ]
        },
        {
          "id": "8570f016-c27c-44c1-9327-236df34684d3",
          "action": "hangup",
          "conditions": [
            {
              "variable": "foo",
              "operator": "==",
              "value": "1"
            }
          ]
        },
        {
          "id": "a5fadcfd-1c2a-4017-9e5a-72c5e4df8007",
          "action": "say",
          "options": {
            "payload": "You pressed 2. Bye!",
            "language": "en-US",
            "voice": "male"
          },
          "conditions": [
            {
              "variable": "foo",
              "operator": "==",
              "value": "2"
            }
          ]
        },
        {
          "id": "a144f0e6-3702-4990-a63e-27d497ef801b",
          "action": "hangup",
          "conditions": [
            {
              "variable": "foo",
              "operator": "==",
              "value": "2"
            }
          ]
        },
        {
          "id": "4c6f803b-2e2f-458d-94a6-6698d53b0cc7",
          "action": "say",
          "options": {
            "payload": "You pressed 3. Bye!",
            "language": "en-US",
            "voice": "male"
          },
          "conditions": [
            {
              "variable": "foo",
              "operator": "==",
              "value": "3"
            }
          ]
        },
        {
          "id": "a9bbba8b-ed1b-4fa4-bdae-85c668723103",
          "action": "hangup",
          "conditions": [
            {
              "variable": "foo",
              "operator": "==",
              "value": "3"
            }
          ]
        },
        {
          "id": "38eb5a4c-3a2a-4475-a056-e8ece4e57e17",
          "action": "say",
          "options": {
            "payload": "You pressed something, but it wasn't 1, 2 or 3. Bye!",
            "language": "en-US",
            "voice": "male"
          }
        }
      ],
      "createdAt": "2017-03-13T13:39:52Z",
      "updatedAt": "2017-03-13T13:39:52Z"
    }
  ],
  "_links": {
    "self": "/v1/call-flows/9e568623-a158-45f5-aa71-d877349abafc"
  }
}

The Transfer tag

The Transfer tag transfers the call to a different phone/server. The Transfer tag may be optionally used as a container for other tags (steps) that are executed for the destination number before the transfer is complete. Applicable tags for such flows include the Play, Say, Hangup, Pause and If tags. For more information on this functionality, please see our guide on Call Screening.

Parameters

The Say tag

The Say tag pronounces a text message with a given voice and language. The XML tag content should contain the text to pronounce. The maximum amount of characters for the payload is 3000.

Parameters

The Play tag

The Play tag plays back an audio file. The tag should not contain any content, only attributes.

Parameters

The Pause tag

The Pause tag pauses (silently) for a given duration. The tag should not contain any content, only attributes.

Parameters

The Record tag

The Record tag initiates an audio recording during a call, e.g. for capturing a user response. The tag should not contain any content, only attributes. The recording can be stopped by using one or more of the attributes maxLength, timeout, finishOnKey.

Parameters

Example

<CallFlow>
    <Say language="en-US" voice="male">
        Unfortunately we are not able to answer the phone right now. Please leave your name and number.
    </Say>
    <Record maxLength="120" timeout="3" transcribe="true" transcribeLanguage="en-US" />
    <Say language="en-US" voice="male">
        Thanks for calling, we will get back to you shortly.
     </Say>
    <Hangup/>
</CallFlow>

The SendKeys tag

The SendKeys tag sends the DTMF signals during a call.

It can be used to dial a number that is reachable via an extension number or to simulate the keypresses of a physical phone to walk through an IVR system.

Parameters

Example

curl -X POST https://voice.messagebird.com/calls \
  -H "Content-Type: application/json" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -d $'{
    "source": "31644556677",
    "destination": "31626146604",
    "callFlow": {
      "steps": [{
        "action": "sendKeys",
          "options": {
              "keys": "1234567890"
          }
        }]
      },
      "webhook": {
        "url": "https://example.com",
        "token": "foobar"
      }
  }'

The FetchCallFlow tag

The FetchCallFlow tag fetches a call flow from a remote URL. See: Dynamic call flows. Any steps following this tag are ignored. The tag should not contain any content, only attributes.

Parameters

The Hangup tag

The Hangup tag ends the call. This is an empty-element tag that has no attributes.

The If tag

The If tag is a container where the contents are other tags (steps) that are executed when the condition in the condition attribute evaluates to true.

Parameters

Example

<CallFlow>
    <Say language="en-US" voice="male" onKeypressVar="foo" onKeypressGoto="bar">Hello! Press 1, 2, or 3 to continue.</Say>
    <Pause length="10s" onKeypressVar="foo" onKeypressGoto="bar"/>
    <Say language="en-US" voice="male">You did not press anything. Good bye!</Say>
    <Hangup/>

    <If id="bar" condition="foo == 1">
        <Say language="en-US" voice="male">You pressed 1. Bye!</Say>
        <Hangup/>
    </If>
    <If condition="foo == 2">
        <Say language="en-US" voice="male">You pressed 2. Bye!</Say>
        <Hangup/>
    </If>
    <If condition="foo == 3">
        <Say language="en-US" voice="male">You pressed 3. Bye!</Say>
        <Hangup/>
    </If>

    <Say language="en-US" voice="male">You pressed something, but it wasn't 1, 2 or 3. Bye!</Say>
</CallFlow>

Updating a call flow

This request updates a call flow resource. The single parameter is the unique ID that was returned upon creation.

Required parameters

Optional parameters

Response

If successful, this request will return an object with a data property, which is an array that has a single call flow object. If the request failed, an error object will be returned.

Definition

PUT https://voice.messagebird.com/call-flows/{callflowID}

Example request

curl -X PUT https://voice.messagebird.com/call-flows/de3ed163-d5fc-45f4-b8c4-7eea7458c635 \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -d $'{
    "steps": [
      {
        "options": {
          "destination": "31611223344"
        },
        "action": "transfer"
      }
    ]
  }'

Example response

{
  "data": [
    {
      "id": "de3ed163-d5fc-45f4-b8c4-7eea7458c635",
      "record": false,
      "steps": [
        {
          "id": "3538a6b8-5a2e-4537-8745-f72def6bd393",
          "action": "transfer",
          "options": {
            "destination": "31611223344"
          }
        }
      ],
      "createdAt": "2017-03-06T13:34:14Z",
      "updatedAt": "2017-03-06T15:02:38Z"
    }
  ],
  "_links": {
    "self": "/call-flows/de3ed163-d5fc-45f4-b8c4-7eea7458c635"
  }
}

Deleting a call flow

This request deletes a call flow. The single parameter is the unique ID that was returned upon creation.

Required parameters

Response

If successful, this request will return an HTTP header of 204 No Content and an empty response. If the request failed, an error object will be returned.

Definition

DELETE https://voice.messagebird.com/call-flows/{callflowID}

Example request

curl -X DELETE https://voice.messagebird.com/call-flows/de3ed163-d5fc-45f4-b8c4-7eea7458c635 \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Assigning numbers to a call flow

To use a call flow for incoming calls to your number(s), you'll need to assign these numbers to the callflow first. This can be accomplished either by adding (using method POST) or replacing (using method PUT) the numbers for the callflow. Apart from this the two endpoints will behave the same with the same request and responses.

Required parameters

Response

If successful, this request will return an object with a data property, which is an array that has a single call flow object. If the request failed, an error object will be returned.

Definition

POST https://voice.messagebird.com/call-flows/{callflowID}/numbers
PUT https://voice.messagebird.com/call-flows/{callflowID}/numbers

Example request

# Add number to the call flow
  curl -X POST https://voice.messagebird.com/call-flows/de3ed163-d5fc-45f4-b8c4-7eea7458c635/numbers \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -d $'{
    "numbers": ["31611111111", "31622222222"]
  }'

  # Replace the numbers of the call flow
  curl -X PUT https://voice.messagebird.com/call-flows/de3ed163-d5fc-45f4-b8c4-7eea7458c635/numbers \
  -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
  -d $'{
    "numbers": ["31611111111", "31622222222"]
  }'

Listing numbers assigned to a call flow

This request retrieves a listing of all numbers currently assigned to a call flow.

Response

If successful, the request will return an object with a data, _links and pagination properties. If the request failed, an error object will be returned.

The data property is an array of number objects. The _links property is an object with HATEOAS links related to the object listing. The pagination property is an object with details about the result page count, total count, and pagination numbers.

Definition

GET https://voice.messagebird.com/call-flows/{callflowID}/numbers

Example request

curl -X GET "https://voice.messagebird.com/call-flows/de3ed163-d5fc-45f4-b8c4-7eea7458c635/numbers" \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"

Example response

{
  "data": [
    {
      "id": "13f38f34-7ff4-45b3-8783-8d5b1143f22b",
      "number": "31611111111",
      "callFlowId": "de3ed163-d5fc-45f4-b8c4-7eea7458c635",
      "createdAt": "2017-03-16T13:49:24Z",
      "updatedAt": "2017-09-12T08:59:50Z",
      "_links": {
        "self": "/numbers/13f38f34-7ff4-45b3-8783-8d5b1143f22b"
      }
    }
  ],
  "_links": {
    "self": "/call-flows/de3ed163-d5fc-45f4-b8c4-7eea7458c635/numbers?page=1"
  },
  "pagination": {
    "totalCount": 1,
    "pageCount": 1,
    "currentPage": 1,
    "perPage": 10
  }
}

Answering Machine Detection (AMD)

Answering Machine Detection (AMD) allows you to determine whether the receiving side of an outgoing call is detected to be a machine (voicemail or fax). Depending on the outcome of the detection you can choose to either hangup the call (ifMachine: "hangup") or to wait until the answering machine has finished talking (ifMachine: "delay") before executing any further steps.

AMD on API originated calls

To enable AMD on the first leg of your callflow (for example a call with a simple callflow of a say step) you need to add an ifMachine attribute in the options of its first step. For available values see the callflow object.

{
  "destination": "31612345678",
  "source": "31644556677",
  "callFlow": {
    "steps": [
      {
        "action": "say",
        "options": {
          "payload": "Testing hangup on AMD for OTP. Call should hangup",
          "voice": "male",
          "language": "en-GB",
          "ifMachine": "hangup"
        }
      }
    ]
  },
  "webhook": {
    "url": "https://some-callback-url"
  }
}

AMD on transfer steps

For transfers (where the primary leg is being connected to a secondary leg towards another number) the same options can be set directly as options of the transfer step. For available values see the callflow object.

{
  "destination": "31612345678",
  "source": "31644556677",
  "callFlow": {
    "steps": [
      {
        "action": "say",
        "options": {
          "payload": "Testing hangup on AMD for transfers. Call should hangup shortly after ringing.",
          "voice": "male",
          "language": "en-GB"
        }
      },
      {
        "action":"transfer",
        "options":{
          "destination":"31612345555",
          "ifMachine":"hangup"
        }
      }
    ]
  },
  "webhook": {
    "url": "https://some-callback-url"
  }
}

If the first step of the callflow happens also to be a transfer step the directions will only have effect for the transfer step. If you wish to have AMD detection for the first leg you are advised to use an intermediate step to host the AMD options such as a short "Pause" step.

Answering Machine Detection doesn't come without side-effects. The algorithm works by detecting if the callee answered with an initial silence of a few seconds or started speaking for an unreasonable period without acknowledgement of the other party. Since the callflow will be delayed until a decision is made, especially for transfers that might mean that a part of the call might not be heard by both parties and could lead to some confusion.

AMD events in webhook callbacks

The outcome of the Answering Machine Detection is also sent as a separate event in callbacks. For more information read the callback section.

The AMDCompleteEvent

This is an object representing an AMDComplete event.

Attributes

At the moment AMD configuration is limited to json callflows and XML callflows may only use the `IfMachine` attribute for Say steps.

Conditionals

Call flow steps can be programmed to be executed depending on which key is pressed in an IVR menu. This is a bit more straightforward and easy to code with XML as shown in the if tag but gets more complex when using JSON because there is no way of grouping actions together.

In JSON each step can have a conditions array of condition objects.

Condition object

Each action that needs to be executed under specific conditions must have them defined in the conditions option array. When looking for an action to execute next, the callflow will continue with the first action that follows the last executed step that either has all its conditions evaluated as true or has no conditions.

Let's consider the following example:

{
  "steps": [
    {
      "action": "say",
      "options": {
        "payload": "press 1 to talk to department A, press 2 to talk to department B",
        "language": "en-US",
        "voice": "male"
      },
      "onKeypressVar": "digitpressed",
      "onKeypressGoto": "transferdept"
    },
    {
      "action": "pause",
      "options": {
        "length": "5s"
      },
      "onKeypressVar": "digitpressed",
      "onKeypressGoto": "transferdept"
    },
    {
      "action": "say",
      "options": {
        "payload": "you didn't press anything. Hanging up",
        "language": "en-US",
        "voice": "male"
      }
    },
    {
      "action": "hangup"
    },
    {
      "id": "transferdept",
      "action": "say",
      "options": {
        "payload": "you are being transferred to department A",
        "language": "en-US",
        "voice": "male"
      },
      "conditions": [
        {
          "variable": "digitpressed",
          "condition": "==",
          "value": "1"
        }
      ]
    },
    {
      "action": "transfer",
      "options": {
        "destination": "316123456781"
      },
      "conditions": [
        {
          "variable": "digitpressed",
          "condition": "==",
          "value": "1"
        }
      ]
    },
    {
      "action": "say",
      "options": {
        "payload": "you are being transferred to department B",
        "language": "en-US",
        "voice": "male"
      },
      "conditions": [
        {
          "variable": "digitpressed",
          "condition": "==",
          "value": "2"
        }
      ]
    },
    {
      "action": "transfer",
      "options": {
        "destination": "35123123123"
      },
      "conditions": [
        {
          "variable": "digitpressed",
          "condition": "==",
          "value": "2"
        }
      ]
    },
    {
      "action": "say",
      "options": {
        "payload": "goodbye",
        "language": "en-US",
        "voice": "male"
      }
    }
  ]
}

In the scenario above the user is presented with an IVR (Interactive voice response) menu. They can choose to be transfered to one of the 2 departments available. If no key is pressed or the wrong key is pressed we'll say something different and hangup.

There are a few key points to pay attention to:

• We use the same onKeypressVar and onKeypressGoto parameters on both the say and the pause so keypresses during the say step and right after are treated equally.
• Right after these two prompting steps we have a say and a hangup step to catch the case where the user did not press anything.
• The step following the hangup has the id parameter set to transferdept which is the same value as the onKeypressGoto. This makes the callflow skip the hangup steps if any key is pressed.
• Each step after and including the step with id set to transferdept has a conditions array apart from the last step.
• onKeypressGoto does not mean that the step to go to will be executed as the step's conditions might not evaluate to true. For example if the user pressed 2 the steps responsible for transfering to department A will be skipped.
• If the user pressed 3 since all conditions are strictly checking against the values 1 and 2 the step to be executed will be the last one as that has no conditions set. After that the call will hangup as there are no more steps to execute.

Dynamic call flows

Call flows can be statically created as described in the Creating a call flow. However, you might want something dynamic to happen based on business logic inside your application or organization. For example: Transfer an incoming call to a 24/7 support line when the caller is a priority customer.

To achieve this, our platform can retrieve a call flow from your web service as a call is being received. Your web service can then dynamically provide the call flow to execute, based on the properties of the incoming call (e.g. the caller ID or the dialed number).

When there is a failure during the fetching of the call-flow, for example a time-out or a wrong attribute, you can look at the logs in the dashboard.

Setup

First, create a call flow with a fetchCallFlow step (as detailed above), passing the URL of your web service as a url step option.

Example request to create a fetch callflow

curl -X POST https://voice.messagebird.com/call-flows \
  -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
  -H "Content-Type: application/json" \
  -d $'{
    "steps": [
      {
        "options": {
          "url": "https://example.com"
        },
        "action": "fetchCallFlow"
      }
    ]
  }'

Usage

Next, incoming calls will trigger an HTTP request to the configured URL with the following parameters:

Parameters

In case the previous step is a Transfer or a MaskedTransfer step the variables parameter will contain these additional fields:

• TransferLegID: the UUID of the transfer leg;
• TransferLegStatus: the status of the transfer leg;
• TransferLegDuration: the duration in seconds of the transfer leg.

Example incoming request to your web service

GET /?callID=97f9b1d2-b8b4-4db7-8829-ec3e660d2cdb&destination=19027064857&firstLegDirection=incoming&source=%2B31611171210&variables=%7B%22testingvar%22%3A%222%22%7D HTTP/1.1
Host: example.com
Accept-encoding: gzip
User-Agent: Go-http-client/1.1
X-MessageBird-Signature: OomF7gSVo5TdL6mxFvdlYodiTnJtPaEk7V6czObUUI0=
Connection: keep-alive

When receiving an incoming HTTP request, your platform should respond with either an XML or JSON call flow (see: The call flow object). Additionally, the response should have a 200 OK status code, and a Content-Type HTTP header with application/xml or application/json as the value, based on what type of call flow you return.

Example HTTP Response Body (XML Call Flow)

<?xml version="1.0" encoding="UTF-8"?>
<CallFlow>
    <Say language="en-GB" voice="female">The quick brown fox jumped over the lazy dog.</Say>
    <Hangup/>
</CallFlow>

When a statically created call flow contains a `fetchCallFlow` step, the fetched call flow will be executed and overrides the previous call flow for the call. If a call flow contained steps after a `fetchCallFlow` step, those will not be executed.

Validation of signatures

Voice signature generation used for fetching dynamic call flows differs from both the signature generation used in Voice webhooks and the generic signature generation used by other MessageBird services

Each Dynamic Call Flow HTTP request is signed with a signature when provided with a token, a base64 encoded HMAC found in the X-MessageBird-Signature HTTP header. To ensure the callback is coming from the MessageBird platform, we strongly advise you to validate its signature by calculating the HMAC of the callback and base64 encoding it.

Using HMAC-SHA256, the HTTP QUERY PARAMS are the message and the optional token of the related fetchCallFlow step is the secret.

Signature simulation example

# Emulate the X-Messagebird-Signature generation from the command line using openssl and base64.

$ echo -n 'callID=97f9b1d2-b8b4-4db7-8829-ec3e660d2cdb&destination=19027064857&firstLegDirection=incoming&source=%2B31611171210&variables=%7B%22testingvar%22%3A%222%22%7D'| openssl dgst -sha256 -hmac "some-custom-token" -binary |base64
v3HpIXiFBDvwiwA4wwgRg6T85Vs7o74w8wAvkOoyDo8=