Create an outbound call with CML

View as Markdown

To start an outbound call driven by CML, send a request to the /markuplanguage/1/create endpoint with the call details and the URLs that Infobip uses during the call.

json

1POST /markuplanguage/1/create HTTP/1.1

2Host: {INFOBIP_BASE_URL}

3Authorization: App {INFOBIP_API_KEY}

4Content-Type: application/json

7 "callback": {

8 "url": "https://example.com/cml/answer",

9 "errorUrl": "https://example.com/cml/error",

10 "method": "POST"

11 },

12 "endpoint": {

13 "type": "PHONE",

14 "phoneNumber": "441234567890"

15 },

16 "notifyUrl": "https://example.com/cml/notify",

17 "from": "442012345678"

18}

The request body includes the following fields:

callback.url: URL of the webhook that serves the first set of markup language instructions when a call is answered.
callback.errorUrl: URL invoked when the url is unreachable. Failover actions are expected in response.
callback.method: HTTP method (GET or POST) to communicate with your webhooks.
notifyUrl: URL of the webhook where Infobip sends a post-call notification with a summary of the call.

After you submit the request:

Infobip calls the defined endpoint.
When the destination endpoint answers the call, Infobip notifies your callback url with the context of the outbound call and expects a set of CML actions in return.

If the callback url is unreachable or returns malformed CML actions, the Infobip platform sends an error notification to the errorUrl, which can reply with a new set of CML actions.

Synchronous machine detection

When starting an outbound call with Calls Markup Language, you can enable machine detection (voicemail detection) in synchronous mode. In this mode, after the call is answered, the Infobip platform performs machine detection first and only queries your callback url for actions after the detection is completed. If you enable end of message detection, your callback URL is called only after the end of message detection finishes. For example, if you configure machine detection to last 3 seconds and end of message detection to last 30 seconds, it can take up to 33 seconds after the call is answered before your callback URL receives the first request.

Synchronous machine detection is best suited for the following scenarios:

Compliance-driven flows: Debt collection, legal, or regulatory notices where you must play a specific message to voicemail or avoid voicemail entirely. If you need the message to start immediately after the voicemail greeting ends, synchronous mode with end of message detection provides that timing directly.
Divergent branch flows: When the response to a machine requires a different flow than the response to a human. For example, if a machine answers, drop a voicemail message and hang up. If a human answers, launch a full IVR.
Lower-volume, latency-tolerant calls: Business-to-business callbacks where a delay before the first prompt does not affect engagement.
Sensitive one-time codes: OTP or authentication callbacks where the code must not be spoken into voicemail. If a machine answers, skip playback and retry through another channel. Synchronous mode ensures this decision is made before any audio plays.

Asynchronous machine detection

When starting an outbound call with Calls Markup Language, you can enable machine detection (voicemail detection) in asynchronous mode. In this mode, after the call is answered, the Infobip platform directly queries your callback url with the call details and expects your webhook to respond with CML actions. In parallel, the platform starts machine detection and sends the result to the defined asyncUrl. The asyncUrl only needs to respond with a 200 OK status code and does not return CML actions. If end of message detection is enabled, the platform also sends the end of message result to the asyncUrl.

Asynchronous machine detection is best suited for the following scenarios:

Outbound dialer and contact center scenarios: Connect immediately to prevent the callee from hearing silence and hanging up. Use the machine detection result afterward to notify the agent or log the outcome.
High-volume automated campaigns: Appointment reminders, delivery notifications, or informational broadcasts where the opening message does not change based on the detection outcome. Play the message regardless and use the asynchronous result to drive the next step (retry, log, or escalate).
Latency-sensitive flows: Any case where end of message detection would otherwise block the first webhook response for longer than your flow can tolerate.

Was this page helpful?