Inbound Calling

Inbound calling lets your zoxaAI agents answer phone calls automatically. When someone calls one of your configured phone numbers, zoxaAI detects the provider, matches the number, verifies the webhook signature, and starts the assigned agent.

How Inbound Calls Work

Universal Inbound Endpoint

All providers use the same inbound endpoint:

https://your-domain.com/api/v1/telephony/run

This is a unified dispatcher — it auto-detects the provider from the webhook payload and routes the call accordingly. You do not need provider-specific webhook URLs.

When you create an inbound binding via POST /api/v1/call with type: "inbound", the platform installs this URL on the provider's side automatically — no manual dashboard step needed. The manual dashboard steps below are for when you configure the webhook directly on the provider instead.

Configuring Webhooks by Provider

Each provider has a different place in their dashboard to set the webhook URL. Below is a summary for each provider.

Twilio

Vonage

Plivo

Telnyx

Cloudonix

Vobiz

Asterisk ARI

ARI delivers call events over a persistent ARI WebSocket connection instead of an HTTP webhook. Asterisk ARI calls are not connected to agents -- see Asterisk ARI for details.

Tata Smartflo

Smartflo handles inbound calls over a static Voice Bot WebSocket — there is no HTTP webhook.

1. In the Tata portal, add a Voice Streaming endpoint (type Static) pointing at your Voice Bot URL:

   wss://your-domain.com/api/v1/telephony/smartflo/ws?token=<config-token>

2. Point your Smartflo DID at that endpoint. Incoming calls stream to zoxaAI, which resolves the agent assigned to the number.

See Tata Smartflo for full setup details.

Automatic Application Creation

For Plivo, Telnyx, Cloudonix, and Vobiz, when you leave the Application ID / Connection ID / Application Name blank during setup, zoxaAI automatically creates the application on the provider's side with the correct inbound webhook URL pre-configured.

This is the recommended approach for most users -- it eliminates the need for manual webhook configuration.

Number-to-Agent Routing

When an inbound call arrives, zoxaAI matches the called number against all phone numbers registered across your telephony configurations. For the call to route successfully, the number must be:

1. Registered in a telephony configuration in your organization.
2. Active (not disabled or deleted).
3. Assigned to an agent.

Assigning a Number to an Agent

Fallback Behavior

If a call arrives but routing fails, zoxaAI returns a provider-appropriate error response:

Context Variables

Every inbound call automatically receives these built-in context variables, accessible anywhere in your agent's configuration (including the system prompt) using {{variable_name}} syntax:

Built-in variables always take precedence over values with the same name in the agent's saved context variable defaults. See Variable substitution for the full rules.

Using Context Variables in Prompts

You can reference these variables in your agent's system prompt:

You are a customer service agent for Acme Corp.
The caller's phone number is {{user_number}}.
Today is {{current_day}}, {{current_date}}.

Cross-Organization Isolation

Inbound routing is strictly scoped to your organization. Even if two organizations use the same telephony provider and have the same account credentials, inbound calls are matched using the organization-specific configuration's account ID field. There is no cross-organization data leakage.

Troubleshooting