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

# How Truedy Works

> High-level overview of Truedy, Ultravox, telephony providers, and your app

# How Truedy Works

Truedy sits in the middle of three worlds:

* **Your product** (backend, CRM, website, internal tools)
* **Ultravox** (real-time voice + conversation engine)
* **Telephony providers** (phone numbers and PSTN/SIP connectivity)

This page gives you the mental model you need before diving into any deep guide or API reference.

## Who this is for

* **Developers / tech leads** planning an integration.
* **Ops / support leaders** who want to understand what Truedy is actually doing under the hood.

If you only remember one thing: **Truedy orchestrates agents, calls, numbers, tools, and knowledge around your organization**, while Ultravox handles the low-level voice intelligence.

## Core building blocks

At a high level, Truedy manages these core objects for your organization:

* **Organizations**: Your workspace in Truedy. Everything (agents, calls, campaigns, contacts) is scoped to an org.
* **Agents**: AI voice agents configured with a voice, system prompt, tools, and knowledge bases.
* **Voices**: Voice identities (usually imported from providers like ElevenLabs) that agents speak with.
* **Telephony numbers**: Phone numbers that can place and receive calls (Truedy-managed or BYOC).
* **Contacts & folders**: People or businesses you call, usually organized into folders for campaigns.
* **Batch calls / campaigns**: High-volume outbound campaigns that schedule calls to many contacts.
* **Calls**: Individual call records (status, duration, transcript, recording, cost).
* **Webhooks**: HTTP callbacks that notify your system when calls or campaigns change state.

All of these live in Truedy’s database and are exposed both via the **dashboard** and the **Public API**.

## High-level architecture

Conceptually, a typical outbound call looks like this:

1. Your app or a dashboard action **creates a call** via Truedy (`POST /calls`) or triggers a batch campaign.
2. Truedy validates your organization, agent, and telephony configuration.
3. Truedy asks **Ultravox** to start a conversation for that agent with the given phone number.
4. Ultravox talks to the **telephony provider** (Telnyx / Twilio / SIP) to actually dial the number.
5. The callee answers, Ultravox runs the conversation using the agent’s prompt, tools, and knowledge.
6. When the call ends, Truedy stores the **call record, transcript, and recording**, updates analytics, and optionally emits **webhooks** (e.g. `call.ended`).

For inbound calls, the flow is similar but starts from the telephony side: a number forwards to Truedy/Ultravox, which routes to the right agent.

## Dashboard vs API vs webhooks

There are three main ways you interact with Truedy:

* **Dashboard**
  * Configure agents, voices, tools, telephony, and batch campaigns.
  * Monitor calls, transcripts, analytics, and billing.
  * Configure webhooks and API keys.
* **Public API**
  * Create and manage agents, calls, contacts, campaigns, and other resources programmatically.
  * Best for integrating Truedy into your backend, workflows, and internal tools.
* **Webhooks**
  * Receive real-time events back into your system when things happen (call started/ended, batch completed, etc.).
  * Best for analytics pipelines, CRMs, and automations that need to react to calls.

Most production setups use **all three**:

* Configure most things in the dashboard.
* Use the API to trigger calls and campaigns or sync data.
* Use webhooks to keep your systems in sync with Truedy activity.

## Where Ultravox fits in

Ultravox is the underlying **voice and conversation engine** that Truedy builds on top of. Truedy:

* Manages your **agents, prompts, tools, and knowledge bases**.
* Translates those into Ultravox-specific configurations.
* Manages **call lifecycle** and maps Ultravox events into a stable public API and webhooks.
* Handles **organization-level concepts** (credits, limits, batch campaigns, analytics).

You almost never need to talk to Ultravox directly. Instead, think of Truedy as:

> “Ultravox + telephony + org/billing + analytics, wrapped into a single, clean API and dashboard.”

## Data flow at a glance

Here is the simplified data flow for a call:

1. **Your system** (or the dashboard) calls the Truedy API.
2. **Truedy backend** validates the request, fetches org + agent configuration, and prepares the call.
3. **Ultravox** handles the live conversation and routing to the telephony provider.
4. **Telephony provider** places the call over PSTN/SIP.
5. **Truedy** stores call data, transcripts, and analytics, and dispatches **webhooks** back to your system.

## Next steps

Now that you have the big picture, continue with:

* [Prompting & Agent Design Basics](/guides/prompting-and-agent-design-basics)
* [Agents & Calls Overview](/guides/agents-calls-overview)
* [Telephony](/api-reference/telephony)
* Or follow the guided path: [Your First Hour with Truedy](/guides/your-first-hour-with-truedy)