Recording Inbound Voice Messages with MessageBird
The MessageBird API provides an easy way to record an inbound or outbound leg as part of the execution of a call flow. After a call ends, a recording can be downloaded as a wav file—keep in mind that MessageBird hosts all recordings for 90 days before automatically deleting them.
In this MessageBird Tutorial learn how to easily record an inbound or outbound leg in your call flow with the MessageBird API. We’ll show you specifically the steps to record an inbound call to a number that you subscribed to MessageBird; an example of a use case would be a cloud-based voice mail service.
Step 1: Create the call flow
To initiate a call recording with MessageBird Voice API, you need to post a call flow with an appropriate record step. The endpoint for creating call flows via the Voice API is:
POST https://voice.messagebird.com/call-flows
Here’s an example with cURL:
curl -X "POST" "http://voice.messagebird.com/call-flows" \-H "Authorization: AccessKey :your_access_key:" \-H "Content-Type: application/json; charset=utf-8" \-d $'{"steps": [{"action": "record",}]}'
In the example below, a simple record step will be executed.
Step 2: Assign a number to the call flow
To have the call flow executed when a number you own is called, you first need to assign that number to the call flow. The endpoint to do this is:
POST https://voice.messagebird.com/call-flows/:call_flow_id:/numbers
The following is an example with cURL:
curl -X "POST" "http://voice.messagebird.com/call-flows/:call_flow_id/numbers" \-H "Authorization: AccessKey :your_access_key:" \-d $'{"numbers": ["31612345678"]}'
The call_flow_id parameter is the ID of the call flow created in step 1.
The string value in the numbers array is the E.164 formatted number you want to assign. Keep in mind that this must be a number you previously purchased. Buying a MessageBird number is quite easy; in this Help Center article we explain to you how to do it.
Awesome! After making this request, the call flow will be executed for every incoming call to the number.
Step 3: Dial the number, record your voice.
After setting the call flow, dial your number. The recording will begin when the call is answered. Speak as you normally would on a call and long enough, so there’s sufficient voice audio to transcribe. Hang up once you finish; the call recording will then stop and be saved.
Step 4: Get the information about the call / leg and recording
1. GET THE CALLS.
By making a request to the /calls endpoint, you can get a list of every call for your account; from there, you can extract the id of the call you want to retrieve leg recordings from. An example request for a list of your calls with cURL would like this:
curl "https://voice.messagebird.com/calls" \-H "Authorization: AccessKey :your_access_key:"
Here’s an example result to a request like that:
{"data": [{"id": ":callID","status": "ended","source": "31644556677","destination": "31612345678","numberId": "6e143426-d7ea-11e6-bf26-cec0c932ce01","createdAt": "2017-06-21T12:42:25Z","updatedAt": "2017-06-21T12:42:36Z","endedAt": "2017-06-21T12:42:36Z","_links": {"legs": "/calls/:callID/legs","self": "/calls/:callID"}},],"_links": {"self": "/calls?page=1"},"pagination": {"totalCount": 1,"pageCount": 1,"currentPage": 1,"perPage": 10}}}
2. GET THE LEGS FROM THE CALL.
With the call info, you can get leg information by making a request to /legs. An example request would be structured like this:
## List Legscurl "https://voice.messagebird.com/calls/:callID/legs" \-H "Authorization: AccessKey :your_access_key:"
The leg information can be found in a result similar to this:
{"data": [{"id": ":legId","callId": ":callId","source": "31123456789","destination": "31123456777","status": "hangup","direction": "outgoing","duration": 31,"cost": 0.000385,"currency": "USD","createdAt": "2017-02-16T10:52:00Z","updatedAt": "2017-02-16T10:52:30Z","answeredAt": "2017-02-16T10:52:30Z","endedAt": "2017-02-16T10:52:30Z","_links": {"self": "/calls/:callId/legs/:legId"}},{"id": ":legId","callId": ":callId","source": "31123456789","destination": "31123456788","status": "hangup","direction": "incoming","duration": 31,"cost": 0.000385,"currency": "USD","createdAt": "2017-02-16T10:52:00Z","updatedAt": "2017-02-16T10:52:30Z","answeredAt": "2017-02-16T10:52:30Z","endedAt": "2017-02-16T10:52:30Z","_links": {"self": "/calls/:callId/legs/:legId"}}],"_links": {"self": "/calls/:callId/legs?page=1"},"pagination": {"totalCount": 2,"pageCount": 1,"currentPage": 1,"perPage": 10}}
Keep in mind that the data field is an array of legs. For our call flow example with the single record step, the API will return only one leg.
3. GET THE RECORDINGS FOR THE LEG.
After you have the leg ids, you can get the recording by making a request as such:
#curl "https://voice.messagebird.com/calls/:callID/legs/:legID/recordings"-H "Authorization: AccessKey :your_access_key:"
An example result of a recording request will be structured like this:
{"data": [{"id": ":recordingID:","format": "wav","legId": ":legID:","status": "done","duration": 7,"createdAt": "2017-05-17T11:42:57Z","updatedAt": "2017-05-17T11:43:04Z"}],"_links": {"self": "/recordings/:recordingID:","file": "/recordings/:recordingID:.wav"}}
Among other information, this result provides the file key which holds the URI for downloading the recording file. To download the recording, you need to do a request to that URI:
https://voice.messagebird.com/recordings/:recordingID.wav
A cURL example for this would be:
curl "https://voice.messagebird.com/recordings/:recordingID.wav" \-H "Authorization: AccessKey :your_access_key:"
Great! This request will download a wav file that holds the recording of that leg to your system.
Nice work! 🎉
You just learned how to retrieve information about calls!
Start building!
Want to build something similar but not quite sure how to get started? Feel free to let us know at support@messagebird.com; we'd love to help!
