NCCO reference

A Call Control Object (NCCO) is represented by a JSON array. You can use it to control the flow of a Voice API call. For your NCCO to execute correctly, the JSON objects must be valid.

While developing and testing NCCOs, you can use the Voice Playground to try out NCCOs interactively. You can read more about it in the Voice API Overview or go directly to the Voice Playground in the Dashboard.

NCCO actions

The order of actions in the NCCO controls the flow of the Call. 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 Call ends.

The NCCO actions and the options and types for each action are:

Record

Use the record action to record a Call or part of a Call:

[
  {
    "action": "record",
    "eventUrl": ["https://example.com/recordings"]
  },
  {
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "from":"447700900000",
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001"
      }
    ]
  }
]

The record action is asynchronous. Recording starts when the record action is executed in the NCCO and finishes when the synchronous condition in the action is met. That is, endOnSilence, timeOut or endOnKey. If you do not set a synchronous condition, the Voice API immediately executes the next NCCO without recording.

For information about the workflow to follow, see Recording.

You can use the following options to control a record action:

The following example shows the return parameters sent to eventUrl:

{
  "start_time": "2020-01-01T12:00:00Z",
  "recording_url": "https://api.nexmo.com/v1/files/aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "size": 12345,
  "recording_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "end_time": "2020-01-01T12:01:00Z",
  "conversation_uuid": "bbbbbbbb-cccc-dddd-eeee-0123456789ab",
  "timestamp": "2020-01-01T14:00:00.000Z"
}

Possible return parameters are:

Conversation

You can use the conversation action to create standard or moderated conferences, while preserving the communication context. Using conversation with the same name reuses the same persisted Conversation. The first person to call the virtual number assigned to the conversation creates it. This action is synchronous.

The following NCCO examples show how to configure different types of Conversation. You can use the answer_url webhook GET request parameters to ensure you deliver one NCCO to participants and another to the moderator.

[
  {
    "action": "conversation",
    "name": "nexmo-conference-standard",
    "record": true
  }
]

// As the customer is the first person to join, there is no canHear/canSpeak entry
// The customer's leg ID is 6a4d6af0-55a6-4667-be90-8614e4c8e83c
[
  {
    "action": "conversation",
    "name": "selective-audio-demo",
    "startOnEnter": false,
    "musicOnHoldUrl": ["https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3"],
  }
]

// The agent joins and can both hear, and speak to the customer
// The agent's leg ID is 533c0874-f43d-446c-a153-f35bf30783fa
[
  {
    "action": "conversation",
    "name": "selective-audio-demo",
    "startOnEnter": true,
    "record": true,
    "canHear": ["6a4d6af0-55a6-4667-be90-8614e4c8e83c"], // Customer leg ID
    "canSpeak": ["6a4d6af0-55a6-4667-be90-8614e4c8e83c"] // Customer leg ID
  }
]

// Finally, the supervisor joins the conversation. They can hear both the customer
// and the agent, but only speak to the agent
// The supervisor's leg ID is e2833e43-db39-4c1a-b689-d17ad2cf3529
[
  {
    "action": "conversation",
    "name": "selective-audio-demo",
    "startOnEnter": true,
    "record": true,
    "canHear": ["6a4d6af0-55a6-4667-be90-8614e4c8e83c", "533c0874-f43d-446c-a153-f35bf30783fa"] // Customer leg ID, Agent leg ID
    "canSpeak": ["533c0874-f43d-446c-a153-f35bf30783fa"] // Agent leg ID
  }
]

[
  {
    "action": "talk",
    "text": "Welcome to a Vonage moderated conference. We will connect you when an agent is available",
    "voiceName": "Amy"
  },
  {
    "action": "conversation",
    "name": "nexmo-conference-moderated",
    "startOnEnter": false,
    "musicOnHoldUrl": ["https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3"]
  }
]

[
  {
    "action": "conversation",
    "name": "nexmo-conference-moderated",
    "record": true,
    "startOnEnter": true
  }
]

You can use the following options to control a conversation action:

Connect

You can use the connect action to connect a call to endpoints such as phone numbers or a VBC extension.

This action is synchronous, after a connect the next action in the NCCO stack is processed. A connect action ends when the endpoint you are calling is busy or unavailable. You ring endpoints sequentially by nesting connect actions.

The following NCCO examples show how to configure different types of connections.

[
  {
    "action": "talk",
    "text": "Please wait while we connect you"
  },
  {
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "timeout": "45",
    "from": "447700900000",
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001",
        "dtmfAnswer": "2p02p"
      }
    ]
  }
]

[
  {
    "action": "talk",
    "text": "Please wait while we connect you"
  },
  {
    "action": "connect",
    "eventType": "synchronous",
    "eventUrl": [
      "https://example.com/events"
    ],
    "from": "447700900000",
    "endpoint": [
      {
        "type": "websocket",
        "uri": "ws://example.com/socket",
        "content-type": "audio/l16;rate=16000",
        "headers": {
            "name": "J Doe",
            "age": 40,
            "address": {
                "line_1": "Apartment 14",
                "line_2": "123 Example Street",
                "city": "New York City"
            },
            "system_roles": [183493, 1038492, 22],
            "enable_auditing": false
        }
      }
    ]
  }
]

[
  {
    "action": "talk",
    "text": "Please wait while we connect you"
  },
  {
    "action": "connect",
    "eventUrl": [
      "https://example.com/events"
    ],
    "from": "447700900000",
    "endpoint": [
      {
        "type": "app",
        "user": "jamie"
      }
    ]
  }
]

[
  {
    "action": "talk",
    "text": "Please wait while we connect you"
  },
  {
    "action": "connect",
    "eventUrl": [
      "https://example.com/events"
    ],
    "from": "447700900000",
    "endpoint": [
      {
        "type": "sip",
        "uri": "sip:rebekka@sip.mcrussell.com",
        "headers": { "location": "New York City", "occupation": "developer" }
      }
    ]
  }
]

[
  {
    "action": "connect",
    "from": "447700900000",
    "timeout": 5,
    "eventType": "synchronous",
    "eventUrl": [
      "https://example.com/event-fallback"
    ],
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001"
      }
    ]
  }
]

[
  {
    "action": "record",
    "eventUrl": ["https://example.com/recordings"]
  },
  {
    "action": "connect",
    "eventUrl": ["https://example.com/events"],
    "from": "447700900000",
    "endpoint": [
      {
        "type": "phone",
        "number": "447700900001"
      }
    ]
  }
]

[
  {
    "action": "talk",
    "voiceName": "Russell",
    "text": "Thank you for calling. Connecting you to extension."
  },
  {
    "action": "connect",
    "endpoint": [
      {
        "type": "vbc",
        "extension": "111"
      }
    ]
  }
]

You can use the following options to control a connect action:

Endpoint Types and Values

Phone (PSTN) - phone numbers in E.164 format

App - Connect the call to a RTC capable application

WebSocket - the WebSocket to connect to

SIP - the SIP endpoint to connect to

VBC - the Vonage Business Cloud (VBC) extension to connect to

Talk

The talk action sends synthesized speech to a Conversation.

The text provided in the talk action can either be plain, or formatted using SSML. SSML tags provide further instructions to the text-to-speech synthesizer which allow you to set pitch, pronunciation and to combine together text in multiple languages. SSML tags are XML-based and sent inline in the JSON string.

By default, the talk action is synchronous. However, if you set bargeIn to true you must set an input action later in the NCCO stack. The following NCCO examples shows how to send a synthesized speech message to a Conversation or Call:

[
  {
    "action": "talk",
    "text": "You are listening to a Call made with Voice API"
  }
]

[
  {
    "action": "talk",
    "text": "Welcome to a Voice API I V R. ",
    "language": "en-GB",
    "bargeIn": false
  },
  {
    "action": "talk",
    "text": "Press 1 for maybe and 2 for not sure followed by the hash key",
    "language": "en-GB",
    "bargeIn": true
  },
  {
    "action": "input",
    "submitOnHash": true,
    "eventUrl": ["https://example.com/ivr"]
  }
]

[
  {
    "action": "talk",
    "text": "<speak><prosody rate='fast'>I can speak fast.</prosody></speak>"
  }
]

You can use the following options to control a talk action:

Stream

The stream action allows you to send an audio stream to a Conversation

By default, the stream action is synchronous. However, if you set bargeIn to true you must set an input action later in the NCCO stack.

The following NCCO example shows how to send an audio stream to a Conversation or Call:

[
  {
    "action": "stream",
    "streamUrl": ["https://acme.com/streams/music.mp3"]
  }
]

[
  {
    "action": "stream",
    "streamUrl": ["https://acme.com/streams/announcement.mp3"]
    "bargeIn": "true"
  },
  {
    "action": "input",
    "submitOnHash": "true",
    "eventUrl": ["https://example.com/ivr"]
  }
]

You can use the following options to control a stream action:

The audio stream referred to should be a file in MP3 or WAV format. If you have issues with the file playing, please encode it to the following technical specification: What kind of prerecorded audio files can I use?

Cache-Control: public, max-age=360000

Input

You can use the input action to collect digits or speech input by the person you are calling. This action is synchronous, Vonage processes the input and forwards it in the parameters sent to the eventUrl webhook endpoint you configure in your request. Your webhook endpoint should return another NCCO that replaces the existing NCCO and controls the Call based on the user input. You could use this functionality to create an Interactive Voice Response (IVR). For example, if your user presses 4 or says "Sales", you return a connect NCCO that forwards the call to your sales department.

The following NCCO example shows how to configure an IVR endpoint:

[
  {
    "action": "talk",
    "text": "Please enter a digit or say something"
  },
  {
    "action": "input",
    "eventUrl": [
      "https://example.com/ivr"
    ],
    "type": [ "dtmf", "speech" ],
    "dtmf": {
      "maxDigits": 1
    },
    "speech": {
      "context": [ "sales", "support" ]
    }
  }
]

The following NCCO example shows how to use bargeIn to allow a user to interrupt a talk action. Note that an input action must follow any action that has a bargeIn property (e.g. talk or stream).

[
  {
    "action": "talk",
    "text": "Please enter a digit or say something",
    "bargeIn": true
  },
  {
    "action": "input",
    "eventUrl": [
      "https://example.com/ivr"
    ],
    "type": [ "dtmf", "speech" ],   
    "dtmf": {
      "maxDigits": 1
    },
    "speech": {
      "context": [ "sales", "support" ]
    }   
  }
]

The following options can be used to control an input action:

DTMF Input Settings

Speech Recognition Settings

The following example shows the parameters sent to the eventUrl webhook for DTMF input:

{
  "speech": { "results": [ ] },
  "dtmf": {
    "digits": "1234",
    "timed_out": true
  },
  "from": "15551234567",
  "to": "15557654321",
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "bbbbbbbb-cccc-dddd-eeee-0123456789ab",
  "timestamp": "2020-01-01T14:00:00.000Z"
}

The following example shows the parameters sent back to the eventUrl webhook for speech input:

{
  "speech": {
    "recording_url": "https://api-us.nexmo.com/v1/files/eeeeeee-ffff-0123-4567-0123456789ab",
    "timeout_reason": "end_on_silence_timeout",
    "results": [
      {
        "confidence": "0.9405097",
        "text": "sales"
      },
      {
        "confidence": "0.70543784",
        "text": "sails"
      },
      {
        "confidence": "0.5949854",
        "text": "sale"
      }
    ]
  },
  "dtmf": {
    "digits": null,
    "timed_out": false
  },
  "from": "15551234567",
  "to": "15557654321",  
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
  "conversation_uuid": "bbbbbbbb-cccc-dddd-eeee-0123456789ab",
  "timestamp": "2020-01-01T14:00:00.000Z"
}

Input Return Parameters

See Webhook Reference for input parameters which are returned to the eventUrl.

Notify

Use the notify action to send a custom payload to your event URL. Your webhook endpoint can return another NCCO that replaces the existing NCCO or return an empty payload meaning the existing NCCO will continue to execute.

[
  {
    "action": "notify",
    "payload": {
      "foo": "bar"
    },
    "eventUrl": [
      "https://example.com/webhooks/event"
    ],
    "eventMethod": "POST"
  }
]

Pay

The pay action collects credit card information with DTMF input in a secure (PCI-DSS compliant) way. See Payments over the Phone guide to learn more.

[
  {
    "action": "talk",
    "text": "Thank you for your order, we will charge 9 dollars 99 cents now"
  },
  {
    "action": "pay",
    "eventUrl": [
      "https://example.com/pay"
    ],
    "amount": 9.99
  }
]

The following options can be used to control an pay action:

Prompts Voice Settings

Prompts Text Settings

Error Prompts

Possible errors depend on prompt type (see above): Prompt Type | Error Type | Description -- | -- | -- CardNumber | InvalidCardType | The type of the card entered is not in the list of allowed card types CardNumber| InvalidCardNumber | The card number entered is not correct ExpirationDate | InvalidExpirationDate | Invalid month number or date in the past SecurityCode | InvalidSecurityCode | Security code validation did not pass CardNumber, ExpirationDate, Security | Timeout | No user input during 10 seconds

Error prompts example:

{
  "type": "ExpirationDate",
  "text": "Please enter expiration date",
  "errors": {
    "InvalidExpirationDate": {
      "text": "Invalid expiration date. Please try again"
    },
    "Timeout": {
      "text": "Please enter your 4 digit credit card expiration date"
    }
  }
}