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 API Overview

The Nexmo Voice API is the easiest way to build high-quality voice applications in the Cloud. With the Voice API you:

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

Contents

In this document you can learn about:

Concepts

  • Authentication with JWTs - interaction with the Voice API are authenticated using JWTs. The Nexmo libraries handle JWT generation using a unique Nexmo Voice Application ID and a Private Key. For more information on see Authenticating your applications
  • Nexmo Voice Applications - Nexmo Voice Applications represent a one-to-one mapping with the application that you are building. They contain configuration such virtual numbers and webhook callback URLs. You can create Nexmo Voice Applications using the Nexmo CLI or the Application API
  • Webhooks - when any event takes place relating to your Nexmo application HTTP callbacks are made to your application web server so that you can act upon them. For example, when an inbound call is made to a number associated with your Nexmo application.
  • NCCOs - Nexmo Call Control Objects are a set of actions that instruct the Nexmo how to control call to your Nexmo application. For example, you can connect a call, send synthesized speech using talk, stream audio, or record a call. They are represented in JSON form as an Array of objects. For more information see the NCCO Reference and NCCO guide.

Getting Started

Before you begin:

Note: If you do not wish to install Node in order to use the Nexmo CLI you can also create applications using the Application API*

Install and Setup the Nexmo CLI (Command Line Interface)

Install the Nexmo CLI:

$ npm install -g nexmo-cli

Note: depending on your system setup you may need to prefix the above command with sudo

Using your Nexmo API_KEY and API_SECRET, available from the dashboard getting started page  , you now setup the CLI with these credentials.

$ nexmo setup API_KEY API_SECRET

Create a Nexmo Voice Application

Create a Nexmo Voice Application within the Nexmo platform to contain configuration such as associated virtual numbers and webhook callback URLs.

$ nexmo app:create 'First Voice App' --type voice https://nexmo-community.github.io/ncco-examples/first_call_talk.json https://example.com/events --keyfile private.key

The output of the app:create command contains:

  • The ID of your Nexmo Voice Application
  • The location of the private.key
Application created: 635c2797-9295-4cdf-9232-d275f75ff096
Private Key saved to: private.key

Both of these are required to interact with the Nexmo Voice API.

For more information on the app:create command run nexmo app:create --help in your terminal or console.

Make a Text-to-Speech Call

In the examples replace API_KEY, API_SECRET, APPLICATION_ID, PRIVATE_KEY_PATH, TO_NUMBER and FROM_NUMBER with real values.

Create a JWT for authentication using the Application ID and the Nexmo CLI:

APPLICATION_JWT="$(nexmo jwt:generate ./private.key \
application_id=APPLICATION_ID)"

Make a call:

curl -X POST https://api.nexmo.com/v1/calls\
  -H "Authorization: Bearer "$APPLICATION_JWT\
  -H "Content-Type: application/json"\
  -d '{"to":[{"type": "phone","number": TO_NUMBER}],
      "from": {"type": "phone","number": FROM_NUMBER},
      "answer_url":["https://nexmo-community.github.io/ncco-examples/first_call_talk.json"]}'

Voice API Features

The Nexmo Voice API provides features which are actioned in one of two ways:

  1. Through a call to the Voice REST API
  2. By returning NCCOs from your app server webhook endpoints

The following table shows the features available and how are achieved.

Action + Guide NCCO API
Create outbound calls POST /calls
Accept inbound calls See Nexmo Call Control Objects
Retrieve all call information GET /calls
Retrieve information for a call GET /calls/{uuid}
End an in-progress call PUT /calls/{uuid}
Record a call record
Collect user input from a call (IVR) input
Create conference calls conversation
Connect calls to phone endpoints connect
Connect calls to websocket endpoints connect
Stream audio to a call stream PUT /calls/{uuid}/stream
Stop streaming audio to a call DELETE /calls/{uuid}/stream
Send synthesized speech to a call talk PUT /calls/{uuid}/talk
Stop sending synthesized speech to a call DELETE /calls/{uuid}/talk
Send Dual-tone multi-frequency (DTMF) to a call PUT calls/{uuid}/dtmf

References

Tutorials