> ## 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.
# Setting Up Inbound Calls
> Route incoming calls to your agents automatically
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:
Truedy's telephony infrastructure receives the inbound call on your number.
Truedy looks up which agent is configured for that phone number.
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.
The call is transcribed and recorded in real time. A call object is created with `direction: "inbound"`.
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
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](/guides/buying-phone-numbers) for a step-by-step walkthrough.
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"`:
```bash curl theme={null}
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"
}'
```
```python Python theme={null}
import requests
requests.post(
"https://api.truedy.ai/api/public/v1/telephony/numbers/assign",
headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
json={
"number_id": number_id,
"agent_id": agent_id,
"assignment_type": "inbound",
},
).raise_for_status()
print("Number assigned for inbound.")
```
```typescript TypeScript theme={null}
await fetch('https://api.truedy.ai/api/public/v1/telephony/numbers/assign', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.TRUEDY_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
number_id: numberId,
agent_id: agentId,
assignment_type: '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](#inbound-prompt-best-practices) section below.
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.
```
Assign different phone numbers to different agent configurations. For example:
* `+18001112222` → "Support" agent (focused on troubleshooting)
* `+18001113333` → "Sales" agent (focused on pricing and demos)
* `+18001114444` → "Billing" agent (focused on account and invoices)
Callers dial the number relevant to their need, and the agent is already primed for that context.
If you need to inject caller-specific data (e.g. their CRM record), use the `call.started` webhook event. When Truedy fires the event, your server receives the `from_number` (the caller's phone number). You can look up the contact in your CRM by phone number and then use Truedy's update API to push context into the live call.
This is an advanced pattern suited for teams with real-time backend infrastructure.
***
## 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.
| Event | When it fires |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| `call.started` | The caller has been connected and the agent begins speaking. Includes the `from_number` of the caller. |
| `call.ended` | The call has completed. Includes the full call object with duration and outcome. |
| `call.analyzed` | Post-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](/guides/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
Understand call statuses, directions, and lifecycle
Receive real-time events for call activity
Learn how to write effective agent prompts
Retrieve and filter your inbound call history