> ## Documentation Index
> Fetch the complete documentation index at: https://docs.voicerix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vonage

> Connect Vonage to Voicerix for outbound and inbound voice calls.

## Overview

Vonage (formerly Nexmo) is a cloud communications platform with global voice capabilities. Voicerix uses Vonage's application-level voice API with high-quality 16kHz audio for clear, natural conversations.

## Prerequisites

* A [Vonage account](https://www.vonage.com/communications-apis/)
* A Vonage **Application** with Voice capability enabled
* **Application ID** and **Private Key** from your Vonage Dashboard
* **API Key** and **API Secret** from your Vonage Dashboard
* At least one Vonage phone number linked to the application

## Configuration

### Step 1: Create a Vonage Application

1. Log in to your [Vonage Dashboard](https://dashboard.nexmo.com/)
2. Navigate to **Applications** → **Create a new application**
3. Enable the **Voice** capability
4. Generate a private key (save this securely — you'll need it)
5. Note your **Application ID**

### Step 2: Get API Credentials

1. Find your **API Key** and **API Secret** under **API Settings** in the dashboard
2. Navigate to **Numbers** → **Your Numbers** and link your phone numbers to the application

### Step 3: Add Configuration in Voicerix

1. In Voicerix, go to **Integrations** and click **Add configuration**
2. Select **Vonage** as your provider
3. Enter your credentials:
   * **Application ID**
   * **Private Key** (include the full key with BEGIN/END lines)
   * **API Key**
   * **API Secret**
4. Click **Save Configuration**
5. Open the saved configuration and add at least one **phone number** without the `+` prefix (e.g. `14155551234`)

### Step 4: Test

1. Go to **Agents**, open a workflow, and click **Test Call**
2. Check the call logs to confirm a successful connection

***

## Inbound Calling Setup

Vonage configures inbound webhooks at the **application level** — a single Answer URL on the Vonage application applies to every number linked to it. When you save an inbound workflow on a phone number in Voicerix, **Voicerix automatically pushes the webhook URL to your Vonage Application's Answer URL**.

### Step 1: Link Phone Numbers to Your Vonage Application

1. Open the [Vonage Dashboard](https://dashboard.nexmo.com/)
2. Under **Numbers** → **Your Numbers**, link each number you want for inbound to the same Vonage Application whose ID you configured in Voicerix

### Step 2: Assign an Inbound Workflow in Voicerix

1. In Voicerix, go to **Integrations** and open your Vonage configuration
2. In the **Phone numbers** section, edit the number that should receive inbound calls
3. Set its **Inbound workflow** to the agent that should answer
4. Save

### Step 3: Verify in Vonage Dashboard

1. Open your Vonage Application in the [Vonage Dashboard](https://dashboard.nexmo.com/)
2. Under **Capabilities** → **Voice**, confirm:
   * **Answer URL** is set to: `https://client.voicerix.ai/api/v1/telephony/inbound/run`
   * **HTTP Method** is `POST`

<Note>
  Voicerix pushes this URL automatically when you save the inbound workflow. If the field is empty or shows a different URL, the auto-push failed — usually because the API Key/Secret or Application ID is incorrect. Paste the URL manually, set the method to `POST`, and save the application.
</Note>

### Step 4: Test Inbound

1. Call your Vonage number from another phone
2. Verify your voice agent answers and responds
3. Check call logs in both Voicerix and the Vonage Dashboard

***

## Audio Quality

Vonage uses 16kHz audio, which gives:

* Clearer voice reproduction
* Better speech recognition accuracy
* More natural TTS output
* Fewer transcription errors

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Voice application capabilities error">
    * Ensure **Voice** is enabled in your Vonage application
    * Verify the Application ID matches your configuration
    * Check that your phone numbers are linked to the application
  </Accordion>

  <Accordion title="JWT authentication failed">
    * Verify your private key is complete (including BEGIN/END lines)
    * Check the Application ID is correct
    * Ensure the private key hasn't been regenerated in Vonage Dashboard
  </Accordion>

  <Accordion title="Invalid phone number error">
    Remove the `+` prefix for Vonage numbers (use `14155551234`, not `+14155551234`)
  </Accordion>

  <Accordion title="No audio on calls">
    * Verify the WebSocket connection is established
    * Check the audio pipeline is configured for 16kHz PCM
    * Monitor WebSocket for binary audio frames
  </Accordion>

  <Accordion title="Calls disconnecting early">
    * Check WebSocket heartbeat/ping-pong frames
    * Verify no timeout in load balancer or proxy
    * Monitor for audio pipeline errors
  </Accordion>

  <Accordion title="Inbound calls not reaching voice agent">
    * Verify the Vonage application's Answer URL is set to `https://client.voicerix.ai/api/v1/telephony/inbound/run`
    * Ensure the Answer URL is publicly accessible
    * Confirm the called number is linked to the correct Vonage application
    * Confirm the called number has an **Inbound workflow** assigned in Voicerix
  </Accordion>

  <Accordion title="Voice agent doesn't respond to inbound calls">
    * Confirm the phone number has an **Inbound workflow** assigned in Integrations
    * Verify the API Key matches the one stored in your Voicerix configuration
    * Verify WebSocket connection establishes successfully
    * Review call logs for error messages
  </Accordion>
</AccordionGroup>

## Best Practices

* Keep your private key secure — it is stored encrypted in Voicerix
* Test your configuration with a single call before running campaigns
* Monitor the Vonage Dashboard for usage and billing