Skip to main content

​
How Truedy Works

Truedy sits in the middle of three worlds:
  • Your product (backend, CRM, website, internal tools)
  • Voice infrastructure (real-time voice and 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 the voice infrastructure handles the low-level real-time session.

​
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 imported from connected voice providers 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 the voice infrastructure to start a conversation for that agent with the given phone number.
  4. The voice infrastructure talks to the telephony provider (Telnyx / Twilio / SIP) to actually dial the number.
  5. The callee answers, the voice infrastructure 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, 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 voice infrastructure fits in

The voice infrastructure is the underlying voice and conversation engine that Truedy orchestrates. Truedy:
  • Manages your agents, prompts, tools, and knowledge bases.
  • Translates those into provider-specific configurations.
  • Manages call lifecycle and maps provider events into a stable public API and webhooks.
  • Handles organization-level concepts (credits, limits, batch campaigns, analytics).
You almost never need to talk to the underlying voice service directly. Instead, think of Truedy as:
“Voice infrastructure + telephony + org/billing + analytics, exposed through 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. Voice infrastructure 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: