> ## 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.

# Phone Carriers (PSTN) Overview

> How BrokerOS connects to PSTN telephone carriers for AI voice broadcast campaigns and in-browser CRM WebRTC softphone calling.

Telecom carriers connect BrokerOS to the Public Switched Telephone Network (PSTN), providing the telephone numbers, SIP trunking lines, and audio channels required to ring physical mobile handsets and landlines.

In BrokerOS, telephony serves two distinct operational channels:

1. **AI Voice Marketing Campaigns**: Automated outbound voice broadcasts executed by background BullMQ workers and AI conversational personas, configured at `Dashboard -> Marketing -> Voice -> Settings`.
2. **Company-Wide Human CRM Softphone**: In-browser WebRTC and bridged PSTN telecalling used by pre-sales agents and sales executives, configured by administrators at `Dashboard -> Admin -> Settings -> CRM Telephony & WebRTC`.

BrokerOS integrates four enterprise carriers through unified provider adapters located in [`integrations/voice/telephony/`](https://github.com/trybrokeros/BrokerOS/blob/main/integrations/voice/).

***

## Two Telephony Architectures

### 1. In-Browser CRM WebRTC Softphone

For direct human agent calling from Lead and Broker profiles, BrokerOS utilizes [`CrmTelephonyModule`](https://github.com/trybrokeros/BrokerOS/blob/main/apps/api/src/crm-telephony/crm-telephony.module.ts):

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Agent as Pre-Sales Agent (Browser)
    participant UI as ActiveCallWidget ([ActiveCallWidget.tsx](https://github.com/trybrokeros/BrokerOS/blob/main/apps/web/features/telephony/components/ActiveCallWidget.tsx))
    participant API as CRM Telephony Controller (/api/crm/telephony)
    participant Carrier as Telecom Carrier (Twilio WebRTC / Exotel / Telnyx / Vobiz)
    actor Lead as Buyer Mobile Handset
    participant Blob as Vercel Blob Storage
    participant Groq as Groq Whisper AI

    Agent->>UI: Click "Direct Call" on Lead Profile
    UI->>API: POST /api/crm/telephony/call
    API->>Carrier: Generate WebRTC Token or Dispatch PSTN Bridge Call
    Carrier->>Lead: Outbound Phone Rings Customer Handset
    Lead-->>Agent: Two-Way Call Connected (Browser Audio or PSTN Bridge)
    Agent->>UI: Take Real-Time Notes & End Call
    Carrier->>API: Webhook Delivers Recording Audio
    API->>Blob: Upload MP3 to Vercel Blob Storage
    API->>Groq: Queue Groq Whisper Transcription & LLM Summarization
```

### 2. Marketing AI Voice Broadcasts

For high-volume AI voice broadcasts, BrokerOS uses the **Carrier Bridge Dispatcher** ([`tryCarrierBridgeDispatch`](https://github.com/trybrokeros/BrokerOS/blob/main/integrations/voice/bridge/carrier-bridge-dispatcher.ts)):

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Worker as BullMQ Voice Processor
    participant Dispatcher as CarrierBridgeDispatcher (@brokeros/int-voice)
    participant CarrierClient as Carrier Adapter (Vobiz / Exotel / Twilio / Telnyx)
    participant PSTN as Physical Carrier Network
    participant Gateway as WebSocket Media Gateway (/voice/stream)
    actor Lead as Buyer Mobile Phone

    Worker->>Dispatcher: tryCarrierBridgeDispatch(platform, sendOptions)
    Dispatcher->>CarrierClient: Dispatch Outbound Call via Provider Client
    CarrierClient->>PSTN: HTTP POST / SIP INVITE (toPhone, callerId, answerUrl)
    PSTN->>Lead: Cellular Phone Rings with Local Caller ID
    Lead->>PSTN: Customer Answers Handset
    PSTN->>Gateway: Connect Bidirectional Audio Stream (G.711 u-law)
    Gateway-->>Lead: Instant First Message Spoken by AI Persona
    PSTN-->>CarrierClient: HTTP 200 OK with Call SID / Request UUID
    CarrierClient-->>Dispatcher: Return SendVoiceResult (success: true, providerCallId)
    Dispatcher-->>Worker: Commit Call Status: IN_PROGRESS
```

***

## The `IVoiceTelephonyProvider` Contract

Every carrier adapter inside [`integrations/voice/telephony/`](https://github.com/trybrokeros/BrokerOS/blob/main/integrations/voice/) implements the standard TypeScript interface defined in `@brokeros/types`:

```typescript theme={null}
export interface IVoiceTelephonyProvider {
  readonly providerType: VoiceTelephonyType;
  
  // Validates API credentials and checks account status
  validateCredentials(credentials?: VoiceTelephonyCredentials): Promise<boolean>;
  
  // Initiates an immediate short verification test call
  testCarrierCall(
    toPhone: string,
    fromNumber: string,
    credentials?: VoiceTelephonyCredentials,
  ): Promise<{ success: boolean; callId?: string; error?: string }>;
}
```

***

## Supported Telephony Carriers

> **[Twilio](https://brokeros.mintlify.site/integrations/telephony/twilio.md)**
>
> **Primary Region**: Global (180+ Countries).
>
> Direct in-browser WebRTC VoIP calling via Twilio Voice SDK, TwiML call orchestration, programmable voice, and dual-channel call recording.

> **[Telnyx](https://brokeros.mintlify.site/integrations/telephony/telnyx.md)**
>
> **Primary Region**: Global (Private IP Network).
>
> Carrier-grade elastic SIP trunking built on a private global IP backbone. Delivers ultra-low conversational latency, automated Outbound Voice Profiles, and TeXML media streaming.

> **[Exotel](https://brokeros.mintlify.site/integrations/telephony/exotel.md)**
>
> **Primary Region**: India (Enterprise Cloud Telephony).
>
> India's leading cloud telephony platform. Provides virtual pilot numbers (ExoPhones), automated call recording, and native TRAI DND (Do Not Disturb) compliance scrubbing.

> **[Vobiz](https://brokeros.mintlify.site/integrations/telephony/vobiz.md)**
>
> **Primary Region**: India (Local Geographic CLI).
>
> Direct REST API and SIP trunking with Indian mobile and landline caller ID display. Delivers low domestic per-minute termination rates and dynamic XML answer callbacks.

***

## Carrier Feature Matrix

| Feature / Capability | Twilio | Telnyx | Exotel | Vobiz |
| :- | :- | :- | :- | :- |
| **CRM In-Browser WebRTC** | Native (Twilio Voice SDK) | PSTN Bridge | PSTN Bridge | PSTN Bridge |
| **Primary Protocol** | REST API & TwiML | REST API v2 & TeXML | REST API & Basic Auth | REST API & XML Callback |
| **Indian CLI Presentation** | Supported (Regulatory Docs) | International E.164 | Supported (Virtual ExoPhones) | Supported (Local City Numbers) |
| **Automated DND Scrubbing** | Custom Suppression Lists | Custom Suppression Lists | Built-in TRAI Registry Scrub | Handled via API |
| **Media Stream WebSocket** | Native Twilio Media Streams | Native TeXML Media Streams | Call Routing Applet | Dynamic Answer Callback |
| **Audio Transcoding** | G.711 u-law / Linear PCM | G.711 u-law / Opus | G.711 A-law / u-law | G.711 u-law (8kHz) |
| **Multiple From Numbers** | Supported (Number Inventory) | Supported (Number Inventory) | Supported (ExoPhone Group) | Supported (Trunk Pool) |

***

## Where to Configure Telephony

Depending on the operational use case, configure your carrier in the corresponding interface:

### 1. CRM Telephony & WebRTC Softphone (Company-Wide)

* **Path**: `Dashboard -> Admin -> Settings -> CRM Telephony & WebRTC` (`/dashboard/admin/settings`).
* **Target Table**: [`CrmTelephonyConfig`](https://github.com/trybrokeros/BrokerOS/blob/main/packages/prisma/schema.prisma).
* **Scope**: Single active company-wide carrier for all browser telecalling, direct lead profile calls, and call recording uploads.
* **Verification**: Built-in test call verification modal (`POST /api/crm/telephony/verify`).

### 2. AI Voice Broadcast Platforms (Marketing Suite)

* **Path**: `Dashboard -> Marketing -> Voice -> Settings -> Gateways & Voice Platforms` (`/dashboard/marketing/voice/settings`).
* **Target Table**: `VoiceTelephonyIntegration`.
* **Scope**: Outbound voice campaign batches and conversational AI pipelines.
* **Verification**: Trunk verification and latency benchmarking (`POST /api/marketing/voice/integrations/telephony/:id/verify`).

***

## Related Guides

* [In-Browser WebRTC Softphone Guide](https://brokeros.mintlify.site//docs/brokerage/pre-sales/softphone.mdx)
* [Connect Twilio](https://brokeros.mintlify.site//docs/integrations/telephony/twilio.mdx)
* [Connect Telnyx](https://brokeros.mintlify.site//docs/integrations/telephony/telnyx.mdx)
* [Connect Exotel](https://brokeros.mintlify.site//docs/integrations/telephony/exotel.mdx)
* [Connect Vobiz](https://brokeros.mintlify.site//docs/integrations/telephony/vobiz.mdx)
* [CRM Telephony API Reference](https://brokeros.mintlify.site//docs/api-reference/crm-telephony.mdx)


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