Telephony

Telephony providers connect your zoxaAI agents to real phone numbers. Once configured, you can place outbound calls, receive inbound calls, and run campaigns at scale -- all through the same unified platform.

---

Supported Providers

zoxaAI supports eight telephony providers. All providers support both inbound and outbound calling.

---

How It Works

The telephony system has three layers:

1. Configurations -- your provider credentials (API keys, tokens, etc.).
2. Phone numbers -- the numbers registered under each configuration, used for caller ID and inbound routing.
3. Default outbound -- one configuration is marked as the default for outbound calls.

When a call is placed, zoxaAI resolves the telephony provider from the configuration, initiates the call through the provider's API, and streams audio over WebSocket between the provider and the voice pipeline.

---

Adding a Provider

---

Managing Phone Numbers

After creating a configuration, navigate into it to manage phone numbers. Phone numbers serve two purposes:

• Outbound caller ID -- the number your contacts see when you call them. The provider selects one at random for each call, or you can specify one explicitly.
• Inbound routing -- matching incoming calls to the right agent.

Adding Phone Numbers

Right after you create a configuration, zoxaAI opens it and fetches the voice numbers on your provider account, so you can click Add next to each one or Add all. You can fetch again any time with Fetch from <provider> in the Phone Numbers section. This works for every provider except Asterisk ARI, which has no API that lists its numbers.

To add a number by hand:

1. Click into a telephony configuration.
2. Click Add phone number.
3. Enter the number in E.164 format (e.g., +14155552671, +919876543210).

Assigning Inbound Routing

Each phone number can be assigned to an agent for inbound call routing:

1. Open the phone number in the configuration (or add a new one).
2. Select an agent in the Inbound target dropdown.
3. Save the phone number.

When an inbound call arrives on that number, zoxaAI automatically routes it to the assigned agent. For Twilio, Vobiz, and Tata Smartflo numbers you can also bind a number to an agent through the API -- see Register an inbound phone number.

---

Multiple Configurations

You can add multiple configurations, even from the same provider. Common patterns:

• Geographic separation -- different providers for US, India, and EU traffic.
• Production vs. testing -- separate credentials for development and production.
• Provider failover -- a backup provider if your primary is down.
• Different number pools -- separate configurations for sales and support numbers.

---

Default Outbound Configuration

One configuration is marked as the default outbound configuration. This is used when:

• An API call does not specify a telephony configuration ID.
• A test call is placed from the dashboard without selecting a specific config.

To change the default:

1. Go to the Telephony page.
2. Click the star icon next to the configuration you want as the default.

---

Configuration Cards

Each configuration appears as a card on the Telephony page showing:

You can:

• Edit a configuration to update credentials or name.
• Delete a configuration (only if no campaigns or active inbound assignments reference it).
• Set as default to use it for outbound calls.

---

How Telephony Connects to Agents

Telephony configurations are used at multiple points in the platform:

---

Webhook Signature Verification

For inbound calls, zoxaAI verifies webhook signatures from each provider to ensure requests are genuine. This happens automatically using the credentials stored in your configuration -- no additional setup is needed.

---

Next Steps