> ## Documentation Index
> Fetch the complete documentation index at: https://brokeros.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect Exotel (Indian Cloud Telephony)

> Configure Exotel as your outbound telephony carrier with ExoPhone virtual numbers and automated TRAI DND compliance.

**Exotel** is India's leading cloud telephony platform, widely used by enterprise real estate developers and property brokerages. It provides virtual pilot phone numbers (ExoPhones), automated call recording, and native integration with the Telecom Regulatory Authority of India (TRAI) Do-Not-Disturb (DND) scrubbing infrastructure.

The BrokerOS integration (`integrations/voice/telephony/exotel/`) connects directly to the Exotel v1 REST API to initiate outbound bridged calls and synchronize call records.

***

## Exotel Calling Pipeline

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Worker as BullMQ Voice Processor
    participant Dispatcher as Carrier Bridge Dispatcher
    participant ExotelAPI as Exotel API (api.in.exotel.com)
    actor Lead as Buyer Handset
    participant Applet as Exotel Call Flow Applet
    participant AI as AI Voice Persona

    Worker->>Dispatcher: tryCarrierBridgeDispatch('EXOTEL', sendOptions)
    Dispatcher->>Dispatcher: formatExotelNumber (Converts +91 to 0-prefixed format)
    Dispatcher->>ExotelAPI: POST /v1/Accounts/{sid}/Calls/connect.json
    ExotelAPI->>ExotelAPI: Check Number against TRAI DND Registry
    alt Number is DND Registered
        ExotelAPI-->>Dispatcher: Reject Call (TRAI DND Policy)
        Dispatcher-->>Worker: Mark Recipient DND_BLOCKED
    else Number is Clean
        ExotelAPI->>Lead: Outbound Phone Rings with ExoPhone Caller ID
        Lead->>ExotelAPI: Customer Answers Handset
        ExotelAPI->>Applet: Connect Customer to AI Voice Media Stream
        AI-->>Lead: Conducts Two-Way Property Consultation
        ExotelAPI-->>Dispatcher: 200 OK with Call SID (exo_call_123)
    end
```

***

## Required Credentials

To connect Exotel, collect the following credentials from your Exotel administrator dashboard:

| Credential Field | Parameter in BrokerOS | Description & Example |
| :- | :- | :- |
| **Account SID** | `Account SID` | Your Exotel Account SID (found under API Settings). |
| **API Key** | `API Key` | Secret API Key string used for Basic HTTP authentication. |
| **API Token** | `API Token` | Secret API Token string paired with your API key. |
| **Subdomain** | `Subdomain` | Your Exotel API cluster domain (e.g., `api.in.exotel.com` or `api.exotel.com`). Defaults to `api.in.exotel.com`. |
| **ExoPhone Number** | `From Numbers` | Your purchased Exotel virtual long number (e.g., `08047123456`). |

***

## Indian Phone Number Normalization (`formatExotelNumber`)

Exotel's telecom switchboard requires destination telephone numbers to be formatted in domestic Indian inter-state dialing format (starting with `0` followed by the 10-digit mobile number), rather than the international `+91` format:

```typescript theme={null}
// Automatic transformation performed by ExotelTelephonyClient:
"+91 98765 43210"  -->  "09876543210"
"9876543210"       -->  "09876543210"
```

The BrokerOS `ExotelTelephonyClient` automatically reformats international E.164 phone numbers to this required format prior to submitting the `connect.json` request.

***

## CRM Telephony PSTN Bridging Setup

To use Exotel as the primary company-wide carrier for human telecalling:

1. Navigate to **Dashboard -> Admin -> Settings -> CRM Telephony & WebRTC** (`/dashboard/admin/settings`).
2. Select the **Exotel Cloud Telephony** card.
3. Enter the following parameters:
   * **API Key**: Your Exotel API Key.
   * **API Token**: Secret API token.
   * **Account SID**: Your Exotel Account SID.
   * **API Subdomain**: Default is `api.exotel.com`.
   * **ExoPhone Virtual Number**: Your registered ExoPhone number (e.g., `080xxxxxxxx`).
4. Click **Save & Activate Carrier**.
5. When an agent clicks **Direct Call** on a lead profile, Exotel connects the agent's verified mobile phone to the lead, streams call events to `/api/crm/telephony/webhooks/exotel-status`, and uploads the audio recording to Vercel Blob storage.

***

## Marketing AI Voice Configuration Steps

**1. Retrieve API Credentials from Exotel**

Log in to `my.exotel.com`. Navigate to **Settings -> API Credentials**. Copy your **Account SID**, **API Key**, and **API Token**. Note your API subdomain (e.g., `api.in.exotel.com`).

**2. Identify Your Outbound ExoPhone Number**

Under **Numbers**, find the virtual long number assigned to your outbound calling flow.

**3. Add Carrier in BrokerOS Settings**

In the BrokerOS dashboard:

1. Navigate to **Dashboard -> Marketing -> Voice -> Settings**.
2. Select the **Gateways & Voice Platforms** tab (`/dashboard/marketing/voice/settings?tab=providers`).
3. Under the **Telephony Gateways** sub-tab, click **Add Carrier** and choose **EXOTEL**.
4. Enter an **Engine Label / Name** (e.g. `Exotel Mumbai Primary`).
5. Fill in **Account SID**, **API Key**, and **API Token**.
6. Set **Subdomain** to your cluster hostname (e.g. `api.in.exotel.com`).
7. Enter your ExoPhone virtual number in **From Numbers**.
8. Click **Save & Verify Carrier**. Credentials are encrypted with AES-256-GCM and stored in `VoiceTelephonyIntegration`.

**4. Test Connection & Verify Latency**

Click **Verify Carrier**. BrokerOS queries `https://${subdomain}/v1/Accounts/${accountSid}.json` to confirm authentication and measure network round-trip time.

**5. Perform a Pre-Flight Test Call**

Use the **Dual-Mode Test Call Modal** from the Agent Composer to place a live test call to your personal handset.

***

## TRAI DND Compliance Enforcement

The Telecom Regulatory Authority of India enforces strict penalties on commercial marketing calls placed to numbers registered in the National Do-Not-Call (NDNC) database:

* Exotel automatically checks the destination phone number against the TRAI registry in real time before ringing the subscriber handset.
* If the prospect is registered on the DND registry, the call is blocked at the telecom switch.
* BrokerOS detects this response and flags the recipient as `DND_BLOCKED` in the campaign call logs, preventing repeated call attempts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.