Developer Guide: Navigating Exotel's Programmable Voice APIs

6 min

Exotel offers three primary programmable Voice API families—Voice APIs, ExoML, and LeadAssist. Each suite caters to distinct execution patterns, control models, and UI dependencies. This guide helps developers select the right integration path based on architectural requirements, call flow complexity, and privacy needs.

Architectural Overview

API Suite	Control Model	Call Flow Definition	Core Purpose
Voice APIs	Server-Initiated (Push)	Dashboard / App Bazaar UI	Triggering outbound calls, pulling CDRs, simple click-to-call
ExoML	Event-Driven (Webhooks)	Pure Code (No UI Dependency)	Programmatic call flows, dynamic IVRs, leg-level manipulation
LeadAssist	Managed Proxy Allocation	Managed Rules	Privacy-safe 2-party proxy calls, virtual number masking

API Selection Decision Tree

flowchart TD
    Start(["What is the core Voice requirement?"])
    
    Start --> Outbound["Outbound Call Triggering"]
    Start --> Flow["UI-Free Call Flow Construction"]
    Start --> Privacy["Privacy & Number Masking"]

    Outbound --> VoiceV1["Voice API<br/>• REST POST Calls<br/>• UI/App Bazaar triggers<br/>• Post-Call CDR Syncing"]
    Flow --> ExoML["ExoML <br/>• Code-driven IVR flows<br/>• Leg-level call manipulation<br/>• Dynamic branching & AI"]
    Privacy --> LeadAssist["LeadAssist API<br/>• Proxy Allocations<br/>• Expiry Timers<br/>• PIN Verification"]

    style Start fill:#2d3748,color:#fff,stroke:#1a202c
    style VoiceV1 fill:#38a169,color:#fff,stroke:#2f855a
    style ExoML fill:#805ad5,color:#fff,stroke:#6b46c1
    style LeadAssist fill:#3182ce,color:#fff,stroke:#2b6cb0

1. Voice V1 APIs: REST-Driven Triggering & Reporting

The Voice V1 API suite provides a RESTful interface to trigger outbound calls and extract historical call data without maintaining active state on your backend during the call.

sequenceDiagram
    autonumber
    participant App as Your Application
    participant Exotel as Exotel Platform
    participant PSTN as Customer / PSTN
    participant Webhook as Your Webhook Endpoint

    App->>Exotel: REST HTTP POST (/Calls/connect)
    activate Exotel
    Exotel-->>App: 200 OK (Call SID)
    Exotel->>PSTN: Dial Outbound Call
    Exotel-->>Webhook: StatusCallback Webhook (in-progress, completed)
    deactivate Exotel

Key Capabilities:

Click-to-Call: Programmatically initiates a connection between two phone numbers using an ExoPhone virtual number.

Flow Triggering: Triggers outbound calls that drop recipients into pre-configured graphical IVR flows created in Exotel's App Bazaar UI.

Reporting & Recordings: Synchronously fetches Call Detail Records (CDRs), recording URLs, and telecom circle metadata.

When to Use: Outbound transactional calls, CRM click-to-call buttons, and post-call analytics ingestion.

When NOT to Use: When call routing needs to be constructed and altered dynamically in code during an active call.

2. ExoML APIs: Programmatic Call Flow Engine

ExoML (Exotel Markup Language) eliminates reliance on dashboard-based visual IVR builders. It allows developers to construct, version-control, and execute entire call flows directly in code via webhooks and XML verbs.

sequenceDiagram
    autonumber
    participant Caller as Caller (Leg A)
    participant Exotel as Exotel Engine
    participant App as Your Backend (Flow Engine)
    participant Destination as Callee (Leg B)

    Caller->>Exotel: Incoming Call / Event
    activate Exotel
    Exotel->>App: HTTP Webhook Request (Call State / Leg Event)
    activate App
    Note over App: Code constructs flow logic dynamically<br/>without graphical UI rules
    App-->>Exotel: ExoML Response (<Gather>, <Dial>, <Say>)
    deactivate App
    
    rect rgb(240, 248, 255)
        Note over Exotel, Destination: Leg-Level Manipulation
        Exotel->>Destination: Dial Leg B / Execute Leg Instructions
        Exotel->>Caller: Play Audio / Collect DTMF on Leg A
    end
    deactivate Exotel

Key Capabilities:

UI-Free Flow Construction: Build complex multi-stage IVRs completely within your application logic and Git repositories.

Leg-Level Manipulation: Target instructions to specific call legs asynchronously—placing individual callers on hold, executing targeted audio prompts, or performing warm agent transfers.

Dynamic Runtime Branching: Route calls conditionally based on live database lookups, customer state, or dynamic DTMF keypresses.

Real-time Media & AI Streaming: Pipe audio to external WebSocket streams for live transcription or generative AI voice assistant integration.

When to Use: Dynamic IVRs built inside code, applications requiring granular leg-level orchestration, and AI voicebot streaming.

When NOT to Use: Basic outbound triggers where a fixed visual dashboard flow or standard 2-party connection is sufficient.

3. LeadAssist APIs: Privacy Proxy & Masked Communication

LeadAssist is a domain-specific API engine designed to manage masked communications between two parties without exposing personal phone numbers.

sequenceDiagram
    autonumber
    participant App as Your Server
    participant LeadAssist as LeadAssist Engine
    participant Driver as Party A (Driver)
    participant Customer as Party B (Customer)

    App->>LeadAssist: REST POST /greenpin (Create Session Allocation)
    LeadAssist-->>App: 200 OK (Assigned ExoPhone Number)
    Note over Driver,Customer: Call Phase (Active Delivery Window)
    Driver->>LeadAssist: Dials Assigned ExoPhone Number
    activate LeadAssist
    LeadAssist->>Customer: Bridges Call Anonymously
    deactivate LeadAssist

Key Capabilities:

Dual-Sided Masking: Hides phone numbers for both caller and recipient using a shared virtual ExoPhone.

Dynamic Expiry: Sets custom lifespans on number mappings (e.g., active only for a 30-minute delivery window).

GreenPin Verification: Restricts connection access via optional dynamic PIN verification prompts.

When to Use: Rideshare apps, last-mile delivery, and two-sided buyer/seller marketplaces.

When NOT to Use: Internal contact centers, general IVRs, or standard business telephony calls.