Skip to main content

​
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: