Welcome to Nexmo Developer

We are improving our Documentation, API references, learning resources & tooling to help you more effectively use our services. We want to help you find everything you need to integrate Nexmo APIs into your code.

As we start this transition, we’d love to hear from you with thoughts & suggestions. If you’ve got something, positive or negative, to tell us, please tell us using the feedback tool at the bottom of each guide or file an issue on GitHub. - Nexmo

Voice app components

Your Voice app interacts with the Voice API to securely create, receive and control Voice communication with your users.

The components in a Voice app are:

VAPI Architecture

  • Outbound - this component:
    • Generates JSON Web Tokens (JWTs) using the private_key allocated to your Voice app
    • Makes requests to Voice API to create calls to one or more users
    • From webhook endpoints, provides the Nexmo Call Control Objects (NCCO) to control the calls
    • Customizes live calls following user interaction using the Voice API and NCCOs
  • Inbound - From webhook endpoints, provides the NCCOs that handle inbound calls to and conferences hosted on the virtual number associated with this app
  • Status - a webhook endpoint that handles the progression of a live call and downloads recordings when the call status is complete

Your Voice app components communicate with one or more users in either a:

  • Conversation - a collection of one or more Calls. From an inbound text-to-speech message to a company conference call. The audio is a mix of all legs connected to the Conversation.
  • Call - a single leg connected to a Conversation. The audio in a Call consists of transmitted audio (Tx) and received audio (Rx). You use a Call to communicate between two end points.

A Conversation and the legs connected to it are identified by separate UUIDs (Universally Unique IDentifiers). This means you can manipulate Conversations and legs independently. For example, you can move a leg from one Conversation to another.

The following figure shows the components for a private voice communication system:

Voice API Call

Using the Voice API or NCCOs you can:

Action NCCO API
Connect to a phone number. connect POST https://api.nexmo.com/v1/calls
Record your Call. record  
Create a standard or moderated conference. conversation  
Send synthesized speech to a Call or Conversation. talk PUT https://api.nexmo.com/v1/calls/{uuid}/talk
Send an audio stream to a Call or Conversation. stream  
Collect digits input by the person you are calling. input  
Send dual-tone multi-frequency signalling (DTMF) tones to an active call   PUT https://api.nexmo.com/v1/calls/{uuid}/dtmf