Voice API Overview

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) 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.

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
  • conversation – Connect the call to a named conversation or another participant

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.

For all the REST API endpoints, see Voice API Reference.

Further Reading