dograh/docs/integrations/telephony/vonage.mdx

---
title: "Vonage Integration"
description: "Configure Vonage (Nexmo) for voice communication in Dograh AI"
---

## Overview

Vonage (formerly Nexmo) is a cloud communications platform that provides global voice, messaging, and video capabilities. Dograh 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](https://www.vonage.com/communications-apis/)
- Vonage Application with Voice capability enabled
- Application ID and Private Key from your Vonage Dashboard
- At least one Vonage phone number
- Dograh AI instance running and accessible

## Video Tutorial

Watch this step-by-step guide to set up Vonage with Dograh AI:

<iframe
  className="w-full aspect-video rounded-xl"
  src="https://www.tella.tv/video/configuring-telephony-on-dograh-with-vonage-3wvo/embed?b=1&title=1&a=1&loop=0&t=0&muted=0&wt=1"
  title="Dograh Vonage Setup"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

## 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 Dograh AI

1. Navigate to **Workflow** → **Phone Call** → **Configure Telephony**
2. Watch the Vonage setup video tutorial above for detailed guidance
3. Select **Vonage** as your provider
4. Enter your credentials:
   - Application ID
   - Private Key (entire key including BEGIN/END lines)
   - API Key (Optional - for some operations)
   - API Secret (Optional - for webhook verification)
   - From Phone Number (without '+' prefix, e.g., 14155551234)
5. Click **Save Configuration**

### Step 4: Test Your Configuration

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

## Inbound Calling

<Note>
**Coming Soon**: Inbound calling support for Vonage is currently under development and will be available in a future release. For now, Vonage integration supports outbound calling only.
</Note>

Vonage integration currently supports outbound calling. Inbound calling functionality is being developed and will include:

- Webhook configuration for incoming calls
- NCCO response handling
- Event tracking for call lifecycle management
- WebSocket audio streaming for inbound calls

For inbound calling needs, consider using [Twilio](/integrations/telephony/twilio), [Cloudonix](/integrations/telephony/cloudonix), or [Vobiz](/integrations/telephony/vobiz) which have full inbound support.

## 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

<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">
    - Verify WebSocket connection is established
    - Check audio pipeline is configured for 16kHz PCM
    - Monitor WebSocket for binary audio frames
    - Review VAD (Voice Activity Detection) settings
  </Accordion>
  
  <Accordion title="Calls disconnecting early">
    - Check WebSocket heartbeat/ping-pong frames
    - Verify no timeout in load balancer/proxy
    - Monitor for audio pipeline errors
    - Review max call duration settings
  </Accordion>
  
  <Accordion title="Inbound calls not reaching voice agent">
    - Verify Answer URL is correctly configured in Vonage application
    - Ensure Answer URL is publicly accessible and returns valid NCCO
    - Check that phone numbers are linked to the correct application
    - Verify Event URL is configured for call tracking
  </Accordion>
  
  <Accordion title="Voice agent doesn't respond to inbound calls">
    - Confirm NCCO response includes correct WebSocket endpoint
    - Check that organization_id in Event URL matches your setup
    - Verify voice agent workflow is properly configured
    - Review webhook logs for error responses
  </Accordion>
</AccordionGroup>

## Best Practices

- **Security**: Private keys are stored securely in the database
- **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.

## Advanced Configuration

### Custom Headers

Add custom headers to WebSocket connections:

```python
# In your webhook response
"headers": {
    "X-Custom-Header": "value",
    "Authorization": "Bearer token"
}
```

### Call Recording

Enable call recording via NCCO:

```json
{
  "action": "record",
  "eventUrl": ["https://your-domain/recording-webhook"],
  "format": "mp3"
}
```

## API Differences from Twilio

| Feature | Twilio | Vonage |
|---------|---------|---------|
| Audio Format | 8kHz μ-law | 16kHz Linear PCM |
| Control Format | TwiML (XML) | NCCO (JSON) |
| Authentication | Basic Auth | JWT |
| WebSocket Data | Base64 text | Binary frames |
| Phone Format | With '+' | Without '+' |

## 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