Messagebird APIs VoiceCalling

Overview

Messagebird API VoiceCalling 내용 정리.

Basic

Voice Calling offers VoIP features for handing phone calls from/to voice capable number purchased via MessageBird.

The MessageBird API uses HTTP verbs and a RESTful endpoint structure. An access key is used as the API Authorization framework. Request and response payloads are formatted as JSON using UTF-8 encoding and URL encoded values, unless specified otherwise.

API Endpoint

https://voice.messagebird.com/

Endpoint Summary

• 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

Authentication

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

Header

Header : Description : Required

Authorization : Must 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 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.

Header

Header : Description : Required

X-MessageBird-Version : Must be in the form of YYYYMMDD. : No

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

Errors

MessageBird uses standard HTTP status codes to indicate success or failure of an API request. Codes in the 2xx range indicate that a request was succesfully processed and codes in the 4xx 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 jons formatted response that tells you exactly what is wrong.

Attributes

attribute : type : description

errors[].code : integer : An integer that represents the error type.

errors[].description : string : A 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
    }
  ]
}

Error codes

code : description

11 : A required parameter is missing in the request.

12 : A parameter has an invalid value.

13 : The requested resource could not be found.

14 : Access to the requested resource was forbidden.

15 : Authentication is missing from the HTTP request.

16 : The request body could not be parsed. Check if the body contents correspond with the supplied Content-Type HTTP header.

17 : Context of X-MessageBird-Version header is invalid.

18 : A query parameter has an invalid value.

21 : An internal server error on the MessageBird platform occurred.

25 : A requested action on the object can't be processed.

HTTP status code

HTTP status code : description

200 Found : The requested resource was found.

201 Created : A resource has been created.

204 No Content : The requested resource is empty.

400 Bad request : The request contains invalid/missing data, or is malformed.

401 Unauthorized : The access key is missing or incorrect.

403 Forbidden : Access to the requested resources was forbidden.

404 Not Found : The resource could not be found.

405 Method Not Allowed : The HTTP method is not allowed.

500 Internal Server Error : Something 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 ban 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.

• 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 object represents a voice call flow.

• ATTRIBUTES

attribute : type : description

id : string : The unique ID of the flow.

title : string : the title of the call flow.

record : bool : Says whether a full call recording is enabled on this call flow, the default value for this attribute is false.

steps : array : An 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[].id : string : The unique (within the call flow) identifier of the step.

steps[].action : string : The name of the VoIP action.

transfer : Transfers the call to a different phone/server.

say : Pronounces a text message with a given voice and language.

play : Plays back an audio file.

pause : Pauses (silently) for a given duration.

record : Initiates an audio recording during a call, e.g. for capturing a user response.

fetchCallFlow : Fetches a call flow from a remote URL.

hangup : Ends the call.

steps[].options : object : Contains 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.

default : bool : The default attribute says whether the cal flow will be used when no call flow found for inbound number. Only one

createdAt : datetime : The date-time the call flow was created, in RFC 3339 format(e.g. 2017-03-06T13.34:14Z)

updatedAt : datetime : The date-time the call flow was last updated, in RFC 3339 format(e.g. 2017-03-06T13.34:14Z)

• ATTRIBUTES FOR step[].options

attribute : type : description

destination : string : The destination (E.164 formatted number or SIP URI) to transfer a call to E.g. 31612345678 or sip:foobar@example.com. Required when steps[].action is transfer.

payload : string : The text to pronounce. Required when steps[].action is say.

language : string : The language of the text that is to be pronounced. Required when steps[].action is 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.

voice : string : The voice to use for pronouncing text. Required when steps[].action is say. Allowed values: male, female.

repeat : string : The amount of times to repeat the payload. Optional when steps[].action is say. Allowed values: Between 1 and 10.

media : string : The URL of the media file to play. Required when steps[].action is play. The media file should be a WAV file(8 kHz, 16 bit).

length : int : The length of the pause in seconds. Required when steps[].action is pause.

maxLength : int : Maximum length of a recording in seconds. It is used when steps[].action is record and it is optional with the default value being 0 which means no limit.

timeout : int : Seconds 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.

finishOnKey : string : Key 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.

transcribe : bool : If 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.

transcribeLanguage : string : The 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.

record : string : Optional when steps[].action is transfer 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.

url : string : The URL to fetch a call flow from. Required when steps[].action is fetchCallFlow. See Dynamic call flows.

ifMachine : string : Optional when step[].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.

machineTimeout : int : Optional when steps[].action is say. The time(in milliseconds) to analyze if a machine picked up the pone. Used in combination with the delay and hangup value of the ifMachine attribute. Minimum: 400, maximum: 10000. Default is 7000.

onFinish : string : Optional 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.

• 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

Retrieves a listing of all call flows.

Returns

Returns an object with a data, _links and paginatioin properties if the request was successful. If the request failed, an error object will be returned.

The data property is an array of call flow 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

Example

Request

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

Response

{
    "_links": {
        "self": "/call-flows?page=1"
    },
    "data": [
        {
            "_links": {
                "self": "/call-flows/22e29b3f-639e-4a5c-95e9-7256f1ecde81"
            },
            "createdAt": "2018-10-08T11:20:05Z",
            "default": false,
            "id": "22e29b3f-639e-4a5c-95e9-7256f1ecde81",
            "record": false,
            "steps": [
                {
                    "action": "fetchCallFlow",
                    "id": "f21869b7-b022-4e54-aebd-0deac73c0efc",
                    "options": {
                        "token": "tp0W3PmpH9BYnpMLD3Dz12Qi1su8NjeGPBtIOwAjjkUfg=",
                        "url": "https://flows.messagebird.com/svc/voice/call-flow?flowId=976946d6-0c62-4727-b8fc-f57560e8c7e2&invocationId=&nextStepId="
                    }
                }
            ],
            "title": "Flows API call flow (ID: 976946d6-0c62-4727-b8fc-f57560e8c7e2)",
            "updatedAt": "2018-10-08T11:20:05Z"
        }
    ],
    "pagination": {
        "currentPage": 1,
        "pageCount": 1,
        "perPage": 10,
        "totalCount": 1
    }
}

Viewing a call flow

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

REQUIRED PARAMETERS

• parameter : type : description
• id : string : The unique ID which was returned upon creation of a call flow.

RETURNS

Returns an object with a data property, which is an array that has a single call flow objct if the request was successful. 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"

Response

{
    "_links": {
        "self": "/call-flows/22e29b3f-639e-4a5c-95e9-7256f1ecde81"
    },
    "data": [
        {
            "createdAt": "2018-10-08T11:20:05Z",
            "default": false,
            "id": "22e29b3f-639e-4a5c-95e9-7256f1ecde81",
            "record": false,
            "steps": [
                {
                    "action": "fetchCallFlow",
                    "id": "f21869b7-b022-4e54-aebd-0deac73c0efc",
                    "options": {
                        "token": "tp0W3PmpH9BYnpMLD3DzQi1su8NjeGPBtIOwAjjkU12fg=",
                        "url": "https://flows.messagebird.com/svc/voice/call-flow?flowId=976946d6-0c62-4727-b8fc-f57560e8c7e2&invocationId=&nextStepId="
                    }
                }
            ],
            "title": "Flows API call flow (ID: 976946d6-0c62-4727-b8fc-f57560e8c7e2)",
            "updatedAt": "2018-10-08T11:20:05Z"
        }
    ]
}

Creating a call flow

Using JSON

Required parameters

• parameter : type : description
• title : string : The title of the new call flow.
• steps : array : An array of step objects.

Optional parameters

• parameter : type : description
• default : bool : The 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 attributes is false.
• record : bool : Informs if a full call recording should be performed. If this optoin is set to true, the call will be recorded. The default is false.

Returns

Returns an object with a data property, which is an array that has a single call flow object if the request was successful. 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"
    }
  ]
}'

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 a 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 kept 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(see example request below).

The transfer tag

Transfer the call to a different phone/server.

• attribute : type : description : required
• id : string : The identifier of the step. : No
• destination : string : The destination(E.164 formatted number or SIP URI) to transfer a call to E.g. 31612345678 or sip:foobar@example.com. : Yes

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.

• attribute : type : description : required
• id : string : The identifier of the step. : No
• language : string : The language of the text that is to be pronounced. Required when steps[].action is say. Allowed values are 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
• voice : string : The voice to use for pronouncing text. Allowed values: male, female. : Yes
• onKeypressVar : string : The 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
• onKeypressGoto : string : The ID of the step to jump to when the caller presses a key during this step. : No
• maxNumKeys : integer : An 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

Plays back an audio file. This is an empty-element tag.

• attribute : type : description : required
• id : string : The identifier of the step. : No
• url : string : The URL of the media file to play. The media file should be a WAV file(mono, 8kHz, 16bit). : Yes
• onKeypressVar : string : The 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
• endKey : string : If 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
• maxNumKeys : integer : An 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 MaxNumKey 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

See also

• https://developers.messagebird.com/docs/voice-calling