--- title: Bridge APIs - Introduction slug: voice-apis/bridge-apis-introduction docTags: createdAt: 2026-01-20T02:50:14.138Z --- A **Bridge** represents a multi-party audio conference that allows multiple **Legs** to be connected together. Bridges are commonly used for **conferencing**, **agent handoffs**, **supervisor monitoring**, and **multi-leg call flows**. Bridge APIs allow you to: - Create a bridge - Retrieve bridge details - Update bridge configuration - Dynamically join or remove legs using **Leg Actions** ## Key Concepts - A bridge exists independently of legs - A bridge becomes **active** when at least one leg joins - Legs are added or removed using: - \ - \ - Bridge state changes are emitted as **external events** ## Base URL :::BlockQuote [https://cpaas-api.in.exotel.com/v2/accounts/](https://cpaas-api.in.exotel.com/v2/accounts/\{AccountSID}) ::: ## Authentication Use **Basic Authentication**. :::BlockQuote Authorization: Basic \ Content-Type: application/json ::: API credentials can be found in **my.exotel.com → Developer Settings**. ## Related APIs - **POST /bridges** — Create a bridge - **GET /bridges/** — Get bridge details - **PUT /bridges/** — Update bridge configuration - **Leg Actions** — JoinBridge / LeaveBridge ## Notes for Developers - Bridge updates apply only to **future participants** - Active legs are not dropped when updating bridge configuration - Use **JoinBridge / LeaveBridge** Leg Actions to manage participants ## Dialer Implementation Guide using Exotel Legs APIs This guide shows you how to build an end-to-end predictive dialer on top of the Legs and Bridge APIs described above. ### Objective This document provides a detailed, implementation-ready plan for building a scalable, real-time **predictive dialer** using Exotel's programmable **Legs and Bridge APIs**. It is designed to help you engage leads at scale, maximize agent productivity, reduce wait time, and ensure precision in call flow orchestration using Exotel as a programmable telephony layer. ### Approach Summary - The customer's leg is dialed first using Exophones. - Call events are streamed in real time via gRPC to detect pickup and leg status. - Upon confirmation of pickup, an ideal agent is dynamically selected and dialled. - The agent leg can also be pre-dialled and held live using our nailed-up connection. - A waiting message (IVR) can be played to the customer until the agent is bridged. - Once both legs are active, a bridge is created to establish a conversation. - Calls can be recorded; all call metadata is accessible through the API and events. **Retry logic, timeouts, and CRM disposition updates are managed by you.** ### Step-by-Step Implementation Using Exotel Legs APIs ### Step 1: Lead Selection and Dial Planning Your backend dialer logic should dynamically determine whom to dial and when, using: - Real-time agent availability - CRM-driven lead prioritization - Historical lead pickup trends and SLA commitments **Responsibility:** You are responsible for implementing this logic and using Exotel APIs to programmatically control all legs and session cycles. ### Step 2: Initiate Customer Leg **API:** `POST /legs` - Use an Exophone DID as the caller ID. - Set `network_type` to `PSTN`. - Attach a `leg_event_endpoint` (gRPC) for real-time event tracking. - Set `timeout` and `time_limit` to define ringing and call duration. **Expected Events:** `leg_ringing`, `leg_answered`, `leg_terminated` ### Step 3: Handle Customer Leg Events When the following is received: - `leg_answered` Then: - Optionally play a message using `StartSay` or `StartPlay` (e.g., "Please hold…"). - Continue monitoring until agent leg is ready. Ensure IVR playback is stopped once the bridge is established. ### Step 4A: Dial Agent Leg On-Demand **API:** `POST /legs` - Trigger agent leg only after the customer leg is answered. - Use the same Exophone DID. - Attach `leg_event_endpoint` to track agent leg events. - **Important:** Use `reference_leg_sid` (customer leg SID) if your use-case involves connecting to the pre-defined agent. If you are allocating an agent dynamically on availability basis you can ignore this step. ```json { "contact_uri": "+91XXXXXXXXXX", "exophone": "080XXXXXXX", "reference_leg_sid": "2mF7xxxxxx", "custom_param": { "session_id": "sess-12345" } } ``` **Expected Events:** `leg_ringing`, `leg_answered`, `leg_terminated` ### Step 4B: (Optional) Pre-Dial Agent Leg - Create the agent leg **before the customer leg**, with a high `time_limit` (e.g., 1800 seconds). - Optionally play a hold tone or message using `StartSay`. - Use `GET /legs/{agent_leg_sid}` to poll for leg status (`status = answered`). - Once the customer answers, bridge them immediately with the pre-connected agent leg. This reduces latency and is useful when predictive decisions are made in advance. ### Step 5: Create Bridge Between Legs **API:** `POST /bridges` - Use both `leg_sids` (agent and customer) to create a bridge. - Attach `bridge_event_endpoint` to track `bridge_created`, `bridge_terminated`, and other events. Stop any active IVR playback on either leg before the bridge is initiated. ### Step 6: Enable Call Recording (Optional) **API:** `POST /bridges/{bridge_sid}/actions` - Initiate recording at the bridge level. - Exotel will emit `recording_available` events with URLs, metadata, and recording durations. ### Step 7: Post-Call Analytics and CRM Sync using events **API:** `GET /legs/{leg_sid}` - Retrieve: - Call duration - Termination reason - Recording links - Push this data to your CRM for: - Lead status updates - Retry and follow-up logic - Agent performance scoring ### Best Practices and Implementation Considerations | Area | Recommendation | | --------------------- | --------------------------------------------------------------------------------------------------------------- | | Event Delivery | Use gRPC endpoints for low-latency, ordered event streams. | | Bridging Consistency | Use `reference_leg_sid` to ensure connecting to a pre-defined agent with low latency. | | IVR Playback Handling | Use `StartSay` or `StartPlay` after customer leg is answered; stop playback once the bridge is created. | | Exophone Support | Fully supported for outbound PSTN legs; use as per your compliance and pickup-rate needs. | | Leg Identifiers | Use `leg_sid` as the unique reference for all API interactions; Exotel does not use a unified CallSid model. | | Retry Handling | Monitor `leg_failed_to_create`, `leg_terminated` | | Session Tracking | Use `custom_param.session_id` consistently across legs and bridges for traceability. | | Leg Status Polling | Use `GET /legs/{leg_sid}` to validate leg state (`initiated`, `ringing`, `answered`, `terminated`) when needed. | ### Conclusion Using Exotel's Legs and Bridge APIs, you can deploy a powerful, scalable predictive dialer that supports: - Fully API-driven orchestration of customer-agent calling - Real-time control using gRPC event streams - Flexible leg creation with IVR, AMD, and pre-connection support - Clean session tracking and CRM sync using custom\_param - Future-readiness with nailed-up connections and intelligent retry APIs. This design ensures operational efficiency, lead quality, and agent productivity—all while maintaining full control through Exotel's programmable voice stack. Please drop an email to [hello@exotel.com](mailto\:hello@exotel.com) or reach out to your account manager if you'd like support with sandbox setup, gRPC streaming samples, or reference flows to accelerate your implementation.