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

In this document you can learn about:

Nexmo Voice API Concepts
How to Get Started with the Voice API
Voice API Features
References
Tutorials

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

Voice Playground

In the Nexmo Dashboard , you can try out the Voice API interactively in the Voice Playground. Once you are signed up for a Nexmo account , you can go to Voice Playground in the Dashboard (Voice ‣ Voice Playgrounds).

When you use the Voice Playgrounds, you will be guided through the process of buying a phone number and assigning it to the Playground, then you can interactively test NCCOs in the browser and see the results. Playgrounds also has a number of common use cases as examples you can try. These are listed below with links to guides and tutorials on how to implement them yourself.

Connecting two users (guide, tutorial)
Interactive Voice Response (IVR) using DTMF tones (guide, tutorial)
Conference Call (guide)
Send audio to call (NCCO reference, API reference)

More details are available in this blog post: Meet Voice Playground, Your Testing Sandbox for Nexmo Voice Apps

Using the Nexmo CLI tool

Before you begin:

Sign up for a Nexmo account
Install Node.JS

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*

Once you have installed NodeJS, you can install and setup the Nexmo CLI (Command Line Interface) as follows:

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

cURL
Node.js
Java
PHP
Python
Ruby

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"]}'

Install the Nexmo Node library:

npm install nexmo

Create an index.js:

const Nexmo = require('nexmo')

const nexmo = new Nexmo({
  apiKey: API_KEY,
  apiSecret: API_SECRET,
  applicationId: APPLICATION_ID,
  privateKey: PRIVATE_KEY
})

nexmo.calls.create({
  from: {
    type: 'phone',
    number: FROM_NUMBER
  },
  to: [{
    type: 'phone',
    number: TO_NUMBER
  }],
  answer_url: ['https://nexmo-community.github.io/ncco-examples/first_call_talk.json']
}, (error, response) => {
  if (error) {
    console.error(error)
  } else {
    console.log(response)
  }
})

Run the application:

node index.js

Create your build.gradle file and list your dependencies:

// build.gradle

repositories {
    mavenCentral()
}

dependencies {
    compile 'com.nexmo:client:2.0.2'
}

task fatJar(type: Jar, dependsOn:configurations.runtime) {
    baseName = project.name + '-with-dependencies'
    from { configurations.runtime.collect { it.isDirectory() ? it : zipTree(it) } }
    with jar
}
assemble.dependsOn fatJar

Create a Java source file that uses the client library to make a call. Replace APPLICATION_ID, PRIVATE_KEY_PATH, TO_NUMBER, and FROM_NUMBER with your values.

// src/main/java/mypackage/MakeCall.class
package mypackage;

import com.nexmo.client.NexmoClient;
import com.nexmo.client.auth.JWTAuthMethod;
import com.nexmo.client.voice.Call;

import java.nio.file.FileSystems;

public class MakeCall {
    public static void main(String[] args) throws Exception {
        NexmoClient client = new NexmoClient(new JWTAuthMethod(
                "APPLICATION_ID",
                FileSystems.getDefault().getPath("PRIVATE_KEY_PATH")
        ));
        client.getVoiceClient().createCall(new Call(
                "TO_NUMBER",
                "FROM_NUMBER",
                "https://nexmo-community.github.io/ncco-examples/first_call_talk.json"
        ));
    }
}

Build a JAR file containing the class and the nexmo client library:

gradle build

Run the application:

java -cp "build/libs/PROJECT-with-dependencies.jar" "mypackage.MakeCall"

Install the Nexmo PHP client

composer require nexmo/client:@beta

Create an index.php:

<?php 
require_once __DIR__ . '/../config.php';
require_once __DIR__ . '/../vendor/autoload.php';

// Building Blocks
// 1. Make a Phone Call
// 2. Play Text-to-Speech

$keypair = new \Nexmo\Client\Credentials\Keypair(file_get_contents(NEXMO_APPLICATION_PRIVATE_KEY_PATH), NEXMO_APPLICATION_ID);
$client = new \Nexmo\Client($keypair);

$call = $client->calls()->create([
    'to' => [[
        'type' => 'phone',
        'number' => TO_NUMBER
    ]],
    'from' => [
        'type' => 'phone',
        'number' => NEXMO_NUMBER
    ],
    'answer_url' => ['https://developer.nexmo.com/ncco/tts.json'],
]);

error_log($call);

Run:

php index.php

Install the Nexmo Python package:

pip install nexmo

Create a call.py:

import nexmo

PRIVATE_KEY = open(PRIVATE_KEY_PATH, 'r').read()
client = nexmo.Client(key=API_KEY, secret=API_SECRET,
    application_id=APPLICATION_ID, private_key=PRIVATE_KEY)

response = client.create_call({
  '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']
})

Run:

python call.py

Install the Nexmo Ruby library

gem install nexmo

Create app.rb

require 'nexmo'
PRIVATE_KEY = File.read(PRIVATE_KEY_PATH)

client = Nexmo::Client.new(
  application_id: APPLICATION_ID,
  private_key: PRIVATE_KEY
)

client.calls.create(
  from: { type: 'phone', number: FROM_NUMBER },
  to: [{ type: 'phone', number: TO_NUMBER }],
  answer_url: [
    'https://nexmo-community.github.io/ncco-examples/first_call_talk.json'
  ]
)

Run the application:

ruby app.rb

Voice API Features

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

Through a call to the Voice REST API
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`

Voice API Overview

Contents

Concepts

Getting Started

Voice Playground

Using the Nexmo CLI tool

Create a Nexmo Voice Application

Make a Text-to-Speech Call

Voice API Features

References

Tutorials