Voice communication

Make calls  from any software system.


Nexmo Voice Application

Voice operation application based on the cloud.

Key highlights

- Scales with existing web solutions
- Easy to configure
- Records and stores any call
- Conference calls
- Text-to-Speech messages in 23 languages
- Make up to 3 call request per second

Introduction

Nexmo Voice is one of the main Nexmo application ecosystems. It allows you to create and manage high-quality voice operation applications on the cloud.

Nexmo Voice is an HTTP-based RESTful API. All API accesses are over HTTPS combined with OAuth2.0 for extra security. Request and response bodies follow JSON format to make the exchange of information fast, easy and reliable.

General picture

 

Concepts

Conversation, leg, conference

Communication can be 1-to-1 or 1-to-n from or to the Nexmo platform. While 1-to-1 calls are known as a leg, 1-to-n calls are known as a conversation. Each call connected to a conversation is its own leg.

NCCO

A Nexmo Call Control Object (NCCO) is a JSON array that you use to control the flow of a Voice API call. For your NCCO to execute correctly, the JSON objects must be valid.

The Call event model is asynchronous. A static or dynamically created NCCO script provides the business logic for your Call. When a Call is placed to your number, Nexmo makes a synchronous request to the webhook endpoint you set as the answer_url for your number and retrieves the NCCO object that controls the Call.

Extended information regarding NCCOs can be found here.

Webhook

Method to augment or alter the behavior of your application via user-defined HTTP callbacks. In your case webhook defines the behavior of your application.

DTMF

Dual Tone Multi Frequency (DTMF), is a form of signaling used by phone systems to transmit the digits 0-9 and the * and # characters.

Text-to-Speech

Nexmo uses Text-to-speech engines to allow you to play machine generated speech in your calls. This feature can be added via NCCOs with the use of talk action or by making a put request on an in-progress call. There are 23 languages available with different styles and genders.

Recording

Nexmo Voice API offers the ability to record call audio in several ways:

- Record a call between two people in a passive 'monitor' manner
- Record audio from a single caller when they are prompted. For example, in a voicemail system
- Enable recording for a named conversation (using the conference action explained in the NCCO reference).

SIP Trunk

To use Session Initiation Protocol (SIP), see the SIP documentation page

Try it out!

You can try the application from different tools/platforms.

- SwaggerHub
- Postman
- cURL

Get the access token

SwaggerHub:

1. Click on Authenticate button
2. Paste your App Keys
3. Click on Authorize

Postman:

1. Fill the environment details with your app keys
2. Call GetAccessToken
3. Click on execute button
4. Check the response code and message

cURL:

Copy your app's credentials and replace APP_CONSUMER_KEY and APP_CONSUMER_SECRET with the copied values, then execute  below curl command to receive access token.

curl -X POST \
 'https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials' \
 -H 'content-type: application/x-www-form-urlencoded' \
 -d 'client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET'

Note: If you are using cURL for Windows then please use the below command.

curl -X POST "https://api-prd.kpn.com/oauth/client_credential/accesstoken?grant_type=client_credentials" -H "content-type: application/x-www-form-urlencoded" -d "client_id=APP_CONSUMER_KEY&client_secret=APP_CONSUMER_SECRET"

The authorization service returns a JSON message that contains the access token field.

Create the Nexmo Application

SwaggerHub:

1. Select  POST /applications
2. Click on Try out
3. Edit the request body by filling the name and answer_url
4. Click on execute button
5. Check the response code and message

Postman:

1. Click on (POST) Create new application resource
2. Fill the name and answer_url
3. Click on send
4. Check the response code and message

cURL

curl -X POST \
 'https://api-prd.kpn.com/communication/nexmo/applications \
 -H 'content-type: application/x-www-form-urlencoded' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -d 'name=exampleApp&type=voice&answer_url=https://www.example.com/my_answer_webhook&event_url=https://www.example.com/my_event_webhook

Remember the application uuid because it will be needed to make calls

Create a call

SwaggerHub:

Select  POST /voice/calls
Click on Try out
Update the ApplicationID header with your application identifier
Edit the request body. There's an example provided afterwards you can use
Click on execute button
Check the response code and message

Postman:

Click on (POST) Create an outbound call
Update the Headers section by filling the ApplicationId field
Update the body fields. There's an example provided afterwards you can use
Click on send
Check the response code and message

cURL:

curl -X 'https://api-prd.kpn.com/communication/nexmo/voice/call' \
 -H 'content-type: application/json' \
 -H 'Authorization: Bearer ACCESS_TOKEN' \
 -H 'ApplicationId: YOUR_APPLICATION_UUID' \
 -d '{"to":[{"type":"phone","number":"31666666666",},],"from":[{"type":"phone","number":"31666666666",},],"answer_url":"["https://example.com/answer"]",}'

Example of body

{
  "to": [
    {
      "type": "phone",
      "number": "NUMBER_TO_CALL"
    }
  ],
  "from": {
    "type": "phone",
    "number": "31XXXXXXXXX"
  },
  "answer_url": [
    "http://www.mocky.io/v2/5bec38f8330000f034fbc310"
  ]
}

The content in the answer_url determines what is going to happen when "to" answers the call.

In your case, the receiver will hear a record and join a conference. We describe the NCCOs as:

[
  {
    "action": "talk",
    "text": "Please wait while we connect you."
  },
  {
    "action": "conversation",
    "name": "nexmo-conference-moderated",
    "startOnEnter": "false",
    "musicOnHoldUrl": [
      "https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3"
    ]
  }
]

Resources

Application: Nexmo App Management resource. Allows CRUD on applications.

Voice: Voice call management resource. Allows CRUD and tuning the call.

Error messages

HTTP Code

Error Code

Description

302

302

Found. Link in Location Header.

401

401

Unauthorized

403

403

Forbidden

404

404

Not Found

429

429

Too Many Requests

500

500

Server Error

503

503

Service Unavailable