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. Possible items: transfer, say, play, pause, record, fetchCallFlow, hangup.

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

• CURL EXAMPLE REQUEST

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

• EXAMPLE RESOURCE

{
    "_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": "tp0W3PmpH9BYnpMLD3DzQi1su8NjeGPBtIOwAjjkUfg=",
                        "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"
        }
    ]
}

See also

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