Technical Details

The Vonage Voice API allows developers to programmatically manage voice calls using two complementary models:

  • One is initiated by your application, using REST API calls or SDKs.
  • The other is requested from your application by Vonage, using webhooks and NCCO (Nexmo Call Control Object - Nexmo is now Vonage) instructions.

This dual approach supports flexible call handling to implement various call flows and programmable voice use cases, from simple notifications to sophisticated contact center flows and AI integration.

Additionally, the Vonage Voice API allows to:

  • Build apps that scale with the web technologies you are already using.
  • Control the flow of inbound and outbound calls in JSON with NCCO.
  • Record and store inbound or outbound calls.
  • Create conference calls.
  • Send text-to-speech messages in 40 languages with different genders and accents.

Contents

In this document you can learn about:

Getting Started

To learn about all of the necessary steps to get up and running with the Vonage Voice API, please refer to the Getting Started guide.

Starting a Voice Call

To start a voice call from your backend application, use the HTTP endpoint:

POST /calls

This method initiates an outbound call to a phone number or SIP endpoint. You can use it directly via HTTP or through any Vonage Server SDKs.

See the Make a Call code snippet to learn more about initiating outbound calls.

When the call connects, Vonage requests instructions (in the form of an NCCO) from your webhook or static URL to determine how the call should proceed.

Call Instructions with NCCOs

An NCCO (Nexmo Call Control Object) is a JSON-based structure that defines what should happen during a call. You return it in response to Vonage’s webhook request when the call connects.

Common NCCO actions include:

  • talk – Convert text to speech and play it to the caller
  • stream – Play an audio file
  • record – Record the call audio
  • connect – Connect another participant to the conversation

You can find the full list of NCCO commands in the NCCO Reference.

Controlling an Active Call

Once a call is in progress, you can also control it dynamically using REST API endpoints:

  • PUT /calls/{uuid} – Update the call status (for example, hang up, transfer, mute)
  • PUT /talk and DELETE /talk – Start or stop text-to-speech during the call
  • PUT /talk and DELETE /stream – Start or stop streaming audio file

These actions let you modify the call behavior in real-time, based on user actions and your application logic.

See the Voice API Reference for a full list of REST API endpoints.

Further Reading