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