Calls Markup Language
Calls Markup Language (Calls ML or CML) is a voice feature designed for developers and available through the API only. You can use Calls ML to create any application to handle inbound and outbound calls. Your application implements the voice scenario logic and uses the Calls Markup Language to control and run actions in calls and conferences.
Differences between Calls API and Calls Markup Language
The event-driven model of Calls API relies on a continuous, real-time conversational loop between the voice platform and the developer's back end. For each discrete occurrence during a call, the platform dispatches an asynchronous webhook event. These events include a call being answered, a DTMF key being pressed, or an audio file finishing playback. The developer's server must then process this event and issue a corresponding API request to dictate the next action.
In contrast, Calls ML simplifies this interaction by using a declarative document (JSON) containing a sequential set of instructions (for example, speak text, record audio, dial a number). Instead of a continuous back-and-forth for each micro-action, the voice platform requests this instruction sheet at important execution milestones. It then parses and runs the specified sequence autonomously without needing constant round-trips to the developer's back end.
These two methods optimize for different developer experiences and technical scenarios:
- Event-driven method with Calls API: Best suited for dynamic, complex applications that maintain call state. It offers flexible, real-time control over the call session. This makes it a good choice for solutions such as contact centers (CCaaS), live agent routing, real-time AI voice assistants, or workflows that require repeated mid-call database lookups. The tradeoff is higher developer overhead, because the back end must maintain call state and handle a high volume of asynchronous webhooks.
- Markup language method with Calls Markup Language: Best suited for simplicity and low latency. It uses a set of actions that are readable and require little code, so the behavior is easy to predict. This makes it a good choice for linear or standard call flows, such as interactive voice response (IVR) menus, automated phone alerts, anonymous call forwarding, or voicemail dropping. It reduces server infrastructure requirements and speeds up development for common voice applications.
CML actions
The Calls Markup Language is composed of individual actions that give instructions to the Infobip voice platform. The following table lists the actions available through Calls Markup Language.
| Action | Description |
|---|---|
play | Play an audio file from a URL. |
say | Play text-to-speech content. |
captureDtmf | Collect digits with an optional barge-in prompt. |
dial | Bridge to a phone, SIP, WebRTC, Viber, or WhatsApp endpoint. |
record | Record the call leg. |
startRecording / stopRecording | Fine-grained recording control. |
pause | Wait a specified number of seconds. |
fetch | Load the next set of CML actions from a URL. |
hangup | End the call. |
Calls Markup Language does not support conferencing, streaming, speech capture, or call real-time transcription.
For the complete reference to all Calls Markup Language actions, see the API documentation.