Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Outbound Calling API - User Guide

Overview

The Outbound Calling API enables external applications to programmatically initiate outbound voice calls and execute conversational flows on the platform. External systems such as iX Dialer, CRM platforms, customer engagement solutions, and demo orchestration tools can trigger a voice interaction using a single API request.

When a call is initiated, the platform dials the specified PSTN number or SIP destination. Once the recipient answers, the designated flow is launched with full persona integrity, ensuring that the configured voice, instructions, prompts, AI behavior, integrations, and business logic are applied from the very first interaction.

This capability allows organizations to automate customer outreach, notifications, testing scenarios, and voice-driven business processes while leveraging the full capabilities of conversational AI.

Key Benefits

Proactive Engagement

Initiate outbound calls for:

  • Appointment reminders

  • Service notifications

  • Policy renewals

  • Payment reminders

  • Customer follow-ups

  • Emergency communications

Automation

Automate voice-based workflows without requiring manual agent intervention.

Common scenarios include:

  • Customer verification

  • Information collection

  • Automated alerts

  • Workflow testing

  • Survey execution

Interoperability

Integrate seamlessly with telephony and contact center platforms including:

  • PSTN

  • SIP

  • Genesys

  • Twilio

  • CRM systems

  • iX Dialer

  • Demo orchestration platforms

Core Capabilities

The Outbound Calling API provides a complete framework for executing, tracking, and managing outbound conversations.

Programmatic Call Initiation

Initiate outbound voice interactions using a single API request.

Required information:

  • Organization ID

  • Flow ID

  • Destination Number (PSTN or SIP)

Full Flow Execution

Outbound calls execute the selected flow exactly as an inbound call would.

Supported capabilities include:

  • LLM interactions

  • Voice prompts

  • Text-to-Speech (TTS)

  • Data Actions

  • API integrations

  • Session variables

  • Conditional routing

  • Conversational AI agents

Flexible Result Delivery

Choose one of three response mechanisms:

  • Synchronous

  • Polling

  • Webhook

Session Variables

Inject contextual information at the time the call is created.

Examples:

  • Customer Name

  • Account Number

  • Policy ID

  • Appointment Details

  • CRM Reference Number

Call Analysis

Optionally detect whether the call was answered by:

  • Live Person

  • Answering Machine

  • Fax Machine

  • Unknown Recipient Type

Typical Workflow

Plain Text1External System2|3| POST Call Request4v5Outbound Calling API6|7v8Telephony Infrastructure9|10v11Recipient Answers12|13v14Flow Starts15|16v17Call Outcome Delivered18(sync / poll / webhook)Show more lines

MVP Scope

Included

✅ Outbound PSTN Calling

✅ SIP Calling

✅ Flow Execution

✅ Session Variables

✅ Call Analysis (AMD)

✅ Status Tracking

✅ Webhook Notifications

✅ API Key Authentication

Out of Scope

The following are not supported in the MVP release:

  • Scheduled or deferred calls

  • Batch or campaign dialing

  • Admin console/dashboard

  • Call recording management

  • Outbound SMS

  • Outbound chat channels

  • Time-based queuing

  • Long-term call persistence

Authentication

All endpoints require API Key authentication.

Authorization Header

HTTP1Authorization: Bearer <api_key>Show more lines

API Key Management

  • API keys are provisioned per organization.

  • API keys are securely stored in Secrets Manager.

  • Shared with the Headless Execution API.

Organization Isolation

Security is enforced at the organization level.

An API key:

✅ Can access flows belonging to its organization.

❌ Cannot access flows belonging to another organization.

❌ Cannot retrieve call information from another organization.

The system validates the orgId in every request against the API key.

Result Delivery Modes

Every call request must specify a delivery mode that determines how results are returned.

1. Sync Mode

Overview

The HTTP connection remains open until the call reaches a terminal state or a timeout occurs.

The complete call outcome is returned as part of the API response.

Best Suited For

  • Testing

  • Demos

  • Very short flows

Characteristics

Feature
Value

Processing Model

Blocking

Initial Response

Wait until completion

HTTP Response

200 OK

Maximum Wait Time

30 Seconds

Public Endpoint Required

No

Flow

Plain Text1POST Request2|3v4Call Initiated5|6v7Call Runs8|9v10Completed / Failed11|12v13Response ReturnedShow more lines

Timeout Handling

If a call exceeds 30 seconds:

HTTP1504 Gateway TimeoutShow more lines

The call continues running and can be tracked using:

HTTP1GET /calls/{sessionId}Show more lines

2. Poll Mode

Overview

The API immediately returns a Session ID.

The client periodically polls the platform to retrieve call progress and final outcomes.

Best Suited For

  • CRM systems

  • Backend services

  • Workflow engines

Characteristics

Feature
Value

Processing Model

Asynchronous

Initial Response

Immediate

HTTP Response

201 Created

Public Endpoint Required

No

Flow

Plain Text1POST Call2|3▼4201 Created5(SessionId)6|7▼8GET Status9|10▼11Queued12Ringing13Answered14CompletedShow more lines

3. Webhook Mode

Overview

The API immediately returns a Session ID and sends lifecycle updates to the configured webhook endpoint.

Best Suited For

  • Real-time integrations

  • Enterprise workflows

  • Event-driven architectures

Characteristics

Feature
Value

Processing Model

Event Driven

Initial Response

Immediate

HTTP Response

201 Created

Public Endpoint Required

Yes

Events Delivered

  • call.answered

  • call.failed

  • call.completed

Delivery Model

Webhook delivery is:

  • Best effort

  • Not retried in MVP

  • Logged on failure

Comparison of Result Delivery Modes

Feature
Sync
Poll
Webhook

Initial Response

After completion

Immediate

Immediate

HTTP Status

200 OK

201 Created

201 Created

Timeout Limit

30 seconds

N/A

N/A

Requires Public Endpoint

No

No

Yes

Suitable for Long Calls

No

Yes

Yes

Real-Time Notifications

No

No

Yes

Session Affinity in Poll Mode

Poll mode requires session affinity because Channel Gateway instances do not share a persistent call-state store.

Clients must:

  1. Store cookies returned in the initiation response.

  2. Include those cookies in subsequent status requests.

This ensures requests are routed to the same gateway instance.

Detailed Call Lifecycle

Session ID ownership (async modes): For poll and webhook modes, the Channel Gateway pre-generates the session ID at request time, persists it with Queued status, and returns it in the 201 Created response. The session ID is also forwarded to the Media Server in the outbound call request. When the recipient answers, the Media Server reports the answered call back to the Channel Gateway using this pre-assigned ID, enabling immediate session matching without an additional round-trip. For sync mode the session ID is generated at the same point but not returned until the call reaches a terminal state.

Queued

The call has been accepted and is waiting for telephony resources.

Ringing

The destination number is currently being dialed.

Answered

The recipient has answered.

At this point:

  • AMD executes (if enabled)

  • Session variables are injected

  • Flow execution begins

Completed

The call completed successfully because:

  • The flow reached an end node

  • The participant disconnected normally

  • The interaction finished successfully

Failed

The call could not be completed.

A failure reason is always provided.

Call Status Values

Status
Description

Queued

Request accepted and waiting to dial

Ringing

Destination is being dialed

Answered

Call was answered

Completed

Call completed successfully

Failed

Call failed

Failure Reasons

Value
Description

no_answer

Destination did not answer within the ring timeout (default 30 s)

busy

Destination was busy

trunk_unavailable

No telephony trunk was available at call time

unroutable_number

Destination number could not be routed (e.g. invalid region)

session_start_failed

Runtime Engine could not create a session upon call connection (flow not found, invalid flow configuration, or any other RTE rejection); a technical difficulty prompt is played to the recipient. Upfront flow ID validation is not performed.

flow_error

Unrecoverable error during flow execution after a session was successfully started

fax

AMD detected a fax machine; call was terminated without starting a flow session

answering_machine

AMD detected an answering machine and "answering_machine" was not in the callAnalysis array; call terminated without starting a flow session

unknown

AMD result was inconclusive and "unknown" was not in the callAnalysis array; call terminated without starting a flow session

Call Analysis (AMD)

Answering Machine Detection (AMD) allows the platform to determine who answered an outbound call before executing the flow.

Supported outcomes:

  • live_person

  • answering_machine

  • fax

The platform supports two mutually exclusive AMD approaches.

Option A — Channel-level AMD (callAnalysis: [...])

When callAnalysis is included in the request body as an array of accepted AMD outcomes, the Channel Gateway invokes the telephony infrastructure's built-in answering machine detection immediately upon pickup, before the Runtime Engine flow session is created. The flow session is created only if the detected result is in the array.

  • Valid values: live_person, answering_machine.

  • The AMD result is recorded as callAnalysisResult and included in all call outcome payloads (poll status, sync response, webhook callback).

  • Fast — uses audio-signal heuristics; result is available within a few seconds of pickup.

  • Lower accuracy — cannot understand language; may mis-classify noisy environments.

  • fax always terminates the call regardless of the array — no flow session is created.

callAnalysisResult

Meaning

Flow session started?

live_person

A human answered

Yes, if in callAnalysis array

answering_machine

An answering machine / voicemail greeting was detected

Yes if in array — flow can leave a message; No if omitted from array — call terminates

fax

A fax tone was detected

No — always terminates

unknown

AMD was inconclusive or timed out

Yes if in array; No if omitted — call terminates

Option B: Flow-Level Semantic Analysis

When callAnalysis is omitted, the flow session starts immediately on pickup with no AMD step. Flow designers can add an Agent node configured for call analysis to semantically analyse the initial audio.

  • Higher accuracy — language-level understanding can distinguish live greetings from machine greetings more reliably.

  • Requires flow authoring — the Agent node must be explicitly added and configured in the flow.

  • callAnalysisResult is absent from all call outcome payloads when this approach is used.

Recommendation for iX Demos: Start with callAnalysis: ["live_person"] for simplicity. If you also want to handle answering machines (e.g. to leave a voicemail), add "answering_machine" to the array. If accuracy is insufficient for a specific use case, implement flow-level semantic analysis instead.

Error Responses

All endpoints use a consistent error envelope:

HTTP
Code
Description

400

INVALID_REQUEST

Malformed request body or missing required fields

400

INVALID_DESTINATION

destinationNumber is not a valid E.164 number or SIP address

400

INVALID_WEBHOOK_URL

webhookUrl is missing, not HTTPS, or otherwise invalid

401

AUTH_HEADER_MISSING

Authorization header was not provided

401

INVALID_TOKEN

API key is invalid, revoked, or expired

403

PERMISSION_DENIED

Org does not have the outbound_calling permission, or the flow belongs to a different org

404

NOT_FOUND

Session identifier not found

429

RATE_LIMIT_EXCEEDED

API Gateway request throttle exceeded

504

SYNC_TIMEOUT

sync mode only: call did not complete within the maximum API Gateway timeout (30 s)

REST API Endpoints

Two endpoints. One to fire a call, one to check its status.

Method
Endpoint
Purpose

POST

/cgw/outbound/v1/orgs/:orgId/flows/:flowId/calls

Initiate an outbound call

GET

/cgw/outbound/v1/orgs/:orgId/calls/:sessionId

Get call status (for poll mode or after a sync timeout)

Initiate Outbound Call

Endpoint

POST /cgw/outbound/v1/orgs/{orgId}/flows/{flowId}/calls

Purpose

Triggers an outbound call and executes the selected flow.

Triggers an immediate outbound PSTN/SIP call using the specified flow. Behaviour after request acceptance depends on the mode field.

Path Parameters

Parameter
Type
Required
Description

orgId

UUID

Yes

Organisation UUID. Must match the org associated with the API key.

flowId

UUID

Yes

UUID of the flow to execute. The flow must belong to the org.

Request Body

Field
Type
Required
Description

destinationNumber

string

Yes

E.164 PSTN number (e.g. +15551234567) or SIP address (e.g. sip:user@domain.com)

callerId

string

No

The caller ID (ANI) presented to the destination, e.g. +15559990000 or a SIP URI. Strongly recommended — when omitted, the platform falls back to a synthetic local identifier that is not a routable caller ID and should not be relied on for production calls.

mode

enum

Yes

Result delivery mode: "sync", "poll", or "webhook"

variables

object

No

Key-value pairs injected into the flow as session variables at the start of the call. Accessible within flow nodes at runtime (e.g. use a customer name in a prompt). Not echoed in API responses.

callAnalysis

string[]

No

Array of accepted AMD outcome values that trigger flow session creation. AMD is enabled when present. Valid values: live_person, answering_machine. Results not in the array (or fax, which always terminates) cause the call to terminate without a session. The AMD result is always recorded in the call outcome. Omit to disable AMD.

webhookUrl

string

Conditional

Required when mode is "webhook". Receives a POST at each lifecycle event: call.answered, call.failed, call.completed.

webhookAuth

string

No

Optional shared secret. When provided, it is used as the HMAC-SHA256 key to compute the X-Signature header on every webhook callback (see Webhook Callback section). It is not forwarded as an Authorization header. Stored encrypted; never returned in any API response. Only meaningful when mode is "webhook".

metadata

object

No

Opaque key-value pairs for the caller's own correlation purposes. Not injected into the flow as session variables. Echoed verbatim in all responses (201, sync 200, GET 200, and webhook callbacks).

Response — poll or webhook mode (201 Created)

Returned immediately. The call is queued asynchronously.

Response — sync mode, call completed (200 OK)

Returned after the call reaches a terminal state. The HTTP connection is held open until completion or the 30-second API Gateway timeout.

Response — sync mode, call failed (200 OK)

Response — sync mode timeout (504 Gateway Timeout)

Returned when the call has not reached a terminal state within 30 seconds. The call continues processing and its status remains queryable via GET .../calls/:sessionId.

Get Call Status

Endpoint

GET /cgw/outbound/v1/orgs/{orgId}/calls/{sessionId}

Purpose

Returns the current or final status of a call.

Common use cases:

  • Poll Mode tracking

  • Retrieving results after Sync timeout

  • Monitoring active calls

Retrieves the current status of an outbound call. Can be called at any point during the call lifecycle — use it to poll for completion in poll mode, or to retrieve the final outcome after a sync timeout.

Path Parameters

Parameter
Type
Required
Description

orgId

UUID

Yes

Organisation UUID. Must match the org associated with the API key.

sessionId

UUID

Yes

UUID of the call session, returned by the initiation endpoint

Response (200 OK) — in-progress call

Response (200 OK) — completed call

Response Fields

Field
Type
Description

sessionId

UUID

UUID uniquely identifying this call session

flowId

UUID

UUID of the flow that was executed

status

enum

Current call status — see status table in Call Lifecycle

durationSeconds

number

Call duration in seconds. Only present when status is Completed and the call was answered.

failureReason

string

Only present when status is Failed — see failureReason values in Call Lifecycle

callAnalysisResult

enum

Only present when callAnalysis was provided. Values: live_person, answering_machine, fax, unknown

metadata

object

The metadata provided in the original request, echoed back for correlation

createdAt

string

ISO 8601 timestamp when the call was accepted

answeredAt

string

ISO 8601 timestamp when the recipient answered. Null if not yet answered.

completedAt

string

ISO 8601 timestamp when the call reached a terminal state. Null if still in progress.

Webhook Events

When mode is "webhook", the platform fires an HTTP POST to your webhookUrl at each of the following lifecycle events. Each payload includes an event field so your receiver can act without tracking state.

Event

event value

Fired when

Call answered

call.answered

Recipient picks up; callAnalysisResult included when callAnalysis is provided

Call failed

call.failed

Call fails at any stage — not answered, busy, fax detected, or flow error

Call completed

call.completed

Flow ends normally (Completed terminal state)

Receiver Authentication

Resolved — Webhook Payload Signing (X-Signature) X-Signature is implemented as an HMAC-SHA256 signature of the JSON body, computed using webhookAuth (the caller-supplied value from the initiation request) as the signing secret. There is no separate per-org signing secret, and webhookAuth is not forwarded as an Authorization header on callbacks — its only purpose is to sign the payload.

Webhook receivers should verify the X-Signature header to confirm a callback originated from the platform:

  1. webhookAuth — a shared secret supplied in the initiation request. If omitted, callbacks are still sent but signed with an empty secret (i.e. effectively unsigned) — supplying a strong secret is recommended for any production integration.

  2. X-Signature — sha256=<hex>, computed as HMAC-SHA256(webhookAuth, rawRequestBody). Recompute this over the exact raw body you received and compare against the header to verify integrity.

Recommended practice: always supply webhookAuth and verify X-Signature on every callback. Since webhookAuth is not sent as an Authorization header, it cannot be used by itself to gate access at your receiver — use a dedicated network/API-level control (e.g. a secret path segment or IP allowlist) if you also need to restrict who can call your endpoint.Each event callback is delivered on a best-effort basis. If the delivery attempt fails (non-2xx response or connection timeout), the failure is logged and the call status remains queryable via GET .../calls/:sessionId. No retries are performed in the initial implementation.

Request Headers

Header
Description

Content-Type

application/json

X-Signature

sha256=<hex> — HMAC-SHA256 signature of the raw request body, computed using webhookAuth as the secret. Allows you to verify the payload was sent by the platform and wasn't tampered with.

Payload — call.answered

Triggered when the recipient picks up. When callAnalysis is provided, AMD completes before the flow session is created, so callAnalysisResult is already available in this payload.

Sent when the recipient answers.

Payload — call.failed

Triggered when the call fails at any stage. callAnalysisResult is present when AMD caused the termination (e.g., failureReason: "fax" or "answering_machine" when the result was not in the callAnalysis array). For calls that fail after being answered, a call.answered was already sent before this.

Sent when the call fails.

Payload — call.completed

Triggered when the flow ends normally. callAnalysisResult is echoed from the earlier call.answered payload for convenience.

Sends when the call ends.

Webhook Security

Webhook payloads can be verified using HMAC-SHA256 signing.

Request Header

HTTP1X-Signature: sha256=<hex>Show more lines

Signature Generation

Plain Text1HMAC-SHA256(webhookAuth, rawRequestBody)Show more lines

Best Practices

  • Always provide a strong webhookAuth

  • Validate every callback signature

  • Use HTTPS only

  • Implement endpoint-level security

  • Use IP allowlisting when possible

Interaction Examples

Example 1: Poll Mode – Customer Renewal Call

An external CRM triggers a call to a customer, then polls for the outcome.

Step 1: Create the Call

HTTP1POST /cgw/outbound/v1/orgs/{orgId}/flows/{flowId}/callsShow more linesJSON1{2"destinationNumber": "+15551234567",3"mode": "poll",4"variables": {5"customerName": "Jane Doe",6"policyNumber": "POL-998877"7},8"callAnalysis": ["live_person"],9"metadata": {10"externalSessionId": "crm-task-54321"11}12}Show more lines

Response:

Step 2: Poll Call Status

JSON1{2"status": "Ringing"3}Show more lines

Step 3: Call Answered

JSON1{2"status": "Answered",3"callAnalysisResult": "live_person"4}Show more lines

Step 4: Call Completed

JSON1{2"status": "Completed",3"durationSeconds": 1874}Show more lines

Example 2: Webhook Mode – Demo Platform Integration

The iX Demos platform triggers a call and receives callbacks at each lifecycle event.

Example 3: Sync Mode – Short Demo Flow

A simple demo scenario where the caller can afford to wait for the result.

Request

JSON1{2"destinationNumber": "+15559876543",3"mode": "sync"4}Show more lines

Response

JSON1{2"status": "Completed",3"durationSeconds": 474}Show more lines

Example 4: Answering Machine Detected

AMD is enabled. The flow receives answering_machine as a session variable and plays a voicemail prompt before hanging up.

Error Responses

All API errors follow a common format.

JSON1{2"error": {3"code": "ERROR_CODE",4"message": "Human-readable description"5}6}Show more lines

HTTP Status
Code
Description

400

INVALID_REQUEST

Invalid request payload

400

INVALID_DESTINATION

Invalid PSTN/SIP destination

400

INVALID_WEBHOOK_URL

Invalid webhook configuration

401

AUTH_HEADER_MISSING

Missing authorization header

401

INVALID_TOKEN

Invalid API key

403

PERMISSION_DENIED

Access denied

404

NOT_FOUND

Session not found

429

RATE_LIMIT_EXCEEDED

Request limit exceeded

504

SYNC_TIMEOUT

Sync request exceeded timeout

Summary

The Outbound Calling API provides a secure, scalable, and flexible mechanism for initiating outbound voice conversations and executing conversational AI flows. With support for PSTN and SIP dialing, session variable injection, Answering Machine Detection (AMD), Sync/Poll/Webhook execution modes, status tracking, and webhook-based event notifications, organizations can build proactive customer engagement experiences, automated workflows, testing frameworks, and enterprise-grade voice integrations using a single API.

Last updated

Was this helpful?