Outbound Calling API

Overview

The Outbound Calling API allows the platform to initiate outbound voice calls via API and execute conversational flows during the call. It supports integrations with telephony systems such as PSTN and SIP.

Key Benefits

• Proactive Engagement: Enables outbound campaigns, alerts, and notifications

• Automation: Supports automated voice-based workflows and testing

• Interoperability: Integrates with external telephony systems (e.g., SIP, Genesys)

Core Capabilities

• Initiate outbound calls programmatically

• Execute flows during the call lifecycle

• Support multiple execution modes

• Detect call-answer types (live vs machine)

API Capabilities

Call Initiation

• Requires:

  • Organization ID

  • Flow ID

  • Destination (PSTN or SIP)

Execution Modes

Mode	Description
Synchronous	Waits for call completion (limited to ~30 seconds)
Polling	Returns immediately; status fetched via API
Webhook	Asynchronous updates sent via webhook

1. Synchronous (Blocking)

The HTTP connection is held open until the call reaches a terminal state (or the 30-second timeout). The full outcome is returned in the response body.

Best for: Very short flows that complete within 30 seconds. Use poll or webhook mode for longer calls.

1. Polling (Async)

Returns immediately with a session identifier and Queued status. The caller then polls GET .../calls/:sessionId at its own pace to check progress.

Best for: Backends that cannot hold connections open, or that want fine-grained status tracking without exposing a public endpoint.

1. Webhook (Event-Driven)

Returns immediately with a session identifier. The platform POSTs to your webhookUrl at each lifecycle event:

• When the call is answered (with AMD result if requested)

• When it fails before answer

• When it reaches a final state

Delivery is best-effort — failed deliveries are logged and not retried in the initial implementation.

Best for: Production event-driven integrations that need to react to call outcomes without polling.

Call Analysis (Answering Machine Detection)

• Detects:

  • Live person

  • Answering machine

  • Fax / unknown

• Flow execution can be condition-based (e.g., execute only for live answers)

  • Uses AI to detect destination type

Advanced Use Cases

• Automated Testing: Trigger flows across environments (e.g., QA → Prod)

• Back-to-back testing: Use flows to test other flows via voice calls

• Cross-platform calling: Call external providers (e.g., Twilio, Genesys)

Notes / Limitations

• No persistence beyond call completion

• Post-call data only available via reporting

• No scheduling (calls executed immediately)

• Semantic call analysis (AI-based detection) is future work