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

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.

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:

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.

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:

  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