Bridge APIs - Introduction

14 min

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:

<JoinBridge>

<LeaveBridge>

Bridge state changes are emitted as external events

Base URL

https://cpaas-api.in.exotel.com/v2/accounts/

Authentication

Use Basic Authentication.

Authorization: Basic <BASE64_APIKEY_APITOKEN> Content-Type: application/json

API credentials can be found in my.exotel.com → Developer Settings.

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.

{
  "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 [email protected] 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.