Inbound Calls

Voice agents can be configured to receive inbound calls. When a contact calls one of your phone numbers, the system routes the call to the appropriate playbook and handles it with the AI agent.

Enabling Inbound Calls

On the voice agent configuration page:

1. Toggle Enable Inbound Calls
2. Add one or more Inbound Playbooks — these are the playbooks that inbound calls will be routed to

Playbook Priority

Inbound playbooks are ordered by priority:

• Index 0 is the primary playbook (used as the default for unknown callers)
• The system searches playbooks in order to find a matching contact
• If the caller's phone number matches a contact in a lower-priority playbook, that playbook is used

Inbound Call Flow

1. A call comes in to the agent's phone number
2. The system identifies the agent by the phone number
3. The caller's phone number is matched against contacts in the inbound playbooks (in priority order)
4. If a match is found, the call is associated with that contact and playbook
5. If no match is found, a new contact may be created in the primary playbook
6. The voice prompt template is rendered with the contact data and call_direction: inbound
7. The AI agent handles the conversation
8. Post-call processing runs as normal (webhook, status update, post-call pipeline)

Prompt Conditionals

Voice prompt templates can use the call_direction variable to customize behavior for inbound vs. outbound calls:

• call_direction = inbound — The contact called you
• call_direction = outbound — You called the contact

This lets you create different greetings and conversation flows. For example, an inbound call might skip the introduction and go straight to asking how you can help.

Contact Type

The contact_type variable is also set during inbound calls:

• new — Brand new contact, no prior contact
• first — First contact in this playbook
• returning — Contact has been contacted before

Combined with call_direction, you can create highly specific prompt conditionals (e.g., a returning contact calling back gets a different experience than a new inbound caller).