Skip to main content

​
Agents & Calls Overview

This guide explains how the core runtime objects in Truedy relate:
  • Agents
  • Calls
  • Contacts & folders
  • Campaigns / batch calls
  • Telephony numbers
Understanding this relationship makes the rest of the guides and API feel much simpler.

​
Agents

An agent is the configuration for how a voice should behave:
  • Identity: name, description.
  • Voice: which voice to use.
  • Behavior: system prompt, temperature, language hints.
  • Knowledge: assigned knowledge bases.
  • Tools: HTTP/function tools it can call.
  • Call settings: recording, max duration, etc.
Agents do not exist in isolation – they are used whenever you place or receive calls.

​
Calls

A call is an individual interaction between an agent and an external participant:
  • Created via:
    • Dashboard test calls.
    • Public API: POST /api/public/v1/calls.
    • Batch campaigns (which internally generate many calls).
  • Has:
    • agent_id, phone_number, direction.
    • status (created, ringing, in_progress, completed, failed, etc.).
    • Duration and cost information.
    • Optional recording and transcript.
Calls are the main unit for:
  • Analytics (success rates, handle time, cost).
  • Webhooks (call.ended, call.failed, etc.).
  • Debugging (reading transcripts and metadata).

​
Contacts & folders

Contacts represent people/businesses you call:
  • Fields like phone_number, first_name, email, company_name, plus custom metadata.
  • Usually attached to folders, which group similar contacts or segments.
You mainly use contacts and folders when:
  • Running batch campaigns (e.g. call everyone in the “Q4 renewal” folder).
  • Reusing the same curated set of contacts across multiple campaigns.

​
Campaigns / batch calls

A campaign (batch call) is:
  • A configuration + schedule + a set of contacts to call.
  • Managed via the /batch-calls API and the batch calling dashboard.
It ties together:
  • One or more agents.
  • One or more telephony numbers to place calls from.
  • A contact source (folder, explicit contact IDs, inline contacts, or uploaded CSV).
  • A schedule (timezone, working days, call window, daily caps).
The batch engine then:
  • Generates campaign contacts with individual scheduled_at timestamps.
  • Fires calls on schedule, respecting your concurrency and rate limits.
  • Updates campaign stats and emits webhooks when statuses change.

​
Telephony numbers

Telephony numbers control how calls actually traverse the phone network:
  • Truedy-managed numbers: purchased through the Telephony section or API.
  • BYOC numbers: imported from your own provider (SIP, Telnyx/Twilio, etc.).
Numbers are:
  • Assigned to agents as inbound and/or outbound numbers.
  • Used by the call engine and campaigns to place calls.
If no suitable outbound number is configured, outbound calls will fail with a clear error.

​
How it all fits together

A typical outbound campaign might look like:
  1. You create and tune an agent.
  2. You configure telephony numbers and assign one outbound number to that agent.
  3. You import contacts into a folder.
  4. You create a campaign using that agent + folder and define scheduling rules.
  5. The batch engine creates campaign contacts and gradually spawns calls.
  6. As calls finish, you analyze results in the dashboard, via the API, or via webhooks.

​
Next steps