Vonage Integration

​

Overview

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

​

Prerequisites

Before setting up Vonage integration, you’ll need:

• A Vonage account
• Vonage Application with Voice capability enabled
• Application ID and Private Key from your Vonage Dashboard
• API Key and API Secret from your Vonage Dashboard
• Signature Secret from your Vonage Dashboard
• At least one Vonage phone number linked to the application
• Ambivert AI AI instance running and accessible

​

Configuration

​

Step 1: Create Vonage Application

1. Log in to your Vonage Dashboard
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. Copy your Signature Secret from the same Vonage account. Ambivert AI uses it to verify Vonage signed webhooks.
3. Navigate to Numbers → Your Numbers
4. Copy your phone number(s)
5. Link each inbound number to your Voice application

​

Step 3: Configure in Ambivert AI AI

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
   • Signature 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 routes inbound Voice API calls through a Voice application. The application owns the Answer URL and Event URL, and the phone number must be linked to that application. Ambivert AI routes the call to the right agent based on the called number’s inbound workflow assignment inside Ambivert AI. When you save an inbound workflow on a phone number, Ambivert AI updates the configured Vonage application’s Voice webhooks and enables signed callbacks, provided the API Key, API Secret, and Application ID are correct and a Signature Secret is configured.

​

Step 1: Link Phone Numbers to Your Vonage Application

1. Open the Vonage Dashboard
2. Go to Numbers → Your Numbers
3. Open each number you want to use for inbound calls
4. Set the number’s Voice application to the same Vonage Application whose ID you configured in Ambivert AI

Vonage’s Numbers API describes this as the number’s app_id: the application that handles inbound traffic to that number. See the Numbers API reference.

​

Step 2: Assign an Inbound Workflow to the Phone Number in Ambivert AI

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
2. Under Capabilities → Voice, confirm:
   • Answer URL is set to: https://<your-backend-domain>/api/v1/telephony/inbound/run
   • HTTP Method is POST
   • Event URL is set to: https://<your-backend-domain>/api/v1/telephony/vonage/events
   • Event Method is POST
   • Signed callbacks are enabled
   Ambivert AI pushes these settings automatically when you save the inbound workflow in Step 2. If the fields are empty, show a different URL, or Ambivert AI surfaced a sync warning on save, check the API Key, API Secret, Application ID, and Signature Secret in Ambivert AI, then save the inbound workflow again. On self-hosted Ambivert AI, the backend domain must be publicly reachable by Vonage.

​

Step 4: Verify Setup

• Ensure your Ambivert AI AI instance is publicly accessible
• Verify your public backend URL is reachable from the internet
• Use the Vonage logs or Voice Inspector to confirm Vonage is sending the Answer webhook to Ambivert AI

​

Test Inbound Calling

1. Call your configured Vonage phone number from another phone
2. Verify your Ambivert AI AI voice agent answers and responds
3. Check call logs in both Ambivert AI AI 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

​

Troubleshooting

​

Best Practices

• Security: Private keys are stored securely in the database
• Signed callbacks: Keep Vonage signed callbacks enabled and keep the Signature Secret in Ambivert AI up to date
• 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 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