Making Outbound Calls

Outbound calls let your agents proactively reach out to contacts — for appointment reminders, sales follow-ups, lead qualification, notifications, and more. This guide walks through placing a single call via the API, handling the response, and monitoring call progress.

Need to call hundreds or thousands of contacts? Use Batch Calls instead. This guide focuses on one-off, programmatically triggered calls.

Prerequisites

Before placing an outbound call, verify that:

You have an active agent — the agent must be published, not in draft. You can confirm this in the dashboard under Agents, or by checking status: "active" on the agent object.
A phone number is assigned to the agent — outbound calls are placed from a Truedy number that belongs to your account and is linked to the agent. If no number is assigned, the call will fail immediately with a no_phone_number_configured error.
You have a valid API key — all API requests require Authorization: Bearer YOUR_API_KEY in the request headers.

You can assign a phone number to an agent from the dashboard under Settings → Phone Numbers, or programmatically via the phone numbers API.

Placing a Call

Send a POST request to /calls with the agent and destination phone number.

Endpoint

POST https://api.truedy.ai/api/public/v1/calls

Request Body

Field	Type	Required	Description
`agent_id`	string	Yes	The ID of the agent that will handle the call
`phone_number`	string	Yes	The destination phone number in E.164 format (e.g. `+14155551234`)
`variables`	object	No	Key-value pairs for template substitution in the agent’s prompt
`from_number`	string	No	Override the caller ID (must be a number assigned to the agent). If omitted, Truedy picks from the agent’s assigned outbound numbers automatically
`call_settings`	object	No	Per-call overrides for recording, greeting, and timeouts (see below)

call_settings fields (all optional):

Field	Type	Description
`recording_enabled`	boolean	Whether to record this call. Default: `true`
`transcription_enabled`	boolean	Whether to transcribe this call. Default: `true`
`greeting`	string	Override the agent’s opening line for this call only
`max_duration`	string	Max call duration, e.g. `"1800s"`. Overrides agent default
`join_timeout`	string	Timeout for callee to answer, e.g. `"30s"`. Overrides agent default

About `variables`

Your agent’s prompt can include template placeholders using double curly braces: {{first_name}}, {{appointment_date}}, etc. When you pass a variables object with the call, Truedy substitutes those values into the prompt before the conversation starts. This lets a single agent handle personalised calls at scale without creating separate agents per contact. For example, a prompt containing:

You are calling {{first_name}} to confirm their appointment on {{appointment_date}} at {{appointment_time}}.

…would be rendered with the values you pass in variables.

Examples

curl -X POST https://api.truedy.ai/api/public/v1/calls \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_01hx2a7b3cd4ef5gh6ij7kl8mn",
    "phone_number": "+14155551234",
    "variables": {
      "first_name": "Sarah",
      "appointment_date": "April 10th",
      "appointment_time": "2:00 PM"
    }
  }'

import requests

response = requests.post(
    "https://api.truedy.ai/api/public/v1/calls",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "agent_id": "agent_01hx2a7b3cd4ef5gh6ij7kl8mn",
        "phone_number": "+14155551234",
        "variables": {
            "first_name": "Sarah",
            "appointment_date": "April 10th",
            "appointment_time": "2:00 PM",
        },
    },
)

call = response.json()
print(call["id"])      # call_01hx3k9p2qw7v8n4m6j5r0y1tz
print(call["status"])  # queued

const response = await fetch("https://api.truedy.ai/api/public/v1/calls", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agent_id: "agent_01hx2a7b3cd4ef5gh6ij7kl8mn",
    phone_number: "+14155551234",
    variables: {
      first_name: "Sarah",
      appointment_date: "April 10th",
      appointment_time: "2:00 PM",
    },
  }),
});

const call = await response.json();
console.log(call.id);     // call_01hx3k9p2qw7v8n4m6j5r0y1tz
console.log(call.status); // queued

Response

A successful request returns HTTP 201 Created with the newly created call object:

{
  "id": "call_01hx3k9p2qw7v8n4m6j5r0y1tz",
  "status": "queued",
  "direction": "outbound",
  "agent_id": "agent_01hx2a7b3cd4ef5gh6ij7kl8mn",
  "phone_number": "+14155551234",
  "from_number": "+18005559876",
  "duration_seconds": null,
  "transcript": null,
  "recording_url": null,
  "variables": {
    "first_name": "Sarah",
    "appointment_date": "April 10th",
    "appointment_time": "2:00 PM"
  },
  "created_at": "2024-04-05T14:21:58Z",
  "started_at": null,
  "ended_at": null
}

The id field is the call identifier you will use to poll for status or match against webhook events.

Monitoring Call Progress

Once you have the call ID, you can track the call to completion using polling or webhooks.

Option 1: Polling

Call GET /calls/{id} repeatedly until the status reaches a terminal state (ended, failed, or cancelled).

import requests
import time

CALL_ID = "call_01hx3k9p2qw7v8n4m6j5r0y1tz"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}
TERMINAL_STATUSES = {"ended", "failed", "cancelled"}

while True:
    response = requests.get(
        f"https://api.truedy.ai/api/public/v1/calls/{CALL_ID}",
        headers=HEADERS,
    )
    call = response.json()

    print(f"Status: {call['status']}")

    if call["status"] in TERMINAL_STATUSES:
        break

    time.sleep(5)  # wait 5 seconds before checking again

print(f"Call finished with status: {call['status']}")
if call["status"] == "ended":
    print(f"Duration: {call['duration_seconds']}s")
    print(f"Outcome: {call['outcome']}")

const CALL_ID = "call_01hx3k9p2qw7v8n4m6j5r0y1tz";
const HEADERS = { Authorization: "Bearer YOUR_API_KEY" };
const TERMINAL_STATUSES = new Set(["ended", "failed", "cancelled"]);

async function pollCall(callId) {
  while (true) {
    const response = await fetch(
      `https://api.truedy.ai/api/public/v1/calls/${callId}`,
      { headers: HEADERS }
    );
    const call = await response.json();

    console.log(`Status: ${call.status}`);

    if (TERMINAL_STATUSES.has(call.status)) {
      return call;
    }

    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

const call = await pollCall(CALL_ID);
console.log(`Call finished: ${call.status}`);

Polling is simple but inefficient. Avoid polling intervals shorter than 5 seconds, and prefer webhooks for any integration processing more than a few dozen calls per day.

Option 2: Webhooks (Recommended)

Register a webhook endpoint and Truedy will deliver a call.ended event to your server automatically when the call finishes — no polling required. See Webhooks Overview to set up your endpoint. The call.ended event payload includes the full call object, including transcript and recording URL.

Phone Number Format

The phone_number field must use E.164 format:

Starts with +
Followed by the country code and subscriber number, no spaces or dashes
Examples: +14155551234 (US), +447911123456 (UK), +61291234567 (AU)

Passing a phone number in any other format (e.g. (415) 555-1234, 415-555-1234, or 14155551234 without the leading +) will result in a 422 Unprocessable Entity error.

Common Errors

HTTP Status	Error Code	Meaning	Resolution
`404 Not Found`	`agent_not_found`	No agent exists with the given `agent_id`	Verify the agent ID in your dashboard
`422 Unprocessable Entity`	`no_phone_number_configured`	The agent has no outbound number assigned	Assign a phone number to the agent in Settings → Phone Numbers
`422 Unprocessable Entity`	`invalid_phone_number`	`phone_number` is not valid E.164 format	Reformat the number (e.g. `+14155551234`)
`422 Unprocessable Entity`	`agent_not_active`	The agent is in draft or paused state	Publish the agent before placing calls
`429 Too Many Requests`	`rate_limited`	You’ve exceeded the API rate limit	Implement exponential backoff and retry
`402 Payment Required`	`insufficient_credits`	Your account balance is too low	Top up credits or check your billing plan

Next Steps

Calls Overview

Understand call statuses, directions, and lifecycle

Batch Calls & Campaigns

Call many contacts at once with campaigns

Webhooks Overview

Receive real-time events instead of polling

Call Management

List, filter, and retrieve call records

Getting Started

How Truedy Works

Agents

Calls

Outbound Campaigns

Telephony

Tools

Knowledge

Embed & Web Calls

Webhooks

Platform

Prerequisites

Placing a Call

Endpoint

Request Body

About `variables`

Examples

Response

Monitoring Call Progress

Option 1: Polling

Option 2: Webhooks (Recommended)

Phone Number Format

Common Errors

Next Steps

Calls Overview

Batch Calls & Campaigns

Webhooks Overview

Call Management

​Prerequisites

​Placing a Call

​Endpoint

​Request Body

​About variables

​Examples

​Response

​Monitoring Call Progress

​Option 1: Polling

​Option 2: Webhooks (Recommended)

​Phone Number Format

​Common Errors

​Next Steps

Calls Overview

Batch Calls & Campaigns

Webhooks Overview

Call Management

Prerequisites

Placing a Call

Endpoint

Request Body

About `variables`

Examples

Response

Monitoring Call Progress

Option 1: Polling

Option 2: Webhooks (Recommended)

Phone Number Format

Common Errors

Next Steps