Messagebird APIs VoiceCalling

From 탱이의 잡동사니
Revision as of 09:09, 7 October 2018 by Pchero (talk | contribs) (→‎Requests)
Jump to navigation Jump to search

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.