Programmable Voice Calling

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

Notification icon

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

API Endpoint

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

API Endpoint

https://voice.messagebird.com

Available HTTP methods

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

Available HTTP Methods

GET /call-flows/
GET /call-flows/{id}
POST /call-flows/
PUT /call-flows/{id}
DELETE /call-flows/{id}
POST /calls/
GET /calls/
GET /calls/{callID}
GET /calls/{callID}/legs
GET /calls/{callID}/legs/{legID}
GET /calls/{callID}/legs/{legID}/recordings
GET /calls/{callID}/legs/{legID}/recordings/{recordingID}
GET /calls/{callID}/legs/{legID}/recordings/{recordingID}.wav
GET /calls/{callID}/legs/{legID}/recordings/{recordingID}/transcriptions
POST /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

Requests

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

JSON Request Payload Example

{
"title": "Example Call Flow",
"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.

When your application cannot send an Authorization header, you can use the GET parameter access_key to provide your access key.

HeaderDescriptionRequired
AuthorizationMust be in the form of AccessKey {accessKey}.Yes

Versioning

The Voice Calling API uses dated versioning. When backward-incompatible changes are made, a new version is released.

By default, all calls to the MessageBird Voice Calling API use the latest version - currently: 20170314. A specific API version can be set per request by sending a X-MessageBird-Version header.

Future releases will be announced on this page.

HeaderDescriptionRequired
X-MessageBird-VersionMust be in the form of YYYYMMDD.No

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

AttributeTypeDescription
errors[].codeintegerAn integer that represents the error type.
errors[].descriptionstringA human-readable description of the error. You can provide your users with this information to indicate what they can do about the error.

Error Object Example

{
"errors": [
{
"message": "The 'title' 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.

Error codes

codedescription
11A required parameter is missing in the request.
12A parameter has an invalid value.
13The requested resource could not be found.
14Access to the requested resource was forbidden.
15Authentication is missing from the HTTP request.
16The request body could not be parsed. Check if the body contents correspond with the supplied Content-Type HTTP header.
17Context of X-MessageBird-Version header is invalid.
18A query parameter has an invalid value.
21An internal server error on the MessageBird platform occured.
25A requested action on the object can't be processed.

HTTP status codes

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

HTTP status codedescription
200 FoundThe requested resource was found.
201 CreatedA resource has been created.
204 No ContentThe requested resource is empty.
400 Bad RequestThe request contains invalid/missing data, or is malformed.
401 UnauthorizedThe access key is missing or incorrect.
403 ForbiddenAccess to the requested resource was forbidden.
404 Not FoundThe resource could not be found.
405 Method Not AllowedThe HTTP method is not allowed.
500 Internal Server ErrorSomething went wrong on our end, please try again.

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/
GET /call-flows/{id}
POST /call-flows/
PUT /call-flows/{id}
DELETE /call-flows/{id}

The call flow object

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

Attributes

attributetypedescription
idstringThe unique ID of the call flow.
titlestringThe title of the call flow.
recordboolSays whether a full call recording is enabled on this call flow, the default value for this attribute is false.
stepsarrayAn array of step objects. The sequence of the array items describe the order of execution, where the first item will be executed first, than the second, etcetera.
steps[].idstringThe unique (within the call flow) identifier of the step.
steps[].actionstringThe name of the VoIP action. Possible values: transfer, say, play, pause, record, fetchCallFlow, sendKeys, hangup.
steps[].optionsobjectContains zero or more key-value pairs, where the key is the identifier of the option and value is the option value. See below for allowed values.
defaultboolThe default attribute says whether the call flow will be used when no call flow was found for an inbound number. Only one default call flow is allowed.
createdAtdatetimeThe date-time the call flow was created, in RFC 3339 format (e.g. 2017-03-06T13:34:14Z).
updatedAtdatetimeThe date-time the call flow was last updated, in RFC 3339 format (e.g. 2017-03-06T13:34:14Z).

Attributes for step[].options

attributetypedescription
destinationstringThe destination (E.164 formatted number, SIP URI or Client URI) to transfer a call to. E.g. 31612345678, sip:foobar@example.com, or client:name_of_client. The Client URI is in early access at this moment as part of our Client SDK. Required when steps[].action is transfer.
payloadstringThe text to pronounce. Required when steps[].action is say.
languagestringThe language of the text that is to be pronounced. Required when steps[].action is say. Allowed values: bg-BG, cs-CZ, cy-GB, da-DK, de-DE, el-GR, en-AU, en-GB-WLS, en-GB, en-IN, en-US, es-ES, es-MX, es-US, fr-CA, fr-FR, hr-HR, id-ID, is-IS, it-IT, ja-JP, ko-KR, ms-MY, nb-NO, nl-NL, pl-PL, pt-BR, pt-PT, ro-RO, ru-RU, sk-SK, sv-SE, ta-IN, th-TH, tr-TR, vi-VN, zh-CN, zh-HK.
voicestringThe preferred voice to use for pronouncing text. Required when steps[].action is say. Allowed values: male, female. This preference is ignored if the desired voice is not available for the selected language.
repeatstringThe amount of times to repeat the payload. Optional when steps[].action is say. Allowed values: Between 1 and 10.
mediastring or arrayThe URL(s) of the media file(s) to play. Required when steps[].action is play. The URL should end in either .wav or .mp3, note this can also be part of the last query parameter, so http://www.example.com/test.mp3?foo=bar&format=.mp3 is a valid format. Note that in the case of multiple media files in this media attribute, all need to be ending with .wav. Wave file format should be 8 kHz, 16 bit.
lengthintThe length of the pause in seconds. Required when steps[].action is pause.
maxLengthintMaximum length of a recording in seconds, when this time limit is reached, the recording will stop. It is used when steps[].action is record and it is optional with the default value being 0 which means no limit.
timeoutintSeconds of silence allowed before a recording is stopped. It is used when steps[].action is record and it is optional. If you omit this parameter, silence detection is disabled.
finishOnKeystringKey DTMF input to terminate recording. Values allowed are any, #, *, none. It is used when steps[].action is record and it is optional with the default value being none.
transcribeboolIf you want to have a transcription of a recording, after the recording has finished. It is used when steps[].action is record and it is optional with the default value being false.
transcribeLanguagestringThe language of the recording that is to be transcribed. Required when transcribe is true. Allowed values: de-DE, en-AU, en-UK, en-US, es-ES, es-LA, fr-FR, it-IT, nl-NL, pt-BR.
recordstringOptional when steps[].action is transfer. Available options are in, out and both. It can be used to record a call for a transfer action. Option in is being used to record the voice of the destination and out for the source. You can use both to record both source and destination individually.
urlstringThe URL to fetch a call flow from. Required when steps[].action is fetchCallFlow. See: Dynamic call flows.
ifMachinestringOptional when steps[].action is say. What to do when a machine picks up the phone? Possible values are:
- continue do not check, just play the message
- delay if a machine answers, wait until the machine stops talking
- hangup hangup when a machine answers
Default is: delay.
machineTimeoutintOptional when steps[].action is say. The time (in milliseconds) to analyze if a machine has picked up the phone. Used in combination with the delay and hangup values of the ifMachine attribute. Minimum: 400, maximum: 10000.
Default is: 7000.
onFinishstringOptional when steps[].action is record. The onFinish is a URL from which a new call flow is fetched. The request is a POST request and contains details of the recording. See: Dynamic call flows.
maskboolOptional when steps[].action is transfer. Mask instructs MessageBird to use the proxy number (the called VMN for example) instead of the original caller ID.
Default is: false.

Call Flow Object Example

{
"id": "de3ed163-d5fc-45f4-b8c4-7eea7458c635",
"title": "Forward call to 31612345678",
"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" -H "X-MessageBird-Version: 20170314"

Example response

{
"data": [
{
"id": "de3ed163-d5fc-45f4-b8c4-7eea7458c635",
"title": "Forward call to 31612345678",
"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
ParameterTypeDescription
idstringThe unique ID which was returned upon creation of a call flow.

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/{id}

Example request

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

Example response

{
"data": [
{
"id": "de3ed163-d5fc-45f4-b8c4-7eea7458c635",
"title": "Forward call to 31611223344",
"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

Required parameters
attributetypedescriptionrequired
titlestringThe title of the new call flow.Yes
stepsarrayAn array of step objects.Yes
defaultboolThe default attribute says whether the call flow will be used when no call flow found for inbound number. Only one default call flow is allowed and the default value for this attribute is false.Yes
recordboolInforms if a full call recording should be performed. If this option is set to true the call will be recorded, the default is false.Yes
Optional parameters
attributetypedescriptionrequired
defaultboolThe default attribute says whether the call flow will be used when no call flow found for inbound number. Only one default call flow is allowed and the default value for this attribute is false.No
recordboolInforms if a full call recording should be performed. If this option is set to true the call will be recorded, the default is false.No

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 "X-MessageBird-Version: 20170314" \
-H "Content-Type: application/json" \
-d $'{
"title": "Forward call to 31612345678",
"record": true,
"steps": [
{
"options": {
"destination": "31612345678"
},
"action": "transfer"
}
]
}'

Example response

{
"data": [
{
"id": "de3ed163-d5fc-45f4-b8c4-7eea7458c635",
"title": "Forward call to 31612345678",
"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"
}
}

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.

Notification icon

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="10" 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",
"title": "XML Call flow",
"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": 10
},
"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.

Required and optional parameters
attributetypedescriptionrequired
idstringThe identifier of the step.No
destinationstringThe destination (E.164 formatted number, SIP URI or Client URI) to transfer a call to. E.g. 31612345678, sip:foobar@example.com, or client:name_of_client. The Client URI is in early access at this moment as part of our Client SDK.Yes

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 1000.

Required and optional parameters
attributetypedescriptionrequired
idstringThe identifier of the step.No
languagestringThe language of the text that is to be pronounced. Required when steps[].actionis say. Allowed values: cy-gb,da-dk,de-de,el-gr,en-au,en-gb,en-gb-wls,en-in,en-us,es-es,es-mx,es-us,fr-ca,fr-fr,id-id,is-is,it-it,ja-jp,ko-kr,ms-my,nb-no,nl-nl,pl-pl,pt-br,pt-pt,ro-ro,ru-ru,sv-se,ta-in,th-th,tr-tr,vi-vn,zh-cn,zh-hk.Yes
voicestringThe voice to use for pronouncing text. Allowed values: male, female.Yes
repeatintThe amount of times to repeat the payload.No
onKeypressVarstringThe name of the variable used for storing a keypress value when a key is pressed during this step. Variables can be used in If conditions.No
onKeypressGotostringThe ID of the step to jump to when the caller presses a key during this step.No
endKeystringIf set, determines which DTMF triggers the next step. The end key is not included in the resulting variable. If not set, no key will trigger the next step.No
maxNumKeysintAn optional limit to the number of DTMF events that should be gathered before continuing to the next step. By default, this is set to 1, so any key will trigger the next step. If EndKey is set and MaxNumKeys is unset, no limit for the number of keys that will be gathered will be imposed. It is possible for less keys to be gathered if the EndKey is pressed or the timeout being reached.No

The Play tag

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

Required and optional parameters
attributetypedescriptionrequired
idstringThe identifier of the step.No
urlstringThe URL of the media file to play. The media file should be a WAV file (mono, 8 kHz, 16 bit).Yes
onKeypressVarstringThe name of the variable used for storing a keypress value when a key is pressed during this step. Variables can be used in If conditions.No
onKeypressGotostringThe ID of the step to jump to when the caller presses a key during this step.No
endKeystringIf set, determines which DTMF triggers the next step. The end key is not included in the resulting variable. If not set, no key will trigger the next step.No
maxNumKeysintAn optional limit to the number of DTMF events that should be gathered before continuing to the next step. By default, this is set to 1, so any key will trigger the next step. If EndKey is set and MaxNumKeys is unset, no limit for the number of keys that will be gathered will be imposed. It is possible for less keys to be gathered if the EndKey is pressed or the timeout being reached.No

The Pause tag

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

Required and optional parameters
attributetypedescriptionrequired
idstringThe identifier of the step.No
lengthintThe length of the pause in seconds.Yes
onKeypressVarstringThe name of the variable used for storing a keypress value when a key is pressed during this step. Variables can be used in If conditions.No
onKeypressGotostringThe ID of the step to jump to when the caller presses a key during this step.No
endKeystringIf set, determines which DTMF triggers the next step. The end key is not included in the resulting variable. If not set, no key will trigger the next step.No
maxNumKeysintAn optional limit to the number of DTMF events that should be gathered before continuing to the next step. By default, this is set to 1, so any key will trigger the next step. If EndKey is set and MaxNumKeys is unset, no limit for the number of keys that will be gathered will be imposed. It is possible for less keys to be gathered if the EndKey is pressed or the timeout being reached.No

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.

Required and optional parameters
attributetypedescriptionrequired
idstringThe identifier of the step.No
maxLengthintMaximum length of a recording in seconds. The default is no limit on the recording length.No
timeoutintThe amount in seconds of silence after which a recording should be stopped. Note that silence detection in noisy environments might not always provide the best results, so it is advised to also set a maxLength as fallback. The default is that silence detection is disabled.No
finishOnKeystringKey DTMF input to stop recording. Values allowed are any, #, *, none. The default is none, which means that a recording can not be stopped by a DTMF.No
transcribeboolSet to true if you want to have a transcription of the recording. The default is false.No
transcribeLanguagestringIf transcribe is set transcribeLanguage is required then. See transcribeLanguage for the list of available languages.No

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.

Required and optional parameters
attributetypedescriptionrequired
idstringThe identifier of the step.No
keysstringKeys to send. Allowed set of characters: 0-9, A-D, #, *; with a maximum of 100 keys.Yes

Example

curl -X POST https://voice.messagebird.com/calls \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "X-MessageBird-Version: 20170314" \
-d $'{
"source": "31644556677",
"destination": "31612345678",
"callFlow": {
"title": "sendKeys example",
"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.

Required and optional parameters
attributetypedescriptionrequired
idstringThe identifier of the step.No
urlstringThe URL to fetch a call flow from. Required when steps[].action is fetchCallFlow.Yes
timeoutintThe timeout for fetching the XML/JSON callflow from the URL the user specified at the fetchCallFlow action. It is optional with the default value being 5 seconds.No

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.

Required and optional parameters
attributetypedescriptionrequired
idstringThe identifier of the If tag.No
conditionstringAn expression which will be evaluated before any nested steps are executed, e.g. foobar == 1. Variables need to be stored before the If tag is reached, by using the onKeypressVar in an earlier step. Valid operators are == and !=.Yes

Example

<CallFlow>
<Say language="en-US" voice="male" onKeypressVar="foo" onKeypressGoto="bar">Hello! Press 1, 2, or 3 to continue.</Say>
<Pause length="10" 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
parametertypedescriptionrequired
idstringThe unique ID which was returned upon creation of a call flow.Yes
Optional parameters
parametertypedescriptionrequired
titlestringThe updated title of a call flow.No
stepsarrayAn array of step objects that replaces the current array of steps.No
recordboolEnables or disables full call recording.No

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/{id}

Example request

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

Example response

{
"data": [
{
"id": "de3ed163-d5fc-45f4-b8c4-7eea7458c635",
"title": "Updated call flow",
"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
parametertypedescriptionrequired
idstringThe unique ID which was returned upon creation of a call flow.Yes

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/{id}

Example request

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

Assigning numbers to a call flow

To use a call flow for incoming calls to your number(s), you'll need to assign those numbers first.

Required parameters
parametertypedescriptionrequired
idstringThe unique ID which was returned upon creation of a call flow.Yes
numbersarrayAn array of strings, where each string is an E.164 formatted number (e.g. 31612345678) you own.Yes

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/{id}/numbers

Example request

curl -X POST https://voice.messagebird.com/call-flows/de3ed163-d5fc-45f4-b8c4-7eea7458c635/numbers \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \
-H "X-MessageBird-Version: 20170314" \
-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/{id}/numbers

Example request

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

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

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

Notification icon

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 "X-MessageBird-Version: 20170314" \
-H "Content-Type: application/json" \
-d $'{
"title": "Fetch call flow from web service",
"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
parametersexampledescription
callID1ebbae0e-e1a6-4b85-8ccb-de609d0b4510The unique ID of the call.
destination31612345678The destination number that is/was called.
firstLegDirectionoutgoing/incomingCan be either 'incoming' or 'outgoing' and be used to distinguish whether the originating call was an incoming one or triggered via the API
source31644556677/anonymousThe source number that triggered the call
variables{"user_pressed": "5"}Json object containing metadata of the call. Can include key presses if used together with onKeypressVar in steps or via the Flow Builder.

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>
Notification icon

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

Notification icon

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
OomF7gSVo5TdL6mxFvdlYodiTnJtPaEk7V6czObUUI0=

Pseudocode example

// Note that the query params should be sorted by alphabetically order of the keys including the variables array
signature = HMAC_SHA_256(
QUERY_PARAMS,
signing_key
)
if HMAC_EQUALS(signature, BASE_64_DECODE(request_signature)) {
// Yay!
}

Calls

A call describes a voice call.

A call is made to a number. A call has legs which are incoming or outgoing voice connections. An incoming leg is created when somebody calls a number. Outgoing legs are created when a call is transferred.

URI

https://voice.messagebird.com/calls

Available HTTP Methods

POST /calls/
GET /calls/
GET /calls/{callID}
DELETE /calls/{callID}
GET /calls/{callID}/legs
GET /calls/{callID}/legs/{legID}

The call object

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

Attributes

attributetypedescription
idstringThe unique ID of the call.
statusstringThe status of the call. Possible values: queued, starting, ongoing, ended.
sourcestringThe source number of the call, without leading +, ommited if not available
destinationstringThe destination number of the call, without leading +, ommited if not available
webhook.urlstringThe URL to use for status callbacks. See: webhooks.
webhook.tokenstringThe token to use for status callbacks. See: webhooks
createdAtdatetimeThe date-time the call was created, in RFC 3339 format (e.g. 2017-03-06T13:34:14Z).
updatedAtdatetimeThe date-time the call was last updated, in RFC 3339 format (e.g. 2017-03-06T13:34:14Z).
endedAtdatetimeThe date-time the call ended, in RFC 3339 format (e.g. 2017-03-06T13:34:14Z).

Call object example

{
"id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
"status": "ended",
"source": "31644556677",
"destination": "31612345678",
"createdAt": "2017-02-16T10:52:00Z",
"updatedAt": "2017-02-16T10:59:04Z",
"endedAt": "2017-02-16T10:59:04Z"
}

List all calls

This request retrieves a listing of all calls.

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 objects, can be null if there are no calls. 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/calls

Example request

curl -X "GET" "https://voice.messagebird.com/calls" -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" -H "X-MessageBird-Version: 20170314"

Example response

{
"data": [
{
"id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
"status": "ended",
"source": "31644556677",
"destination": "31612345678",
"createdAt": "2017-02-16T10:52:00Z",
"updatedAt": "2017-02-16T10:59:04Z",
"endedAt": "2017-02-16T10:59:04Z",
"_links": {
"self": "/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58"
}
},
{
"id": "ac07a602-dbc1-11e6-bf26-cec0c932ce01",
"status": "ended",
"source": "31644556677",
"destination": "31612345678",
"createdAt": "2017-01-16T07:51:56Z",
"updatedAt": "2017-01-16T07:55:56Z",
"endedAt": "2017-01-16T07:55:56Z",
"_links": {
"self": "/calls/ac07a602-dbc1-11e6-bf26-cec0c932ce01"
}
}
],
"_links": {
"self": "/calls?page=1"
},
"pagination": {
"totalCount": 2,
"pageCount": 1,
"currentPage": 1,
"perPage": 10
}
}

Viewing a call

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

Required parameters
parametertypedescriptionrequired
idstringThe unique ID of a call generated upon creation.Yes

Response

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

Definition

GET https://voice.messagebird.com/calls/{id}

Example request

curl https://voice.messagebird.com/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58 -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' -H 'X-MessageBird-Version: 20170314'

Example response

{
"data": [
{
"id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
"status": "ended",
"source": "31644556677",
"destination": "31612345678",
"createdAt": "2017-02-16T10:52:00Z",
"updatedAt": "2017-02-16T10:59:04Z",
"endedAt": "2017-02-16T10:59:04Z"
}
],
"_links": {
"self": "/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58"
}
}

Creating a call

This request initiates an outbound call. When placing a call, you pass the source (the caller ID), the destination(the number/address that will be called), and the callFlow (the call flow to execute when the call is answered).

Required parameters
parametertypedescriptionrequired
sourcestringThe caller ID of the call.Yes
destinationstringThe number/address to be called. This can be an E.164 formatted number, SIP URI or Client URI. E.g. 31612345678, sip:foobar@example.com, or client:name_of_client.Yes
callFlowobjectThe call flow object to be executed when the call is answered.Yes
Optional parameters
parametertypedescriptionrequired
webhook.urlstringThe URL to use for status callbacks. See: webhooks. Setting a webhook URL when creating a call will override any webhook resource settings if they exist.No
webhook.tokenstringThe token to use for status callbacks. See: webhooks.No

Response

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

Definition

POST https://voice.messagebird.com/calls

Example request

curl -X POST https://voice.messagebird.com/calls \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "X-MessageBird-Version: 20170314" \
-d $'{
"source": "31644556677",
"destination": "31612345678",
"callFlow": {
"title": "Say message",
"steps": [
{
"action": "say",
"options": {
"payload": "This is a journey into sound. Good bye!",
"voice": "male",
"language": "en-US"
}
}
]
},
"webhook": {
"url": "https://example.com",
"token": "token_to_sign_the_call_events_with",
}
}'

Example response

{
"data": [
{
"id": "21025ed1-cc1d-4554-ac05-043fa6c84e00",
"status": "queued",
"source": "31644556677",
"destination": "31612345678",
"createdAt": "2017-08-30T07:35:37Z",
"updatedAt": "2017-08-30T07:35:37Z",
"endedAt": null
}
],
"_links": {
"self": "/calls/21025ed1-cc1d-4554-ac05-043fa6c84e00"
}
}

Updating a call

This request updates an active call. You can update steps of an ongoing call by providing a new call-flow url. When you update the call through the API, the API will request the new call-flow at the by you provided new URL. Once the new call-flow is fetched, current ongoing steps will be stopped and the new call-flow will be executed.

Required parameters
parametertypedescriptionrequired
fetchCallFlowUrlstringThe URL to fetch the new call flow from. See: Dynamic call flows.Yes
Optional parameters
parametertypedescriptionrequired
fetchCallFlowTokenstringThe token that we will use to sign the request. See: Dynamic call flows.No

Response

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

Definition

PUT https://voice.messagebird.com/calls/{id}

Example request

curl -X PUT https://voice.messagebird.com/calls/{id} \
-H "Content-Type: application/json" \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "X-MessageBird-Version: 20170314" \
-d $'{
"fetchCallFlowUrl": "https://www.example.com",
"fetchCallFlowToken": "foobar",
}'

Example response

{
"data": [
{
"id": "21025ed1-cc1d-4554-ac05-043fa6c84e00",
"status": "ongoing",
"source": "31644556677",
"destination": "31612345678",
"createdAt": "2017-08-30T07:35:37Z",
"updatedAt": "2017-08-30T07:35:37Z",
"endedAt": null
}
],
"_links": {
"legs": "/calls/21025ed1-cc1d-4554-ac05-043fa6c84e00/legs",
"self": "/calls/21025ed1-cc1d-4554-ac05-043fa6c84e00"
}
}

Deleting a call

This request will hang up all the legs of the call.

Required parameters
parametertypedescriptionrequired
idstringThe unique ID of the call.Yes

Response

If successful, this request returns 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/calls/{id}

Example request

curl -X DELETE https://voice.messagebird.com/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58 -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' -H 'X-MessageBird-Version: 20171123'

Legs

A leg describes a leg object (inbound or outbound) that belongs to a call. At least one leg exists per call.

Inbound legs are being created when an incoming call to a Number is being initiated.

Outbound legs are created when a call is transferred or when a call is being originated from the API.

URI

https://voice.messagebird.com/calls/{callID}/legs

Available HTTP Methods

GET /calls/{callID}/legs/
GET /calls/{callID}/legs/{legID}

The leg object

This is an object representing a leg at MessageBird.com.

Attributes

attributetypedescription
idstringThe unique ID of the leg.
callIDstringThe unique ID of the call that this leg belongs to.
sourcestringThe number/SIP/Client URL that is making the connection.
destinationstringThe number/SIP/Client URL that a connection is made to.
statusstringThe status of the leg. Possible values: starting, ringing, ongoing, busy, no_answer, failed and hangup.
directionstringThe direction of the leg, indicating if it's an incoming connection or outgoing (e.g. for transferring a call). Possible values: incoming, outgoing.
costfloatThe cost of the leg. The amount relates to the currency parameter.
currencystringThe three-letter currency code (ISO 4217) related to the cost of the leg.
durationintThe duration of the leg, in seconds.
createdAtdatetimeThe date-time the leg was created, in RFC 3339 format (e.g.2017-03-06T13:34:14Z).
updatedAtdatetimeThe date-time the leg was last updated, in RFC 3339 format (e.g. 2017-03-06T13:34:14Z).
answeredAtdatetimeThe date-time the leg was answered, in RFC 3339 format (e.g.2017-03-06T13:34:14Z).
endedAtdatetimeThe date-time the leg ended, in RFC 3339 format (e.g. 2017-03-06T13:34:14Z).

Object example

{
"id": "d4f07ab3-b17c-44a8-bcef-2b351311c28f",
"callId": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
"source": "31644556677",
"destination": "31612345678",
"status": "hangup",
"direction": "outgoing",
"duration": 31,
"createdAt": "2017-02-16T10:52:00Z",
"updatedAt": "2017-02-16T10:52:30Z",
"answeredAt": "2017-02-16T10:52:30Z",
"endedAt": "2017-02-16T10:52:30Z"
}

List all legs

This request retrieves a listing of all legs.

Required parameters
parametertypedescriptionrequired
idstringThe unique ID of a call generated upon creation.Yes

Response

If successful, this request will return an object with a data property containing the leg objects, can be null if there are no legs. If the request failed, an error object will be returned.

Definition

GET https://voice.messagebird.com/calls/{id}/legs

Example request

curl -X "GET" "https://voice.messagebird.com/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/legs" -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" -H "X-MessageBird-Version: 20170314"

Example response

{
"data": [
{
"id": "d4f07ab3-b17c-44a8-bcef-2b351311c28f",
"callId": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
"source": "31123456789",
"destination": "31123456777",
"status": "hangup",
"direction": "outgoing",
"duration": 31,
"cost": 0.000385,
"currency": "USD",
"createdAt": "2017-02-16T10:52:00Z",
"updatedAt": "2017-02-16T10:52:30Z",
"answeredAt": "2017-02-16T10:52:30Z",
"endedAt": "2017-02-16T10:52:30Z",
"_links": {
"self": "/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/legs/d4f07ab3-b17c-44a8-bcef-2b351311c28f"
}
},
{
"id": "e60ca497-0cf3-4954-b74c-265e95633ec8",
"callId": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
"source": "31123456789",
"destination": "31123456788",
"status": "hangup",
"direction": "incoming",
"duration": 31,
"cost": 0.000385,
"currency": "USD",
"createdAt": "2017-02-16T10:52:00Z",
"updatedAt": "2017-02-16T10:52:30Z",
"answeredAt": "2017-02-16T10:52:30Z",
"endedAt": "2017-02-16T10:52:30Z",
"_links": {
"self": "/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/legs/e60ca497-0cf3-4954-b74c-265e95633ec8"
}
}
],
"_links": {
"self": "/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/legs?page=1"
},
"pagination": {
"totalCount": 2,
"pageCount": 1,
"currentPage": 1,
"perPage": 10
}
}

Viewing a leg

This request retrieves a leg resource. The parameters are the unique ID of the call and of the leg that were returned upon their respective creation.

Required parameters

parametertypedescriptionrequired
callIDstringThe unique ID of a call generated upon creation.Yes
legIdstringThe unique ID of a leg generated upon creation.Yes

Response

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

Definition

GET https://voice.messagebird.com/calls/{callID}/legs/{legID}

Example request

curl https://voice.messagebird.com/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/legs/d4f07ab3-b17c-44a8-bcef-2b351311c28f -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' -H "X-MessageBird-Version: 20170314"

Example response

{
"data": [
{
"id": "d4f07ab3-b17c-44a8-bcef-2b351311c28f",
"callId": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58",
"source": "31644556677",
"destination": "31612345678",
"status": "hangup",
"direction": "outgoing",
"duration": 31,
"cost": 0.000385,
"currency": "USD",
"createdAt": "2017-02-16T10:52:00Z",
"updatedAt": "2017-02-16T10:52:30Z",
"answeredAt": "2017-02-16T10:52:30Z",
"endedAt": "2017-02-16T10:52:04Z"
}
],
"_links": {
"self": "/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/legs/d4f07ab3-b17c-44a8-bcef-2b351311c28f"
}
}

Recordings

A recording describes a voice recording of a leg. You can initiate a recording of a leg by having a step in your callflow with the record action set.

URI

https://voice.messagebird.com/calls/{callID}/legs/{legID}/recordings

Available HTTP Methods

GET /calls/{callID}/legs/{legID}/recordings
GET /calls/{callID}/legs/{legID}/recordings/{recordingID}

The recording object

This is an object representing a recording.

Attributes

attributestypedescription
idstringThe unique ID of the recording.
formatstringThe format of the recording. Supported formats are: wav.
typestringThe type of the recording, possible values are ivr(result of a record step), transfer(result of a transfer step recording) or call(in case of full call recording).
legIdstringThe ID of the leg that the recording belongs to.
statusstringThe status of the recording. Available statuses are:initialised, recording, done and failed
durationintegerThe duration of the recording in seconds.
createdAtdatetimeThe date-time the call was created, in RFC 3339 format (e.g. 2017-03-06T13:34:14Z).
updatedAtdatetimeThe date-time the call was last updated, in RFC 3339 format (e.g. 2017-03-06T13:34:14Z).
_linkshashA hash with HATEOAS links related to the object. This includes the file link that has the URI for downloading the wave file of the recording.

URI

{
"data": [
{
"id": "3b4ac358-9467-4f7a-a6c8-6157ad181123",
"format": "wav",
"legId": "227bd14d-3eee-4380-b01f-fe7723c69a31",
"state": "done",
"duration": 7,
"createdAt": "2017-05-17T11:42:57Z",
"updatedAt": "2017-05-17T11:43:04Z"
}
],
"_links": {
"self": "/calls/bb3f0391-4fdc-4e38-9551-e8a01602984f/legs/cc3bd14d-3eee-4380-b01f-fe7723c69a31/recordings/3b4ac358-9467-4f7a-a6c8-6157ad181123",
"file": "/calls/bb3f0391-4fdc-4e38-9551-e8a01602984f/legs/cc3bd14d-3eee-4380-b01f-fe7723c69a31/recordings/3b4ac358-9467-4f7a-a6c8-6157ad181123.wav"
}
}

Viewing a recording

This request retrieves a recording resource. The parameters are the unique ID of the recording, the leg and the call with which the recording is associated.

Required parameters

parametertypedescriptionrequired
callIDstringThe unique ID of a call generated upon creation.Yes
legIdstringThe unique ID of a leg generated upon creation.Yes
recordingIdstringThe unique ID of a recording generated upon creation.Yes

Response

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

Definition

GET https://voice.messagebird.com/calls/{callID}/legs/{legID}/recordings/{recordingID}

Example request

curl -X "GET" "https://voice.messagebird.com/calls/bb3f0391-4fdc-4e38-9551-e8a01602984f/legs/cc3bd14d-3eee-4380-b01f-fe7723c69a31/recordings/4c2ac358-b467-4f7a-a6c8-6157ad181142" -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" -H "X-MessageBird-Version: 20170314"

Example response

{
"data": [
{
"id": "4c2ac358-b467-4f7a-a6c8-6157ad181142",
"format": "wav",
"type": "ivr",
"legId": "317bd14d-3eee-4380-b01f-fe7723c6913a",
"state": "done",
"duration": 42,
"createdAt": "2017-05-17T11:42:57Z",
"updatedAt": "2017-05-17T11:43:04Z",
"_links": {
"self": "/calls/fdcf0391-4fdc-4e38-9551-e8a01602984f/legs/317bd14d-3eee-4380-b01f-fe7723c6913a/recordings/4c2ac358-b467-4f7a-a6c8-6157ad181142",
"file": "/calls/fdcf0391-4fdc-4e38-9551-e8a01602984f/legs/317bd14d-3eee-4380-b01f-fe7723c6913a/recordings/4c2ac358-b467-4f7a-a6c8-6157ad181142.wav"
}
}
],
"_links": {
"self": "/calls/fdcf0391-4fdc-4e38-9551-e8a01602984f/legs/317bd14d-3eee-4380-b01f-fe7723c6913a/recordings/4c2ac358-b467-4f7a-a6c8-6157ad181142?page=1"
},
"pagination": {
"totalCount": 1,
"pageCount": 1,
"currentPage": 1,
"perPage": 10
}
}

Downloading the recording file

The file HATEOAS link has the appropriate URI for downloading a wave file for the recording. The file is accessible only if you provide the correct API access key for your account and the recording is for a leg/call in your account.

URI

/calls/{callID}/legs/{legID}/recordings/{recordingID}.wav

Deleting a recording

This request deletes a recording. The parameters are the unique ID of the recording, the leg and the call with which the recording is associated.

Required parameters
parametertypedescriptionrequired
callIDstringThe unique ID of a call generated upon creation.Yes
legIdstringThe unique ID of a leg generated upon creation.Yes
recordingIdstringThe unique ID of a recording generated upon creation.Yes

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/calls/{callID}/legs/{legID}/recordings/{recordingID}

Example request

curl -X "DELETE" "https://voice.messagebird.com/calls/bb3f0391-4fdc-4e38-9551-e8a01602984f/legs/cc3bd14d-3eee-4380-b01f-fe7723c69a31/recordings/4c2ac358-b467-4f7a-a6c8-6157ad181142" -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" -H "X-MessageBird-Version: 20170314"

Transcriptions

transcription is a textual representation of a recording as text. You can request an automated transcription for a recording by doing a POST request to the API.

MessageBird supports several languages: de-DE, en-AU, en-UK, en-US, es-ES, es-LA, fr-FR, it-IT, nl-NL, pt-BR. We expect to release support for more languages soon.

URI

https://voice.messagebird.com/calls/{callID}/legs/{legID}/recordings/{recordingID}/transcriptions

Available HTTP Methods

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

The transcription object

This is an object representing a transcription.

Attributes

attributetypedescription
idstringThe unique ID of the transcription.
recordingIdstringThe ID of the recording that the transcription belongs to.
errorstringIn case that an error was occurred while executing the transcription request, it appears here.
createdAtdatetimeThe date-time the transcription was created/requested, in RFC 3339 format (e.g. 2017-03-06T13:34:14Z).
updatedAtdatetimeThe date-time the transcription was last updated, in RFC 3339 format (e.g. 2017-03-06T13:34:14Z).
_linkshashA hash with HATEOAS links related to the object. This includes the file link that has the URI for downloading the text transcription of a recording.

Transcription object example

{
"data": [
{
"id": "87c377ce-1629-48b6-ad01-4b4fd069c53c",
"recordingId": "123da3f9-ddd3-4267-ab01-71cf55df31df",
"error": null,
"createdAt": "2017-06-20T10:03:14Z",
"updatedAt": "2017-06-20T10:03:14Z"
}
],
"_links": {
"self": "/calls/096d3500-0f6e-4c0f-89a1-41934458ee69/legs/124906d6-b745-435e-aabc-8005dbc5ccf3/recordings/07fda3f9-ddd3-4267-ab01-71cf55df31df/transcriptions/87c377ce-1629-48b6-ad01-4b4fd069c53c",
"file": "/calls/096d3500-0f6e-4c0f-89a1-41934458ee69/legs/124906d6-b745-435e-aabc-8005dbc5ccf3/recordings/07fda3f9-ddd3-4267-ab01-71cf55df31df/transcriptions/87c377ce-1629-48b6-ad01-4b4fd069c53c.txt"
}
}

Creating a transcription request

In order to create a transcription request for an existing recording, you must do a POST request to the following URI:

The parameters are the unique ID of the recording, the leg, and the call with which the recording is associated. A transcription request is asynchronous. That means that it will take some time before the result has been generated. This depends on the total duration of the recording.

Required parameters

parametertypedescriptionrequired
callIDstringThe unique ID of a call generated upon creation.Yes
legIdstringThe unique ID of a leg generated upon creation.Yes
recordingIdstringThe unique ID of a recording generated upon creation.Yes
languagestringThe language of the recording that is to be transcribed. Allowed values: de-DE, en-AU, en-UK, en-US, es-ES, es-LA, fr-FR, it-IT, nl-NL, pt-BR.Yes

Response

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

Example request

curl -X "POST" "https://voice.messagebird.com/calls/94dc10f8-099a-42a7-a33b-063be8cc47b8/legs/9afe113b-9746-4b18-852d-b18ba50b3e4a/recordings/07fda3f9-ddd3-4267-ab01-71cf55df31df/transcriptions/" -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" -H "X-MessageBird-Version: 20170314"

Viewing a transcription

This request retrieves a transcription resource. The parameters are the unique ID of the recording, the leg and, the call with which this recording is associated.

Required parameters

parametertypedescriptionrequired
callIDstringThe unique ID of a call generated upon creation.Yes
legIdstringThe unique ID of a leg generated upon creation.Yes
recordingIdstringThe unique ID of a recording generated upon creation.Yes

Response

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

Definition

GET https://voice.messagebird.com/calls/{callID}/legs/{legID}/recordings/{recordingID}

Example request

curl -X "GET" "https://voice.messagebird.com/calls/fdcf0391-4fdc-4e38-9551-e8a01602984f/legs/317bd14d-3eee-4380-b01f-fe7723c6913a/recordings/4c2ac358-b467-4f7a-a6c8-6157ad181142/transcriptions/87c377ce-1629-48b6-ad01-4b4fd069c53c" -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" -H "X-MessageBird-Version: 20170314"

Example response

{
"data": [
{
"id": "87c377ce-1629-48b6-ad01-4b4fd069c53c",
"recordingId": "07fda3f9-ddd3-4267-ab01-71cf55df31df",
"error": null,
"createdAt": "2017-06-20T10:03:14Z",
"updatedAt": "2017-06-20T10:03:14Z",
"_links": {
"self": "/calls/096d3500-0f6e-4c0f-89a1-41934458ee69/legs/124906d6-b745-435e-aabc-8005dbc5ccf3/recordings/07fda3f9-ddd3-4267-ab01-71cf55df31df/transcriptions/87c377ce-1629-48b6-ad01-4b4fd069c53c",
"file": "/calls/096d3500-0f6e-4c0f-89a1-41934458ee69/legs/124906d6-b745-435e-aabc-8005dbc5ccf3/recordings/07fda3f9-ddd3-4267-ab01-71cf55df31df/transcriptions/87c377ce-1629-48b6-ad01-4b4fd069c53c.txt"
}
}
}

Downloading the transcription file

The file HATEOAS link has the appropriate URI for downloading a text file for the transcription. The file is accessible only if you provide the correct API access key for your account and the transcription is for a recording/leg/call in your account.

The format of this URI is:

/calls/{callID}/legs/{legID}/recordings/{recordingID}/transcriptions/{transcriptionID}.txt

Webhooks

The webhook object

This object represents a configuration for delivering webhooks.

Attributes

attributetypedescription
idstringThe unique ID of the webhook.
urlstringThe callback URL that will be requested when our platform sends a webhook.
tokenstringThe secret used for signing webhook requests.
createdAtstringThe date-time when webhook was created, in RFC 3339 format (e.g. 2017-03-06T13:34:14Z).
updatedAtstringThe date-time when webhook was updated, in RFC 3339 format (e.g. 2017-03-06T13:34:14Z).

Webhook object example

{
"id": "534e1848-235f-482d-983d-e3e11a04f58a",
"url": "https://example.com/",
"token": "foobar",
"createdAt": "2017-03-15T14:10:07Z",
"updatedAt": "2017-03-15T14:10:07Z"
}

URI

https://voice.messagebird.com/webhooks

Available HTTP Methods

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

List all webhooks

This request retrieves a listing of all webhooks.

Response

If successful, this request returns 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 webhook objects, can be null if there are no webhooks. 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.

Example request

curl -X "GET" "https://voice.messagebird.com/webhooks" -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" -H "X-MessageBird-Version: 20170314"

Example response

{
"data": [
{
"id": "534e1848-235f-482d-983d-e3e11a04f58a",
"url": "https://example.com/",
"token": "foobar",
"createdAt": "2017-03-15T13:28:32Z",
"updatedAt": "2017-03-15T13:28:32Z",
"_links": {
"self": "/webhooks/534e1848-235f-482d-983d-e3e11a04f58a"
}
}
],
"_links": {
"self": "/webhooks?page=1"
},
"pagination": {
"totalCount": 1,
"pageCount": 1,
"currentPage": 1,
"perPage": 10
}
}

Viewing a webhook

This request retrieves a webhook resource. The single parameter is the unique ID that was returned upon creation.

Required parameters

parametertypedescriptionrequired
idstringThe unique ID which was returned upon creation of a webhook.Yes

Response

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

Definition

GET https://voice.messagebird.com/webhooks/{id}

Example request

curl https://voice.messagebird.com/webhooks/534e1848-235f-482d-983d-e3e11a04f58a -H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" -H "X-MessageBird-Version: 20170314"

Example response

{
"data": [
{
"id": "534e1848-235f-482d-983d-e3e11a04f58a",
"url": "https://example.com/",
"token": "foobar",
"createdAt": "2017-03-15T13:28:32Z",
"updatedAt": "2017-03-15T13:28:32Z"
}
],
"_links": {
"self": "/webhooks/534e1848-235f-482d-983d-e3e11a04f58a"
}
}

Creating a webhook

This request creates a new webhook.

Required parameters

parametertypedescriptionrequired
urlstringThe URL to use for status callbacks. Setting a webhook URL when creating a call will override any webhook resource settings if they exist.Yes

Optional parameters

parametertypedescriptionrequired
titlestringThe title of the new webhook.No
tokenstringThe secret used for signing webhook requests.No

Response

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

Definition

POST https://voice.messagebird.com/webhooks/

Example request

curl -X POST https://voice.messagebird.com/webhooks \
-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \
-H "X-MessageBird-Version: 20170314" \
-H "Content-Type: application/json" \
-d $'{
"url": "https://example.com/",
"token": "foobar"
}'

Example response

{
"data": [
{
"id": "534e1848-235f-482d-983d-e3e11a04f58a",
"url": "https://example.com/",
"token": "foobar",
"createdAt": "2017-03-15T14:10:07Z",
"updatedAt": "2017-03-15T14:10:07Z"
}
],
"_links": {
"self": "/webhooks/534e1848-235f-482d-983d-e3e11a04f58a"
}
}

Updating a webhook

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

Required parameters

parametertypedescriptionrequired
idstringThe unique ID that was returned upon creation of a webhook.Yes

Optional parameters

parametertypedescriptionrequired
titlestringThe updated title of a webhook.No
tokenstringThe secret used for signing webhook requests.No

Response

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

Definition

PUT https://voice.messagebird.com/webhooks/{id}

Example request

curl -X PUT https://voice.messagebird.com/webhooks/534e1848-235f-482d-983d-e3e11a04f58a -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' -H "X-MessageBird-Version: 20170314" -d $'{"url": "https://example.com/baz"}'

Example response

{
"data": [
{
"id": "534e1848-235f-482d-983d-e3e11a04f58a",
"url": "https://example.com/baz",
"token": "foobar",
"createdAt": "2017-03-15T13:27:02Z",
"updatedAt": "2017-03-15T13:28:01Z"
}
],
"_links": {
"self": "/webhooks/534e1848-235f-482d-983d-e3e11a04f58a"
}
}

Deleting a webhook

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

Required parameters

parametertypedescriptionrequired
idstringThe unique ID that was returned upon creation of a webhook.Yes

Response

If successful, this request returns 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/webhooks/{id}

Example request

curl -X DELETE https://voice.messagebird.com/webhooks/534e1848-235f-482d-983d-e3e11a04f58a -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' -H "X-MessageBird-Version: 20170314"

Example request (Type leg)

POST / HTTP/1.1
Host: example.com
Content-Type: application/json
X-MessageBird-Signature: roAnwpDfIzW6G3JpKVS6866CKHcJQUiAC9DqswzGY6s/xFPUIa5Qla9AZuCOSQ=
Content-Length: 376
{
"timestamp": "2017-09-14T07:40:12Z",
"items": [
{
"type": "leg",
"payload": {
"id": "f3e699db-68a5-49dc-8f5b-e5272a7349c7",
"callId": "2452531a-b7a9-4797-a45e-20f5feaf46ce",
"source": "31644556677",
"destination": "31612345678",
"status": "ringing",
"direction": "outgoing",
"duration": 0,
"createdAt": "2017-09-14T07:40:07Z",
"updatedAt": "2017-09-14T07:40:07Z",
"answeredAt": null,
"endedAt": null
}
}
]
}

Callbacks

Callbacks are HTTP requests sent to your platform when a call is created or updated. A callback is triggered by a webhook. To set up webhooks, please refer to webhooks.

Request

Each HTTP request has a body with a JSON object of the created/updated resource.

HTTP body

attributetypedescription
timestampdatetimeThe date-time the callback was created, in RFC 3339 format (e.g. 2017-03-06T13:34:14Z).
itemsarrayAn array of items that triggered a callback. When sending callbacks, our platform might batch items, where each item will be an object in this array.
items[].typestringThe type of the resource that created/updated. Possible values: call, leg.
items[].eventstringThe event that triggered the callback. Possible values: callCreated, callUpdated.
items[].payloadobjectThe resource related to the event, e.g. a call or leg object.

Response

Your platform should respond with a 200 OK HTTP header.

Example request (Type call)

POST / HTTP/1.1
Host: example.com
Content-Type: application/json
X-MessageBird-Signature: roAnwpDfIzW6G3JpKVS6866CKHcJQUiAC9DqswzGY6s/xFPUIa5Qla9AZuCOSQ=
Content-Length: 760
{
"timestamp": "2017-08-30T07:56:46Z",
"items": [
{
"type": "call",
"event": "callUpdated",
"payload": {
"id": "5a0dfae6-c809-4f6f-9e3d-c593149e4c0f",
"status": "ended",
"source": "31644556677",
"destination": "31612345678",
"createdAt": "2017-08-30T07:54:22Z",
"updatedAt": "2017-08-30T07:56:46Z",
"endedAt": "2017-08-30T07:56:46Z",
}
}
]
}

Example request (Type leg)

POST / HTTP/1.1
Host: example.com
Content-Type: application/json
X-MessageBird-Signature: roAnwpDfIzW6G3JpKVS6866CKHcJQUiAC9DqswzGY6s/xFPUIa5Qla9AZuCOSQ=
Content-Length: 376
{
"timestamp": "2017-09-14T07:40:12Z",
"items": [
{
"type": "leg",
"payload": {
"id": "f3e699db-68a5-49dc-8f5b-e5272a7349c7",
"callId": "2452531a-b7a9-4797-a45e-20f5feaf46ce",
"source": "31644556677",
"destination": "31612345678",
"status": "ringing",
"direction": "outgoing",
"duration": 0,
"createdAt": "2017-09-14T07:40:07Z",
"updatedAt": "2017-09-14T07:40:07Z",
"answeredAt": null,
"endedAt": null
}
}
]
}

Validation of signatures

Notification icon

Voice webhook/callback signature generation used in POST HTTP requests differs from both the signature generation used for fetching Dynamic call flows and the generic signature generation used by other MessageBird services

Each Webhook callback HTTP request is signed with a signature, 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 binary HMAC of the callback and base64 encoding it.

Using HMAC-SHA256, the HTTP body is the message and the token of the related webhook resource is the secret. Only handle the webhook if the computed value matches the signature in the HTTP header.

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
OomF7gSVo5TdL6mxFvdlYodiTnJtPaEk7V6czObUUI0=

Pseudocode example

signature = HMAC_SHA_256(
SHA_256_SUM(BODY),
signing_key
)
if HMAC_EQUALS(signature, BASE_64_DECODE(request_signature)) {
// Yay!
}
cURL
PHP
Node
C#
Java
Ruby
Go
Python
Cookie Settings