Vonage
Set up Vonage as your telephony provider for outbound and inbound voice calls with zoxaAI.
What you'll learn
How to configure Vonage as a telephony provider in zoxaAI, including creating a Vonage Application, finding your four required credentials, and configuring inbound webhooks.
Vonage
Vonage (formerly Nexmo) provides cloud communications APIs including programmable voice. zoxaAI integrates with Vonage for both outbound and inbound calling using the Voice API and NCCO (Nexmo Call Control Objects).
Provider Details
| Feature | Value |
|---|---|
| Provider name | vonage |
| Audio format | L16 PCM |
| Sample rate | 16,000 Hz |
| Call transfer | No |
| Auto-create application | No |
| Webhook signature verification | Yes (JWT) |
| Account ID field | api_key |
Higher audio quality
Vonage streams audio at 16 kHz (L16 PCM), which is double the sample rate of most other providers (8 kHz mulaw). This can result in higher-fidelity voice quality for both speech-to-text and text-to-speech processing.
Prerequisites
- A Vonage API account (sign up at dashboard.nexmo.com)
- A Vonage Application created in the dashboard with Voice capability enabled
- At least one Vonage phone number
Credentials
You need four values from your Vonage Dashboard:
| Field | Where to Find It | Sensitive | Required | Description |
|---|---|---|---|---|
| API Key | Vonage Dashboard > API Settings | Yes | Yes | Your account API key |
| API Secret | Vonage Dashboard > API Settings | Yes | Yes | Your account API secret |
| Application ID | Vonage Dashboard > Applications > your app | No | Yes | The UUID of your Vonage Application |
| Private Key | Downloaded when creating the application | Yes | Yes | RSA private key content for JWT authentication |
Setup
Create a Vonage Application (if you do not have one)
- Go to Applications in the Vonage Dashboard.
- Click Create a new application.
- Enable Voice capability.
- Set the Answer URL to:
https://your-domain.com/api/v1/telephony/run - Set the HTTP Method to POST.
- Click Generate new application.
- Download the private key file -- you will need its contents for the zoxaAI configuration.
Open the Telephony Page
Navigate to Telephony in the zoxaAI sidebar.
Add a New Configuration
Click Add Configuration. Select Vonage from the provider dropdown.
Enter Your Credentials
Fill in all four fields:
- API Key and API Secret from Dashboard > API Settings.
- Application ID from your Vonage Application.
- Private Key -- paste the entire contents of the private key file (including
-----BEGIN PRIVATE KEY-----and-----END PRIVATE KEY-----lines).
Name and Save
Give the configuration a name (e.g., "Vonage Production") and click Save.
Add Phone Numbers
Right after you save, zoxaAI opens the new configuration and fetches the voice numbers on your Vonage account. Click Add next to the ones you want, or Add all. You can fetch again any time with Fetch from Vonage in the Phone Numbers section.
To add a number by hand instead, click Add phone number and enter it in E.164 format:
+14155552671Fetching uses your API Key and API Secret (Vonage's Numbers API does not accept the application key). Only numbers with the voice feature are listed. A number linked to a different Vonage application shows an info icon: inbound calls reach zoxaAI only after you link it to this configuration's application.
Phone number format
Enter numbers with or without the + prefix (+14155552671 or 14155552671); zoxaAI strips the + when it calls the Vonage API. Fetch from Vonage adds them with the +.
Outbound Calls
Vonage outbound calls use the Voice API with NCCO (Nexmo Call Control Objects) for call control. Audio is streamed over WebSocket in audio/l16;rate=16000 format -- linear 16-bit PCM at 16 kHz.
| Source | Description |
|---|---|
| Test calls | Place a test call from the agent editor |
| API calls | Use POST /api/v1/call with your API key |
| Campaigns | Bulk outbound dialing across a contact list |
Inbound Calls
Vonage fully supports inbound calling via the Voice API. Configure your Vonage Application's Answer URL to point to zoxaAI.
Open Vonage Dashboard
Go to the Vonage Dashboard and navigate to Applications > your application.
Set Answer URL
Under Voice, set:
- Answer URL:
https://your-domain.com/api/v1/telephony/run - HTTP Method: POST
Assign an Agent
In the zoxaAI dashboard, go to Telephony > your Vonage configuration and open the phone number (or add it). Select the agent that should answer in the Inbound target dropdown and save.
See Inbound Calling for the full inbound routing guide.
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| "Private key" validation error | Key not pasted in full | Paste the entire key file content including the BEGIN/END header lines |
| Inbound calls not routing | Answer URL not set on the Vonage Application | Set the Answer URL as described above |
| Phone numbers not matching | Numbers include + prefix | Remove the + prefix from all Vonage phone numbers |
| Outbound calls fail | Application ID or Private Key mismatch | Verify the Application ID matches the application whose private key you downloaded |