Nexmo Call Control Objects

A Nexmo Call Control Object (NCCO) is a JSON array of actions that is used to control the flow of a Voice API Call.

This section describes:

About Nexmo Call Control Objects

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.

The general schema of an NCCO is:

[
  {
    "action": "<value>",
    "<option1>": "<value>",
    "<option2>": [
      {
        "type": "<value>",
        "<option1>": "<value>"
      },
      {
        "type": "<value>",
        "<option1>": "<value>",
        "<option2>": "<value>"
      }
    ]
  }
]

The elements of an NCCO instruction are:

  • action - something to be done in the Call.
  • option - how to customize an action.
  • type - describes an option. For example, type=phone for an endpoint option.

The order of actions in the NCCO controls the flow of the call. This is called the stack. The order of instructions on the stack matters: the actions are executed in order. Unless explicitly halted NCCO are executed on a FIFO basis. When an action is completed, the next action in the stack is executed. Actions that have to complete before the next action can be executed are synchronous. Other actions are asynchronous. That is, they are supposed to continue over the following actions until a condition is met. For example, a record action terminates when the endOnSilence option is met. When all the actions in the NCCO are complete, the voice call ends.

Some actions and options are:

[
 {
   "action": "talk",
   "text": "Hello, you are listening to a call made using Voice API."
 }
]
[
  {
    "action": "record",
    "eventUrl": ["https://example.com/recordings"],
    "endOnSilence": "3"
  },
  {
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "from":"441632960960",
    "endpoint": [
      {
        "type": "phone",
        "number": "441632960961"
      }
    ]
  }
]
[
  {
    "action": "stream",
    "streamUrl": ["https://acme.com/streams/music.mp3"]
  }
]
[
  {
    "action": "talk",
    "text": "Welcome to a Voice API I V R. ",
    "voiceName": "Amy",
    "bargeIn": false
  },
  {
    "action": "talk",
    "text": "Press 1 for maybe and 2 for not sure followed by the hash key",
    "voiceName": "Amy",
    "bargeIn": true
  },
  {
    "action": "input",
    "submitOnHash": "true",
    "eventUrl": ["https://example.com/ivr"]
  }
]

For your NCCO to execute correctly, the JSON syntax must be valid. It is better to generate JSON dynamically using a JSON library than to attempt to write it yourself programatically.

The actions you can use in an NCCO are:

  • record - all or part of a call
  • conversation - create a standard or hosted conversation
  • connect - connect to a connectable endpoint such as a phone number
  • talk - send synthesized speech to a conversation
  • stream - send audio files to a conversation
  • input - collect digits and speech from the person you are calling, then process them

Creating a custom call or conversation for each user

When you make an outbound call or accept an inbound call, Nexmo makes a request to your webhook endpoint at answer_url and retrieves your NCCO. This request contains the following parameters:

Name Description
to The endpoint being called.
from The endpoint you are calling from.
conversation_uuid The unique ID for this Conversation.
uuid The unique ID for this Call.

You can use these parameters to customize the NCCO you return to Nexmo. The following code examples show how to provide the NCCO that controls your call or conversation:

<?php

$method = $_SERVER['REQUEST_METHOD'];

switch ($method) {
  case 'GET':
    //Retrieve with the parameters in this request
    $to = $request['to']; //The endpoint being called
    $from = $request['from']; //The endpoint you are calling from
    $conversation_uuid = $request['conversation_uuid']; //The unique ID for this Conversation
    $uuid = $request['uuid']; //The unique ID for this Call

    //For more advanced Conversations you use the paramaters to personalize the NCCO
    //Dynamically create the NCCO to run a conversation from your virtual number
    if( $to == "441632960960")
      $ncco='[
      {
        "action": "talk",
        "text": "Hello Russell, welcome to a Call made with Voice API"
      }
      ]';
    else
      $ncco='[
      {
        "action": "talk",
        "text": "Hello Rebekka, welcome to a Call made with Voice API"
      }
      ]';

    header('Content-Type: application/json');
    echo $ncco;
    break;
  default:
    //Handle your errors
    handle_error($request);
    break;
}
#To run this code, replace the MyHandler in
#https://wiki.python.org/moin/BaseHttpServer With the following code,
import time
import BaseHTTPServer
import re
import json

class MyHandler(BaseHTTPServer.BaseHTTPRequestHandler):
    def do_GET(s):
        #Parse parameters in the GET request
        parsed_path = urlparse(s.path)
        try:
                params = dict(
                [p.split('=') for p in parsed_path[4].split('&')])
        except:
                params = {}

        #Retrieve with the parameters in this request
        call_to = params['to']      #The endpoint being called
        call_form = params['from']  #The endpoint you are calling from
        conversation_uuid = params['conversation_uuid']     #The unique ID for this Conversation
        call_uuid = params['uuid']     #The unique ID for this Call

        #Dynamically create the NCCO to run a conversation from your virtual number
        if call_to == "441632960960":
            ncco=[
            {
                "action": "talk",
                "text": "Hello Russell, welcome to a Call made with Voice API"
                }
            ]
        else:
            ncco=[
            {
                "action": "talk",
                "text": "Hello Rebekka, welcome to a Call made with Voice API"
                }
            ]

        #For more advanced Conversations you use the paramaters to personalize the NCCO
        #Dynamically create the NCCO to run a conversation from your virtual number

        print "GET Request from " + s.path
        s.send_response(200)
        s.send_header("Content-type", "application/json")
        s.end_headers()
        s.wfile.write(json.dumps(ncco))
require 'socket'
require 'uri'
require 'json'

#Dynamically create the NCCO to send synthsized speech to a virtual number

# Initialize a TCPServer
def generate_ncco(request_line)
#Parse the parameters and check if the message was delivered
  params = URI::decode_www_form(request_line).to_h

  #Retrieve with the parameters in this request
  to = params['to']         #The endpoint being called
  from = params['from']     #The endpoint you are calling from
  conversation_uuid = params['conversation_uuid']    #The unique ID for this Conversation
  uuid = params['uuid']    #The unique ID for this Call
  #For more advanced Conversations you use the paramaters to personalize the NCCO

  #Dynamically create the NCCO to run a conversation from your virtual number
  if to == "441632960960"
    ncco=[
      {
        "action": "talk",
        "text": "Hello Russell, welcome to a Call made with Voice API"
      }
    ]
  else
    ncco=[
      {
        "action": "talk",
        "text": "Hello Rebekka, welcome to a Call made with Voice API"
      }
    ]
  end

  return ncco.to_json
end

server = TCPServer.new('', 9999)
# Wait for connections
loop do
  # Wait until a client connects
  socket = server.accept
  method, path = socket.gets.split
  resp = generate_ncco(path)
  # Return the 200 OK

  headers = ["HTTP/1.1 200 OK",
             "Content-Type: application/json",
             "Content-Length: #{resp.length}\r\n\r\n"].join("\r\n")
  socket.puts headers
  #Return the NCCO
  socket.puts resp
  # Close the socket, terminating the connection
  socket.close
end