# Vonage Integration

> Configure Vonage (Nexmo) for voice communication in Menace Voice

## What you need

- A [Vonage API account](https://www.vonage.com/communications-apis/) with
  credit added.
- One Vonage number with Voice capability.
- A Vonage Application with Voice enabled and the number linked to it.
- The Application ID, downloaded private key, API Key, API Secret, and
  Signature Secret.

## Estimated price

Vonage shows the monthly and setup price in **Buy Numbers** before purchase.
The amount varies by country, number type, and availability, so there is no
safe universal estimate. Usage is billed separately. Check the live result and
[current Vonage Voice pricing](https://www.vonage.com/communications-apis/voice/pricing/).

## Set up Vonage step by step

### 1. Buy a voice-capable number

1. Sign in to the [Vonage API Dashboard](https://dashboard.nexmo.com/).
2. Add credit, then open **Buy Numbers**.
3. Choose a country, select the **Voice** feature, and choose a number type.
4. Review the monthly and setup prices, click **Buy**, and complete any
   country-specific document request.

See Vonage's official [Buy Numbers guide](https://developer.vonage.com/en/dashboard/build/phone-numbers/buy-numbers).

### 2. Create a Voice Application

1. Open **Applications** and click **Create a new application**.
2. Give the Application a recognizable name.
3. Click **Generate public and private key**. Save the downloaded private key;
   Vonage cannot show it to you again.
4. Enable the **Voice** capability and create the Application.
5. Copy its **Application ID**.
6. Link the purchased number to this Application.

Vonage documents these controls in [Applications](https://developer.vonage.com/en/dashboard/build/applications).

### 3. Copy the account credentials

In **API Settings**, copy the **API Key**, **API Secret**, and **Signature
Secret**. The Signature Secret lets Menace Voice verify signed webhooks.

### 4. Connect Vonage in Menace Voice

1. Open **Phone numbers** and click **Add phone number**.
2. Choose **Vonage** and continue.
3. Paste the **Application ID** and the entire private key, including the
   `BEGIN PRIVATE KEY` and `END PRIVATE KEY` lines.
4. Paste the **API Key**, **API Secret**, and **Signature Secret**.
5. Enter the purchased number and choose an inbound agent.
6. Finish setup.

### 5. Test the number

Call the number from another phone and confirm the selected agent answers.
Then place one outbound test call before using the connection in a campaign.

## 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. Menace Voice routes the call to the right agent based on the called number's inbound workflow assignment inside Menace Voice.

When you save an inbound workflow on a phone number, Menace Voice 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.

<Warning>
  Linking the phone number to the Voice application is required. If the number
  is not linked, Vonage will not call Menace Voice's Answer URL, and you may hear a
  busy or disconnected tone without seeing any Menace Voice application logs.
</Warning>

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

1. Open the [Vonage Dashboard](https://dashboard.nexmo.com/)
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 Menace Voice

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](https://developer.vonage.com/en/api/numbers).

### Step 2: Assign an Inbound Workflow to the Phone Number in Menace Voice

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://<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

   <Note>
     Menace Voice pushes these settings automatically when you save the inbound
     workflow in Step 2. If the fields are empty, show a different URL, or
     Menace Voice surfaced a sync warning on save, check the API Key, API Secret,
     Application ID, and Signature Secret in Menace Voice, then save the inbound
     workflow again. On self-hosted Menace Voice, the backend domain must be publicly
     reachable by Vonage.
   </Note>

### Step 4: Verify Setup

- Ensure your Menace Voice instance is publicly accessible
- Verify your public backend URL is reachable from the internet
- Use the [Vonage logs](https://dashboard.nexmo.com/logs) or Voice Inspector to confirm Vonage is sending the Answer webhook to Menace Voice

### Test Inbound Calling

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

<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="Signed webhook validation failed">
    - Verify the Signature Secret in Menace Voice matches the Vonage account's signature secret
    - Ensure signed callbacks are enabled on the Vonage Voice application
    - Check that the webhook request includes an `Authorization` header
    - Confirm the application belongs to the same API Key saved in Menace Voice
  </Accordion>
  
  <Accordion title="Invalid phone number error">
    - Remove the '+' prefix for Vonage (use `14155551234` not `+14155551234`)
    - Ensure numbers are in [E.164](https://en.wikipedia.org/wiki/E.164) format (country code + number, no spaces or dashes) 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)](/configurations/interruption#what-is-vad) behavior — this is what detects when the caller starts and stops speaking
  </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 the Vonage application's Answer URL is set to `https://<your-backend-domain>/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 exists in your Menace Voice telephony configuration and has an **Inbound workflow** assigned
  </Accordion>

  <Accordion title="Inbound call gives busy tone and Menace Voice shows no logs">
    - Confirm the Vonage number is linked to the Voice application configured in Menace Voice
    - Confirm the Voice application has the Menace Voice Answer URL set with method `POST`
    - Confirm your backend domain is public; Vonage cannot call `localhost`
    - Check Vonage logs for Answer URL delivery errors before debugging Menace Voice
  </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 Menace Voice telephony configuration (used to identify the org from the inbound webhook)
    - Verify WebSocket connection establishes successfully
    - Review call logs for error messages
  </Accordion>
</AccordionGroup>

## Best Practices

- **Security**: Private keys are stored securely in the database
- **Signed callbacks**: Keep Vonage signed callbacks enabled and keep the Signature Secret in Menace Voice 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](https://www.vonage.com/communications-apis/voice/pricing/) for current rates.

## Next Steps

- Test your Vonage integration with a simple workflow
- Review [VAD and interruption behavior](/configurations/interruption) for your workflow's nodes
- Set up monitoring and alerts
- Explore advanced features like call recording