Voice API

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 Nexmo how to control the 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 being:

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, 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

Run the following code:

const Nexmo = require('nexmo');

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

nexmo.calls.create({
  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']
}, (err, res) => {
  if(err) { console.error(err); }
  else { console.log(res); }
});

You can find this code in the Nexmo Node Quickstart repo.

Install the Nexmo PHP client:

composer require nexmo/client:@beta

Run the following code:

require_once 'vendor/autoload.php';

$basic  = new \Nexmo\Client\Credentials\Basic(API_KEY, API_SECRET);
$keypair = new \Nexmo\Client\Credentials\Keypair(file_get_contents(PRIVATE_KEY), APPLICATION_ID);

$client = new \Nexmo\Client(new \Nexmo\Client\Credentials\Container($basic, $keypair));

$call = $client->calls()->create([
    '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'],
]);

error_log($call);

You can find this code in the Nexmo PHP Quickstart repo.

Install the Nexmo Java client by adding the following to your build.gradle:

repositories {
    maven {
        url 'https://oss.sonatype.org/content/repositories/snapshots/'
    }
}

dependencies {
    compile 'com.nexmo:client:2.0.0-SNAPSHOT'
}

Run the following code:

        AuthMethod auth = new JWTAuthMethod(
                APPLICATION_ID,
                FileSystems.getDefault().getPath(PRIVATE_KEY)
        );
        NexmoClient client = new NexmoClient(auth);
        client.getVoiceClient().createCall(new Call(
                TO_NUMBER,
                FROM_NUMBER,
                "https://nexmo-community.github.io/ncco-examples/first_call_talk.json"
        ));

You can find this code in the Nexmo Java Quickstart repo.

Install the nexmo Python package:

  pip install nexmo

Run the following code:

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

You can find this code in the Nexmo Python Quickstart repo.

Install the Nexmo .NET package:

  Install-Package Nexmo.Csharp.Client

Run the following code:

  var results = Call.Do(new Call.CallCommand
  {
      to = new[]
      {
          new Call.Endpoint {
              type = "phone",
              number = TO_NUMBER
          }
      },
      from = new Call.Endpoint
      {
          type = "phone",
          number = FROM_NUMBER
      },
      answer_url = new[]
      {
          "https://nexmo-community.github.io/ncco-examples/first_call_talk.json"
      }
  });

You can find this code in the Nexmo .NET Quickstart repo.

Install the Nexmo Ruby gem:

  gem install nexmo

Run the following code:

require 'nexmo'

client = Nexmo::Client.new(
  key: API_KEY,
  secret: API_SECRET,
  application_id: APPLICATION_ID,
  private_key: File.read(PRIVATE_KEY)
)

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

puts response

You can find this code in the Nexmo Ruby Quickstart repo.

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.

Guide NCCO Action REST 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}
Hangup call PUT /calls/{uuid}
Mute a call PUT /calls/{uuid}
Ear muff a call PUT /calls/{uuid}
Transfer a call to another NCCO 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 text-to-speech to a call talk PUT /calls/{uuid}/talk
Stop sending text-to-speech to a call DELETE /calls/{uuid}/talk
Send DTMF to a call PUT calls/{uuid}/dtmf

References

Tutorials

Previous   Next