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

# Vonage

> Configure Vonage (Nexmo) for voice communication in SentiVue Talk

## Overview

Vonage (formerly Nexmo) is a cloud communications platform that provides global voice, messaging, and video capabilities. SentiVue Talk's Vonage integration enables high-quality voice interactions with your workflows using Vonage's robust infrastructure.

## Prerequisites

Before setting up Vonage integration, you'll need:

* A [Vonage account](https://www.vonage.com/communications-apis/)
* 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 Vonage Application

1. Log in to your [Vonage Dashboard](https://dashboard.nexmo.com/)
2. Navigate to **Applications** → **Create a new application**
3. Enable **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** in the dashboard under **API Settings**
2. Navigate to **Numbers** → **Your Numbers**
3. Copy your phone number(s)
4. Link your numbers to your application

### Step 3: Configure in SentiVue Talk

1. Navigate to **/telephony-configurations** and click **Add configuration**
2. Select **Vonage** as your provider
3. Enter your credentials:
   * Application ID
   * Private Key (entire key including BEGIN/END lines)
   * API Key
   * API Secret
4. Click **Save Configuration**
5. Open the configuration you just created and add at least one **phone number** (without `+` prefix, e.g. `14155551234`). The default caller ID is used for outbound calls.

### Step 4: Test Your Configuration

1. Create a test workflow
2. Click "Call" to verify connection
3. Check call logs for successful connection

## Inbound Calling Setup

Vonage configures inbound webhooks at the **application level**, not per phone number. A single **Answer URL** on the Vonage application applies to every number linked to it. SentiVue Talk routes the call to the right agent based on the called number's inbound workflow assignment inside SentiVue Talk. **When you save an inbound workflow on a phone number, SentiVue Talk automatically pushes the webhook URL to your Vonage Application's Answer URL** (provided the credentials are correct).

### 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 to use for inbound to the same Vonage Application whose ID you configured in SentiVue Talk

### Step 2: Assign an Inbound Workflow to the Phone Number in SentiVue Talk

1. Go to **/telephony-configurations** 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 the Answer URL on the Vonage Application

1. Open your Vonage Application in the [Vonage Dashboard](https://dashboard.nexmo.com/)
2. Under **Capabilities** → **Voice**, confirm:

   * **Answer URL** is set to: `https://app.sentivue.com/talk/api/v1/telephony/inbound/run`
   * **HTTP Method** is `POST`

   SentiVue Talk sets this automatically when you save the inbound workflow.

   If the field is empty or shows something else, the auto-push failed — usually a wrong API Key/Secret or Application ID. Paste the URL in yourself, set the method to `POST`, and save the application.

### Step 4: Verify Setup

* Confirm the number is listed in your SentiVue Talk telephony configuration and has an **Inbound workflow** assigned
* Confirm the number is linked to the same Vonage Application whose ID is configured in SentiVue Talk

### Test Inbound Calling

1. Call your configured Vonage phone number from another phone
2. Verify your SentiVue Talk workflow answers and responds
3. Check call logs in both SentiVue Talk dashboard and Vonage Dashboard

## Audio Quality Optimization

Vonage uses higher quality audio (16kHz) which provides:

* Clearer voice reproduction
* Better speech recognition accuracy
* More natural-sounding TTS output
* Reduced transcription errors

## Call handling setup

Vonage numbers use the **Standard** setup: calls reach your agent through Vonage's voice webhook. This supports inbound calls, outbound calls, and cold transfer.

Warm transfer and live translation need the **Advanced** setup, which is currently available on Twilio only. Support for Vonage is in progress.

## 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 (use `14155551234` not `+14155551234`)
    * Ensure numbers are in E.164 format without the '+'
    * Verify numbers are active in your Vonage account
  </Accordion>

  <Accordion title="No audio on calls">
    * Confirm the number is linked to the same Vonage application whose ID is configured in SentiVue Talk
    * Check the Vonage Dashboard logs for the call for streaming errors
    * Review the call logs in the SentiVue Talk dashboard
  </Accordion>

  <Accordion title="Calls disconnecting early">
    * Check the Vonage Dashboard logs for the call's termination reason
    * Review the call logs in the SentiVue Talk dashboard for errors
  </Accordion>

  <Accordion title="Inbound calls not reaching workflow">
    * Verify the Vonage application's Answer URL is exactly `https://app.sentivue.com/talk/api/v1/telephony/inbound/run` and the method is `POST`
    * Confirm the called number is linked to the same Vonage application whose ID is configured in SentiVue Talk
    * Confirm the called number exists in your SentiVue Talk telephony configuration and has an **Inbound workflow** assigned
    * Check the Vonage Dashboard logs for the Answer URL request and its response
  </Accordion>

  <Accordion title="Voice agent doesn't respond to inbound calls">
    * Confirm the phone number has an **Inbound workflow** assigned in /telephony-configurations
    * Verify API Key matches the one stored in your SentiVue Talk telephony configuration (used to identify the org from the inbound webhook)
    * Review call logs for error messages
  </Accordion>
</AccordionGroup>

## Best Practices

* **Security**: Rotate your application's private key in the Vonage Dashboard if you suspect it has been exposed, then update it here
* **Testing**: Use Vonage Voice Inspector for debugging call issues
* **Numbers**: Configure multiple numbers for redundancy
* **Monitoring**: Set up alerts in Vonage Dashboard for failures
* **Cost Management**: Monitor usage to control costs

## Cost Considerations

Vonage pricing includes:

* Per-minute charges for calls
* Phone number rental fees
* Optional features (recording, transcription)

Check [Vonage pricing](https://www.vonage.com/communications-apis/voice/pricing/) for current rates.

## Next Steps

* Test your Vonage integration with a simple workflow
* Configure VAD settings for optimal voice detection
* Set up monitoring and alerts
* Explore advanced features like call recording