> ## 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.

# Agents & Calls Overview

> Understand how agents, calls, campaigns, contacts, and numbers fit together in Truedy

# 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

* Learn how to [create and configure agents](/guides/creating-an-agent).
* Make your first call in depth: [Making Your First Call](/guides/making-your-first-call).
* Explore high-volume usage: [Batch Calls & Campaigns Overview](/guides/batch-calls-and-campaigns-overview).