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.