Transferring Voice Calls with MessageBird
In this MessageBird Tutorial you’ll learn how to handle and forward incoming voice calls by building a call flow powered by the MessageBird API.
Step 1: Create the call flow
A call flow describes the operations to be executed when a voice call is received or placed; the flow has one or more steps that are executed in sequence. A step action can be to transfer a call, pronounce a text to speech (TTS) message, playback an audio file, record the call or hang up.
Since we're interested in doing a transfer, we're going to create a call flow with one single step that transfers the call. The JSON object of the call flow we're going to "POST" to the API looks like this:
{"steps": [{"action": "transfer","options": {"destination": "31612345678"}}]}
Here’s the cURL command to create this call flow through the Voice API:
curl -X "POST" "https://voice.messagebird.com/call-flows" \-H "Content-Type: application/json" \-H "Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM" \-d $'{"steps": [{"options": {"destination": "31612345678"},"action": "transfer"}]}'
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
Here’s 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": ["31611111111"]}'
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, inthis 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
Dial the number you used in step 2 (:your_number). The call should be transferred to the number you defined in the destination parameter of the steps[].options object.
Step 4: Query call information
To get information about voice calls that were received, you can either query the API manually (List all calls), or you can subscribe to call status events by using webhooks (Webhooks and Handle callbacks).
Keep in mind
This tutorial uses a simple static call flow; the destination of the transfer is always the same. If you want to transfer a call dynamically, for example, based on the number that is calling or the time of day, you can also configure a "fetch" call flow that queries your web service via HTTP to obtain a call flow. This approach is outlined in the ‘Dynamic call flows’ section of our Voice Calling API documentation.
Nice work! 🎉
You just learned how to configure a flow for transferring voice 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!
