Skip to main content
A call in Truedy represents a single conversation between one of your AI agents and a person. Every time your agent speaks with someone — whether you initiated the call, someone called in, or they connected through a browser widget — Truedy creates a call object that records everything: the transcript, the recording, timing metadata, and the final outcome. This guide explains the call data model, the lifecycle a call moves through, and how to retrieve call data via the API.

​
Call Directions

Truedy supports three call directions, each representing a different way a conversation is initiated.

Outbound

Your agent places a call to a contact’s phone number. Used for proactive outreach, follow-ups, appointment reminders, and campaigns.

Inbound

A contact dials one of your Truedy phone numbers and the call is routed to the configured agent. Used for support lines, hotlines, and always-on reception.

WebRTC

A contact connects through a browser-based widget embedded on your website or app. No phone number required on either side — audio is transmitted over the internet.

​
The Call Lifecycle

Every call moves through a defined sequence of statuses from creation to completion. Understanding this lifecycle helps you build reliable integrations and interpret webhook payloads correctly. 
queued → ringing → in-progress → ended
                              ↘ failed
1

queued

The call has been created in Truedy’s system and is waiting to be dialled. For outbound calls, this is the initial state after you call POST /calls. The call will transition out of this state within seconds under normal conditions.
2

ringing

Truedy has initiated the connection and is waiting for the recipient to answer. For inbound and WebRTC calls, this state is brief or may be skipped entirely.
3

in-progress

The call has been answered and the agent is actively speaking with the contact. Transcription and recording begin at this point.
4

ended

The call completed normally. The transcript, recording URL, duration, and outcome are now available on the call object.
5

failed

The call could not be connected or was interrupted before completion. Check the failure_reason field for details (e.g. no-answer, busy, invalid-number, agent-error).
WebRTC calls skip the ringing state entirely and move directly from queued to in-progress once the browser widget establishes the connection.

​
Call Status Reference

StatusMeaningTerminal?
queuedCall created, waiting to be dialledNo
ringingDialling the recipient, awaiting answerNo
in-progressActive conversation underwayNo
endedCall completed successfullyYes
failedCall could not connect or was interruptedYes
cancelledCall was cancelled before it could be dialledYes
Only ended, failed, and cancelled are terminal statuses. Once a call reaches one of these states, it will never transition again. Use this to know when it is safe to process a call’s transcript or recording.

​
The Call Object

When you retrieve a call from the API, you receive a call object with the following fields:
FieldTypeDescription
idstringUnique identifier for the call (UUID)
statusstringCurrent call status (see table above)
directionstringoutbound, inbound, or webrtc
agent_idstringThe agent that handled this call
phone_numberstringThe E.164 phone number dialled or that called in. null for WebRTC calls
from_numberstringThe Truedy number the call was placed from (outbound) or received on (inbound)
duration_secondsintegerTotal call duration from answer to hangup. null if the call never connected
transcriptarrayOrdered array of {speaker, text, timestamp} objects. Available after the call ends
recording_urlstringSigned URL to the call recording audio file. Time-limited — download promptly
cost_centsintegerThe cost of this call in USD cents
outcomestringPost-call analysis outcome label (e.g. interested, not-interested, voicemail)
variablesobjectTemplate variables that were passed when the call was created
failure_reasonstringMachine-readable reason the call failed. Present only when status is failed
started_atstringISO 8601 timestamp when the call moved to in-progress
ended_atstringISO 8601 timestamp when the call reached a terminal status
created_atstringISO 8601 timestamp when the call object was created

​
Example: A Completed Call Object

{
  "id": "call_01hx3k9p2qw7v8n4m6j5r0y1tz",
  "status": "ended",
  "direction": "outbound",
  "agent_id": "agent_01hx2a7b3cd4ef5gh6ij7kl8mn",
  "phone_number": "+14155551234",
  "from_number": "+18005559876",
  "duration_seconds": 183,
  "cost_cents": 92,
  "outcome": "interested",
  "variables": {
    "first_name": "Sarah",
    "appointment_date": "April 10th"
  },
  "transcript": [
    {
      "speaker": "agent",
      "text": "Hi Sarah, this is Aria calling from Bright Dental. I'm reaching out about your appointment on April 10th.",
      "timestamp": 1.2
    },
    {
      "speaker": "contact",
      "text": "Oh hi, yes I remember. Is everything still on?",
      "timestamp": 7.4
    },
    {
      "speaker": "agent",
      "text": "Absolutely, everything is confirmed for 2pm. Just wanted to make sure you didn't have any questions.",
      "timestamp": 11.9
    }
  ],
  "recording_url": "https://recordings.truedy.ai/call_01hx3k9p2qw7v8n4m6j5r0y1tz.mp3?token=eyJ...&expires=1712620800",
  "failure_reason": null,
  "started_at": "2024-04-05T14:22:01Z",
  "ended_at": "2024-04-05T14:25:04Z",
  "created_at": "2024-04-05T14:21:58Z"
}

​
Retrieving a Call

Use GET /calls/{id} to fetch the current state of any call by its ID. 
curl https://api.truedy.ai/api/public/v1/calls/call_01hx3k9p2qw7v8n4m6j5r0y1tz \
  -H "Authorization: Bearer YOUR_API_KEY"
The response is a single call object as shown in the example above.

​
Polling vs. Webhooks

After creating a call, you have two options for tracking when it completes: Polling — repeatedly call GET /calls/{id} until the status reaches a terminal state. Simple to implement but inefficient at scale. Webhooks — register a webhook endpoint and Truedy will push a call.ended or call.analyzed event to your server the moment the call finishes. This is the recommended approach for production integrations.
For any integration that processes more than a handful of calls per day, webhooks are strongly preferred over polling. See the Webhooks Overview guide for setup instructions.

​
Next Steps

Making Outbound Calls

Place individual outbound calls via the API

Setting Up Inbound Calls

Route incoming callers to your agents

WebRTC Widget

Embed a browser-based voice widget

Call Management

List, filter, and export call records