The structure of a call
To understand how Messagebird handles calls, it can be helpful to be familiar with the general structure of how calls are created. This article will provide a short example to help lay the foundations of the terms that will be most helpful to understand how Messagebird fulfills calls and will provide links to documentation and other articles where you can dig deeper on the concepts touched on here.
An example with virtual phone numbers
A customer wants to call a customer service number for a support request, and dials the number listed online. They place the call and are transferred to the line of an agent who works at the company. They speak for a while and, having resolved the matter, both parties hang up.
This interaction describes a common use case that Messagebird's FlowBuilder helps to automate and one that we're used to from everyday life, but let's unpack it from the perspective of the Messagebird Voice API to highlight some key concepts.
Describing the structure
1. Placing the call & the first leg
When the customer places the call, the customer's phone service provider directs the call to the destination number specified. In the event that this is a virtual number provided by Messagebird, we will receive the call and begin the process of handling it. During this phase, a leg with an inbound direction will be created, representing the customer's original call placed to the destination number.
When the leg is first created, it will proceed through various stages that represent the user's real-time progression through the call. This begins with a starting status, followed by ringing and finally ongoing when the call has been picked up. It will remain in the ongoing state until some concluding event occurs like a hangup. Likewise, the call status as a whole will also undergo status updates that reflect the call's real-time progress. This information can be accessed during a call with the assistance of the Voice API, and a full list of statuses for both calls and legs can be found in this article.
2. Call Flow execution
To determine what should happen next for the inbound call, Messagebird executes the Call Flow associated with the number.
The actions that should be taken are defined by the steps property of the Call Flow which can either be done in FlowBuilder or via the Voice API. In the case described above, the only step will be a transfer to the terminating number of the agent who should receive the call.
3. Transfer step & the second leg
When Messagebird executes the transfer step to the new destination number, a new leg with an outbound direction gets created as we initiate the transfer of call from the virtual number to the new target. The agent receives this call and the client and agent have their conversation.
4. Hangup
When the call ends, the status of the legs involved in the call will all be updated to hangup, and the call status as a whole will be marked as ended.
Review of terms
Many terms were outlined in the above example. Here's a quick reminder of each:
| Term | Meaning |
|---|---|
| Call | The highest-level container to describe a telephone conversation or flow. Is constituted by each of its individual Legs |
| Leg | A segment of a call between a number and the Messagebird platform. Each leg taken as a collection will represent a Call. |
| Call Source | The number that originates the call. |
| Call Destination | The number or virtual number that is to receive the call. |
| Leg Direction | Leg Direction describes the telephone event from the perspective of the Messagebird Voice API. An inbound directed leg is one that is placed to a Messagebird virtual number or from a SIP trunk to the MessageBird platform and an outbound directed leg is one placed from the MessageBird platform to the PSTN or SIP destination. |
| Call Status | The status of the call as a whole. |
| Leg Status | The status of each leg that comprises the call. |
