Before you begin

What are Code Snippets?

Code snippets are short pieces of code you can reuse in your own applications. The code snippets use code from example repositories.

Please read this information carefully, so you can best use the code snippets.

Prerequisites

Before going further, you must create a Vonage account to manage applications and numbers.

Create an Application

Go to the Application's page on the Dashboard, and define a Name for your Application.

Make sure to click on the Generate public and private key button, and keep the file private.key around.

Then, enable the Voice capability. For the moment, leave everything by default.

An example of enabling Voice capabilities

Finally, click Generate new application at the bottom of the page.

Check out Getting Started with Vonage CLI for more information on how to install and configure the CLI.

Use the following command to create a Vonage application:

vonage apps create 'Your application'

✅ Creating Application
Saving private key ... Done!
Application created

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  None Enabled

vonage apps create 'Your application'

✅ Creating Application
Saving private key ... Done!
Application created

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
  None Enabled

vonage apps create 'Your application' ✅ Creating Application Saving private key ... Done! Application created Name: Your application Application ID: 00000000-0000-0000-0000-000000000000 Improve AI: Off Private/Public Key: Set Capabilities: None Enabled

Once you have the application, you then need to add the voice capabilities; make sure you replace the webhook URLs with your own:

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 voice `
  --voice-answer-url='https://example.com/webhooks/voice/answer' `
  --voice-event-url='https://example.com/webhooks/voice/event' `
  --voice-fallback-url='https://example.com/webhooks/voice/fallback'
  
✅ Fetching Application
✅ Adding voice capability to application 00000000-0000-0000-0000-000000000000

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
 VOICE:
    Uses Signed callbacks: On
    Conversation TTL: 41 hours
    Leg Persistence Time: 6 days
    Event URL: [POST] https://example.com/webhooks/voice/event
    Answer URL: [POST] https://example.com/webhooks/voice/answer
    Fallback URL: [POST] https://example.com/webhooks/voice/fallback

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 voice ^
  --voice-answer-url='https://example.com/webhooks/voice/answer' ^
  --voice-event-url='https://example.com/webhooks/voice/event' ^
  --voice-fallback-url='https://example.com/webhooks/voice/fallback'
  
✅ Fetching Application
✅ Adding voice capability to application 00000000-0000-0000-0000-000000000000

Name: Your application
Application ID: 00000000-0000-0000-0000-000000000000
Improve AI: Off
Private/Public Key: Set

Capabilities:
 VOICE:
    Uses Signed callbacks: On
    Conversation TTL: 41 hours
    Leg Persistence Time: 6 days
    Event URL: [POST] https://example.com/webhooks/voice/event
    Answer URL: [POST] https://example.com/webhooks/voice/answer
    Fallback URL: [POST] https://example.com/webhooks/voice/fallback

vonage apps capabilities update 00000000-0000-0000-0000-000000000000 voice \ --voice-answer-url='https://example.com/webhooks/voice/answer' \ --voice-event-url='https://example.com/webhooks/voice/event' \ --voice-fallback-url='https://example.com/webhooks/voice/fallback' ✅ Fetching Application ✅ Adding voice capability to application 00000000-0000-0000-0000-000000000000 Name: Your application Application ID: 00000000-0000-0000-0000-000000000000 Improve AI: Off Private/Public Key: Set Capabilities: VOICE: Uses Signed callbacks: On Conversation TTL: 41 hours Leg Persistence Time: 6 days Event URL: [POST] https://example.com/webhooks/voice/event Answer URL: [POST] https://example.com/webhooks/voice/answer Fallback URL: [POST] https://example.com/webhooks/voice/fallback

The application is then created and has the required capabilities. Creating an application and adding application capabilities are covered in detail in the Application documentation.

Rent a Number

In the Dashboard, go to the Buy Numbers page. Make sure to tick Voice in the search filter, and select the country you want to buy a number in. In some countries, you may need to request a number, as additional documents may be required.

You can then click the Buy button next to the number you want, and validate your purchase.

Congratulations! Your virtual number is now listed in Your Numbers.

You can rent a number using the Vonage CLI. The following command searches for an available number in the United States:

vonage numbers search US

✅ Searching for numbers

There is 1 number available for purchase in United States

Number       Type    Features         Monthly Cost  Setup Cost
-----------  ------  ---------------  ------------  ----------
16127779311  Mobile  MMS, SMS, VOICE  €0.90         €0.00

Use vonage numbers buy to purchase.

vonage numbers search US

✅ Searching for numbers

There is 1 number available for purchase in United States

Number       Type    Features         Monthly Cost  Setup Cost
-----------  ------  ---------------  ------------  ----------
16127779311  Mobile  MMS, SMS, VOICE  €0.90         €0.00

Use vonage numbers buy to purchase.

vonage numbers search US ✅ Searching for numbers There is 1 number available for purchase in United States Number Type Features Monthly Cost Setup Cost ----------- ------ --------------- ------------ ---------- 16127779311 Mobile MMS, SMS, VOICE €0.90 €0.00 Use vonage numbers buy to purchase.

Use this command to purchase a number:

vonage numbers buy US 16127779311 
✅ Searching for numbers
Are you sure you want to purchase the number 16127779311 for €0.90? [y/n] y

✅ Purchasing number
Number 16127779311 purchased

Number: 16127779311 
Country: 🇺🇸 United States
Type: Mobile
Features: MMS, SMS, VOICE
Monthly Cost: €0.90
Setup Cost: €0.00
Linked Application ID: Not linked to any application
Voice Callback: Not Set
Voice Callback Value: Not Set
Voice Status Callback: Not Set

vonage numbers buy US 16127779311 
✅ Searching for numbers
Are you sure you want to purchase the number 16127779311 for €0.90? [y/n] y

✅ Purchasing number
Number 16127779311 purchased

Number: 16127779311 
Country: 🇺🇸 United States
Type: Mobile
Features: MMS, SMS, VOICE
Monthly Cost: €0.90
Setup Cost: €0.00
Linked Application ID: Not linked to any application
Voice Callback: Not Set
Voice Callback Value: Not Set
Voice Status Callback: Not Set

vonage numbers buy US 16127779311 ✅ Searching for numbers Are you sure you want to purchase the number 16127779311 for €0.90? [y/n] y ✅ Purchasing number Number 16127779311 purchased Number: 16127779311 Country: 🇺🇸 United States Type: Mobile Features: MMS, SMS, VOICE Monthly Cost: €0.90 Setup Cost: €0.00 Linked Application ID: Not linked to any application Voice Callback: Not Set Voice Callback Value: Not Set Voice Status Callback: Not Set

Specify an alternative two-character country code to purchase a number in another country.

Link a Number

Now that you have both an application and a number, you need to link them together.

Go to the Application page, and click on the application you created earlier.

In the Voice section, click on the Link button next to the number you want to link.

Now that you have both an application and a number, you need to link them together.

vonage apps numbers link 00000000-0000-0000-0000-000000000000 16127779311

✅ Fetching Application
Fetching Owned numbers [===============================================] 1/1 100%

Number linked

Number: 16127779311
Country: 🇺🇸 United States
Type: Toll-free
Features: MMS, SMS, VOICE
Monthly Cost: Not Set
Setup Cost: Not Set
Linked Application ID: 00000000-0000-0000-0000-000000000000
Voice Callback: app
Voice Callback Value: 00000000-0000-0000-0000-000000000000
Voice Status Callback: Not Set

vonage apps numbers link 00000000-0000-0000-0000-000000000000 16127779311

✅ Fetching Application
Fetching Owned numbers [===============================================] 1/1 100%

Number linked

Number: 16127779311
Country: 🇺🇸 United States
Type: Toll-free
Features: MMS, SMS, VOICE
Monthly Cost: Not Set
Setup Cost: Not Set
Linked Application ID: 00000000-0000-0000-0000-000000000000
Voice Callback: app
Voice Callback Value: 00000000-0000-0000-0000-000000000000
Voice Status Callback: Not Set

vonage apps numbers link 00000000-0000-0000-0000-000000000000 16127779311 ✅ Fetching Application Fetching Owned numbers [===============================================] 1/1 100% Number linked Number: 16127779311 Country: 🇺🇸 United States Type: Toll-free Features: MMS, SMS, VOICE Monthly Cost: Not Set Setup Cost: Not Set Linked Application ID: 00000000-0000-0000-0000-000000000000 Voice Callback: app Voice Callback Value: 00000000-0000-0000-0000-000000000000 Voice Status Callback: Not Set

Other resources:

Our blog post on how to use Ngrok.

Replaceable variables

Generic replaceable

The following replaceable information depends on the library and specific call:

Key	Description
`VONAGE_API_KEY`	Your Vonage API key (see it on your dashboard).
`VONAGE_API_SECRET`	Your Vonage API secret (also available on your dashboard).
`VONAGE_APPLICATION_PRIVATE_KEY_PATH`	Private key path.
`VONAGE_APPLICATION_PRIVATE_KEY`	Private key.
`VONAGE_APPLICATION_ID`	The Vonage Application ID.
`JWT`	Used to authenticate your request. See Authentication for more information, including how to generate a JWT.

Numbers

All phone numbers are in E.164 format.

Key	Description
`VONAGE_VIRTUAL_NUMBER`	Your Vonage Number. E.g. `447700900000`
`VOICE_TO_NUMBER`	The recipient number to call, e.g. `447700900002`.

UUIDs

UUIDs are typically used in the code snippets to identify a specific call.

Key	Description
`VOICE_CALL_ID`	The UUID of the call leg.

Specific replaceable/variables

Some code snippets have more specialized variables that will need to be replaced by actual values. These may be specified on a per-code snippet basis.

Authentication

Voice API requires authentication using JWTs. You can generate a JWT using the Vonage CLI or the online tool.

Webhooks

The main ones you will meet here are:

/webhooks/answer - Vonage makes a GET request here when you receive an inbound call. You respond with an NCCO.
/webhooks/event - Vonage makes POST requests here when an event occurs. You receive a JSON event.
/webhooks/recordings - Vonage makes a POST request here when the recording is available. You receive a JSON object with recording details.
/webhooks/dtmf - Vonage POSTs user DTMF input here in a JSON object.

If you are using Ngrok you will set your webhook URLs in the Vonage Application object to something like:

https://demo.ngrok.io/webhooks/answer
https://demo.ngrok.io/webhooks/event
https://demo.ngrok.io/webhooks/recordings
https://demo.ngrok.io/webhooks/dtmf

Change demo in the above with whatever applies in your case.