Skip to main content
Inbound calling lets your agents handle calls that people place to you — a support line, a booking hotline, an after-hours reception desk. Once configured, any call to your Truedy number is answered instantly by your AI agent with no human required.

​
How Inbound Calling Works

When someone dials a Truedy phone number assigned to your account, the following happens automatically:
1

Call arrives at Truedy

Truedy’s telephony infrastructure receives the inbound call on your number.
2

Agent lookup

Truedy looks up which agent is configured for that phone number.
3

Agent answers

The agent answers the call and delivers its opening greeting. The conversation begins immediately — there is no hold music or menu system unless you build one into the agent’s prompt.
4

Conversation recorded

The call is transcribed and recorded in real time. A call object is created with direction: "inbound".
5

Post-call processing

Once the caller hangs up, Truedy runs post-call analysis (outcome labelling, summary generation) and fires webhook events to any configured endpoints.

​
Setup: Step by Step

1

Obtain a phone number

You need a Truedy phone number to receive inbound calls. You can purchase a new number directly in the dashboard under Settings → Phone Numbers, or import an existing number by porting it to Truedy.Numbers are available in the US, Canada, UK, and a growing list of countries. Choose a number in the same country as your callers to avoid international charges on their end.See Buying Phone Numbers for a step-by-step walkthrough.
2

Assign the number to an agent

Navigate to Settings → Phone Numbers in the dashboard. Find the number you want to use for inbound, click the assignment dropdown, and select the agent that should handle calls on this number.Each phone number can be assigned to exactly one agent. A single agent can be assigned to multiple numbers (e.g. a toll-free number and a local number that both route to the same agent).You can also manage this via the API — use POST /telephony/numbers/assign with assignment_type: "inbound":
curl -X POST https://api.truedy.ai/api/public/v1/telephony/numbers/assign \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "number_id": "YOUR_NUMBER_UUID",
    "agent_id": "YOUR_AGENT_UUID",
    "assignment_type": "inbound"
  }'
3

Configure your agent for inbound

Your agent’s prompt should be written with inbound context in mind. Unlike outbound calls where your agent speaks first with a specific goal, inbound callers may arrive for a variety of reasons and have their own agenda.See the Inbound Prompt Best Practices section below.
4

Test the setup

Call your Truedy number from a real phone. Your agent should answer within a couple of seconds. Verify:
  • The greeting sounds natural for your use case
  • The agent handles common caller questions correctly
  • The call appears in your dashboard under Calls with direction: inbound

​
Inbound Prompt Best Practices

Writing a great inbound prompt is slightly different from outbound. Keep these principles in mind.

​
Establish context in the system prompt

Your agent does not know why someone is calling when the call begins. Set the scene clearly: 
You are an AI receptionist for Bright Dental Clinic.
You are receiving inbound calls from patients and prospective patients.
Common reasons people call include: booking appointments, asking about services and pricing,
getting directions, and questions about their dental health.

Always greet callers warmly and ask how you can help them today.

​
Use a natural greeting

Inbound callers expect to be greeted immediately. Your opening line should orient the caller quickly: 
Opening: "Thank you for calling Bright Dental. I'm Aria, your virtual assistant. How can I help you today?"
Avoid lengthy company intros — callers become impatient. Get to the point within one sentence.

​
Handle unknown intent gracefully

Unlike outbound calls where the agent drives toward a specific goal, inbound agents must be flexible. Include guidance for handling unexpected questions: 
If a caller asks about something you don't have information on, acknowledge their question,
let them know you can note their query, and offer to have a human team member follow up.
Do not make up information or speculate.

​
Collect identifying information early

If your workflow requires knowing who is calling, ask early in the conversation: 
Before assisting with account-specific queries, ask for the caller's name and
the phone number or email address on their account to verify their identity.
Unlike outbound calls, you cannot inject variables into an inbound call at the moment it arrives — you don’t know who is calling until they tell you. Design your prompt so the agent collects any necessary context during the conversation itself.

​
Passing Context to Inbound Calls

Inbound calls are initiated by the caller, so there is no API request at call-start where you can inject variables. However, there are patterns you can use to provide context to the agent:
The most straightforward approach. Design your agent’s prompt to ask the caller for identifying information — name, account number, email address — early in the conversation. The agent can then use that information in subsequent turns.
Start by greeting the caller and asking for their name and the reason for their call.
Use their name throughout the conversation to make the interaction feel personal.

​
Webhook Events for Inbound Calls

Truedy fires the same webhook events for inbound calls as for outbound. Configure your endpoints under Settings → Webhooks in the dashboard.
EventWhen it fires
call.startedThe caller has been connected and the agent begins speaking. Includes the from_number of the caller.
call.endedThe call has completed. Includes the full call object with duration and outcome.
call.analyzedPost-call analysis has finished. Includes transcript, summary, and outcome label.
Use the call.started event to log inbound call activity or trigger CRM lookups in real time. Use call.analyzed when you need the transcript and outcome for downstream automations.
See Webhooks Overview for setup and payload documentation.

​
Concurrency and Capacity

Inbound calls consume from your account’s concurrent call limit just like outbound calls. If your limit is 5 concurrent calls and 5 calls are already active, the 6th inbound call will receive a busy signal.
Make sure your concurrent call limit is appropriate for your expected call volume. For high-traffic inbound lines, contact Truedy support to discuss increased limits.
To estimate the concurrency you need:
  • Determine your expected peak calls per hour
  • Estimate average call duration in minutes
  • Apply Little’s Law: concurrency needed = (calls per hour × avg duration in minutes) / 60
For example: 120 calls/hour × 3 min average ÷ 60 = 6 concurrent calls needed at peak.

​
Caller ID and Privacy

When an inbound call arrives, the phone_number field on the call object contains the caller’s number as reported by the carrier. Note:
  • Callers who have blocked their number will show as anonymous or unknown
  • VoIP callers may show inaccurate or spoofed numbers
  • Numbers are stored in E.164 format
Ensure your handling of caller phone numbers complies with applicable privacy regulations in your jurisdiction (e.g. GDPR in Europe, TCPA in the US).

​
Next Steps

Calls Overview

Understand call statuses, directions, and lifecycle

Webhooks Overview

Receive real-time events for call activity

Prompting Basics

Learn how to write effective agent prompts

Call Management

Retrieve and filter your inbound call history