Getting Call Information with MessageBird
When voice calls are created on the MessageBird platform, they're available for querying through the Voice API's RESTful endpoints. In this MessageBird Tutorial you’ll learn the concepts, terminology and the available methods for retrieving information about calls.
Calls and legs
When a call is received or placed, a call resource is stored on our platform. A call object typically looks like this:
{"id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58","status": "ended","numberId": "206001de-a327-4dbb-9770-47c82ef18e82","createdAt": "2017-02-16T10:52:00Z","updatedAt": "2017-02-16T10:59:04Z","endedAt": "2017-02-16T10:59:04Z"}
During the life cycle of a call, one or more voice connections are made. We call these entities legs. Amongst other properties, a leg has a source (number or SIP URL), destination (number or SIP URL) and direction (“incoming’ or ‘outgoing”).
Calls have a "one to many" relation with legs, meaning a single call can have one or more legs. Typically, each incoming voice call has a leg with direction "incoming" and, based on the call flow that was executed, one or more legs with direction "outgoing". Legs with direction "outgoing" are created when a transfer step is executed.
A leg object typically looks like this:
{"id": "d4f07ab3-b17c-44a8-bcef-2b351311c28f","callId": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58","source": "31644556677","destination": "31612345678","status": "hangup","direction": "outgoing","createdAt": "2017-02-16T10:52:00Z","updatedAt": "2017-02-16T10:52:30Z","answeredAt": "2017-02-16T10:52:30Z","endedAt": "2017-02-16T10:52:04Z"}
Keep in mind that leg resources are created automatically by the platform during the lifecycle of a call; because of this, you can query them through the Voice API, but you cannot create them manually.
Retrieving call information
STEP 1: LISTING ALL CALLS
To query a list of all calls, you can use the following API endpoint:
GET https://voice.messagebird.com/calls
An example cURL command looks like this:
curl -X "GET" "https://voice.messagebird.com/calls" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
The response is a JSON object with a data array of call objects:
{"data": [{"id": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58","status": "ended","numberId": "6e143426-d7ea-11e6-bf26-cec0c932ce01","createdAt": "2017-02-16T10:52:00Z","updatedAt": "2017-02-16T10:59:04Z","endedAt": "2017-02-16T10:59:04Z","_links": {"self": "/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58"}},{"id": "ac07a602-dbc1-11e6-bf26-cec0c932ce01","status": "ended","numberId": "6e143426-d7ea-11e6-bf26-cec0c932ce01","createdAt": "2017-01-16T07:51:56Z","updatedAt": "2017-01-16T07:55:56Z","endedAt": "2017-01-16T07:55:56Z","_links": {"self": "/calls/ac07a602-dbc1-11e6-bf26-cec0c932ce01"}}],"_links": {"self": "/calls?page=1"},"pagination": {"totalCount": 2,"pageCount": 1,"currentPage": 1,"perPage": 10}}
You can find a detailed description of the call object in the ‘Call’ section of our Voice Calling API documentation.
To query a list of legs related to a call, you can use the following API endpoint:
https://voice.messagebird.com/calls/{callID}/legs
An example cURL command looks like this:
curl -X "GET" "https://voice.messagebird.com/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/legs" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"
The response is a JSON object with a data array of leg objects:
{"data": [{"id": "d4f07ab3-b17c-44a8-bcef-2b351311c28f","callId": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58","source": "31123456789","destination": "31123456777","status": "hangup","direction": "outgoing","createdAt": "2017-02-16T10:52:00Z","updatedAt": "2017-02-16T10:52:30Z","answeredAt": "2017-02-16T10:52:30Z","endedAt": "2017-02-16T10:52:04Z","_links": {"self": "/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/legs/d4f07ab3-b17c-44a8-bcef-2b351311c28f"}},{"id": "e60ca497-0cf3-4954-b74c-265e95633ec8","callId": "f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58","source": "31123456789","destination": "31123456788","status": "hangup","direction": "incoming","createdAt": "2017-02-16T10:52:00Z","updatedAt": "2017-02-16T10:52:04Z","answeredAt": "2017-02-16T10:52:30Z","endedAt": "2017-02-16T10:52:04Z","_links": {"self": "/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/legs/e60ca497-0cf3-4954-b74c-265e95633ec8"}}],"_links": {"self": "/calls/f1aa71c0-8f2a-4fe8-b5ef-9a330454ef58/legs?page=1"},"pagination": {"totalCount": 2,"pageCount": 1,"currentPage": 1,"perPage": 10}}
Awesome!
You can find a detailed description of the leg object in the ‘Leg’ section of our Voice Calling API documentation.
Receiving updates on calls
In addition to manually querying calls, you can also receive HTTP callbacks on your web service when calls are created and updated.
STEP 1: CONFIGURE A WEBHOOK FOR YOUR NUMBER
First, let’s create a webhook resource—a configuration object that is used for performing status callbacks. Here’s the endpoint to create a webhook for a number:
POST https://voice.messagebird.com/numbers/:your_number/webhookcurl -X POST https://voice.messagebird.com/numbers/31123456788/webhook-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM"-H "Content-Type: application/json"-d $'{"url": "https://example.com/messagebird/callback","token": "foobar"}'
STEP 2: HANDLING INCOMING CALLBACKS:
When a call is created or updated, the MessageBird platform does an HTTP POST request to the URL configured. An example POST body of a callback looks like this:
{"timestamp": "2017-08-24T09:44:37Z","items": [{"type": "call","event": "callUpdated","payload": {"id": "a3369d39-52d6-4b4d-b852-05a72b45c589","status": "ongoing","number": {"id": "13f38f34-7ff4-45b3-8783-8d5b1143f22b","number": "31123456788","callFlowId": "4e0d9601-ad9c-45dc-a1f7-e015119c741c","createdAt": "2017-03-16T13:49:24Z","updatedAt": "2017-08-23T15:16:16Z"},"legs": [{"id": "079f1437-9c18-49c2-91af-000c88fcd051","callId": "a3369d39-52d6-4b4d-b852-05a72b45c589","source": "31612345678","destination": "31123456788","status": "ongoing","direction": "incoming","createdAt": "2017-08-24T09:44:37Z","updatedAt": "2017-08-24T09:44:37Z","answeredAt": null,"endedAt": null}],"createdAt": "2017-08-24T09:44:37Z","updatedAt": "2017-08-24T09:44:37Z","endedAt": null}}]}
Your web service should respond with a 200 OK HTTP header.
You can find more information on the JSON structure and how to validate a callback in the ‘Handle webhooks callbacks section’ of our Voice Calling API documentation.
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!
