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

# How TopCalls Works

> Understanding the architecture and capabilities of the TopCalls platform.

## Platform Overview

TopCalls bridges traditional telephony (SIP/PSTN) and modern AI to automate phone interactions at scale. We handle the hard parts: telephony infrastructure, AI orchestration, audio processing, and compliance tooling. You focus on what your agents say and do.

## What TopCalls Does

<CardGroup cols={2}>
  <Card title="Telephony Infrastructure" icon="phone">
    SIP trunking, carrier registration, number provisioning, and audio streaming. No telecom expertise needed.
  </Card>

  <Card title="AI Orchestration" icon="brain">
    Real-time speech recognition, intelligent conversation handling, and natural voice synthesis. All optimized for phone conversations.
  </Card>

  <Card title="Campaign Management" icon="list-check">
    Queue management for automated outbound calls with retry logic, timezone awareness, and compliance tooling.
  </Card>

  <Card title="Analytics & Insights" icon="chart-bar">
    Automatic call summaries, sentiment analysis, structured data extraction, and reporting.
  </Card>
</CardGroup>

## System Architecture

```
┌──────────────────────────────────────┐
│   Your Application / SaaS App        │
│   (User Management, Campaigns,       │
│    Analytics Dashboard)              │
└──────────────┬───────────────────────┘
               │
               │ REST API
               ▼
┌──────────────────────────────────────┐
│   TopCalls Voice Gateway             │
│                                      │
│   ✅ Call Execution & Control        │
│   ✅ AI Conversation Handling        │
│   ✅ Campaign Queue & Dispatch       │
│   ✅ Quota Management                │
│   ✅ Transcript & Recording          │
│   ✅ Post-Call Analysis & Webhooks  │
│   ✅ Telephony Infrastructure        │
│   ✅ Audio Processing & Streaming    │
└──────────────────────────────────────┘
```

## Conversation Modes

TopCalls supports two modes, each optimized for different use cases:

### Realtime Mode (Recommended)

Speech-to-speech processing for the most natural conversations.

| Feature       | Details                                                     |
| ------------- | ----------------------------------------------------------- |
| **Latency**   | Ultra-low (\~200-500ms)                                     |
| **Voices**    | Preset voices (default: `alloy`)                            |
| **Languages** | Auto-detects, works best with explicit instructions         |
| **Best For**  | Customer support, appointment management, inbound reception |

<Note>
  Realtime Mode provides the most natural conversations with the lowest latency. Use `mode: "realtime"` in your API calls.
</Note>

### Legacy Mode (Maximum Customization)

Separate speech recognition, language model, and voice synthesis for full control over each stage.

| Feature       | Details                                                |
| ------------- | ------------------------------------------------------ |
| **Latency**   | Standard (\~300-600ms)                                 |
| **Voices**    | Hundreds of built-in voices + voice cloning            |
| **Languages** | 36+ languages with explicit dialect control            |
| **Best For**  | Brand-specific personas, voice cloning, multi-language |

Check available models and voices via `GET /v1/models` and `GET /v1/voices/builtin`.

<Note>
  Legacy Mode gives you full control over voice, language, and model selection. Use `mode: "legacy"` in your API calls.
</Note>

## The Call Lifecycle

Every call goes through these stages:

<Steps>
  <Step title="1. Call Creation">
    You trigger a call via API (`POST /v1/calls`) or it's dispatched from a campaign. The system validates your request and reserves quota.
  </Step>

  <Step title="2. Dispatch">
    The call is dispatched to our telephony infrastructure. Status changes to `queued` then `in_progress`.
  </Step>

  <Step title="3. Connection">
    The recipient picks up. The AI immediately greets them with the `first_sentence` you configured.
  </Step>

  <Step title="4. Conversation">
    Audio streams in real-time. The AI:

    * Transcribes speech
    * Processes with the language model (with knowledge base context if configured)
    * Responds naturally with voice synthesis
    * Executes tools/functions as needed
    * Can end the call gracefully when the conversation is complete
  </Step>

  <Step title="5. Completion">
    Call ends (either by user or AI). The system:

    * Captures final transcript
    * Fetches recording URL (available \~15s after call ends)
    * Generates call summary (if configured)
    * Extracts structured data from transcript (if `analysis_schema` provided)
    * Maps analysis fields to outcomes using `outcome_mapping` rules
  </Step>

  <Step title="6. Webhook Delivery">
    Your server receives a webhook with complete call details including transcript, recording URL, call summary, structured analysis data, and all custom metadata.
  </Step>
</Steps>

## Key Features

### Intelligent Routing

Automatically detect voicemail, IVR systems, or human answers. Route accordingly or handle each scenario with custom logic.

### Function Calling

Give your AI agents tools to interact with your systems during calls: book appointments, look up orders, update CRMs, process payments, and end calls gracefully.

### Knowledge Base Injection

Add text entries with the product, pricing, and policy details your agents need. The AI automatically accesses the attached context during conversations.

### Structured Data Extraction

Define schemas to extract specific information from calls: "Did the customer agree to a demo?", "What objections were raised?", "What's the next step?"

### Multi-Language Support

36+ languages with proper dialect control. Use for operations across multiple regions.

## What You Control

| Aspect                | Your Control                                            |
| --------------------- | ------------------------------------------------------- |
| **AI Instructions**   | Full control over persona, goals, and behavior          |
| **Voice Selection**   | Choose from built-in voices or use custom/cloned voices |
| **Call Flow**         | Define first sentence, handle objections, set goals     |
| **Tools & Functions** | Integrate with your systems in real-time                |
| **Knowledge**         | Provide context via knowledge bases                     |
| **Analytics**         | Define what data to extract from calls                  |

## What We Handle

| Aspect                 | TopCalls Responsibility                                          |
| ---------------------- | ---------------------------------------------------------------- |
| **Telephony**          | SIP trunking, carrier management, number provisioning            |
| **Audio Processing**   | Real-time streaming, VAD, echo cancellation                      |
| **AI Orchestration**   | Speech recognition, language model, and voice synthesis pipeline |
| **Infrastructure**     | Scaling, reliability, monitoring                                 |
| **Compliance Tooling** | Features to help honor local calling laws (TCPA/TSR/DNC, GDPR)   |

<Note>
  **Compliance Responsibility**: TopCalls provides production-ready compliance tooling, but customers remain responsible for ensuring lawful use of the platform.
</Note>

## Next Steps

<CardGroup cols={2}>
  <Card title="AI & Voice Customization" icon="microphone" href="/concepts/ai-voice">
    Control your agent's personality, voice, and behavior.
  </Card>

  <Card title="Campaign Management" icon="bullhorn" href="/concepts/campaigns">
    Scale your outbound calling with campaign features.
  </Card>
</CardGroup>