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 customers maximiseengage 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 the customer.


Step-by-Step Implementation Using Exotel Legs APIs


Step 1: Lead Selection and Dial Planning

Customer’s 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:
Customer is 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 the Customer’s 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, Customer 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 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.