Action Flows That You Can Do With the Voice API
Published on March 27, 2023

You can build high-quality programmable voice applications in the cloud with Vonage Voice API and Python. For example, you can manage outbound and inbound calls in Call Control Objects, record and store calls, create a conference call, send text-to-speech messages in many languages with varieties of voices and accents.

NCCO - is Call Control Objects (NCCOs) that describe the flow of a Voice API call. NCCO is represented by a JSON array. Control Object is an essential part of a call that contains instructions that need to happen during the call. For example, in which order and how the call conversation should proceed.

This article will describe how to use NCCO builder with Python code snippets as an example.

NCCO builder, Python SDK

Use the builder to construct valid NCCO actions, which are modeled in the SDK as Pydantic models, and build them into an NCCO. In Pydantic models described required and optional parameters for related NCCO action. The NCCO actions supported by the builder are:

NCCO action Sample of NCCO Python object
Record record = Ncco.Record(eventUrl=['https://example.com'])
Conversation conversation = Ncco.Conversation(name='Audio demo')
Connect connect = Ncco.Connect(endpoint={'type':'phone','number':'123456789'})
Talk talk = Ncco.Talk(text='Press 1 for maybe and 2 for not sure followed by the hash key', language='en-GB')
Stream stream = Ncco.Stream(streamUrl='https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3')
Input input = Ncco.Input(type=['dtmf', 'speech'], dtfm={'maxDigits':'1'})
Notify notify = Ncco.Notify(payload={"foo": "bar"}, eventUrl='https://example.com/webhooks/event')

Do you want to use NCCO builder in your application? First, you need to Install Vonage SDK

pip install vonage

And import Vonage packages

import vonage
from vonage import Ncco

Build into an NCCO

Method Ncco.build_ncco can create an NCCO from the actions. This will be returned as a list of dictionaries representing each action and can be used in calls to the Voice API.

List of required and optional parameters you can find on NCCO reference page

Let's create NCCO that can connect two users.

The following code construct actions, talk and connect, that we need

talk = Ncco.Talk(text='Please wait while we connect you.')
connect = Ncco.Connect(endpoint={'type':'phone','number':'123456789'}, from_ = '12345678', timeout='20')

The Connect action has each valid endpoint type (phone, application, WebSocket, SIP, and VBC) specified as a Pydantic model, so these can be validated, though it is also possible to pass in a dict with the endpoint properties directly into the Ncco.Connect object.

Let's create NCCO with build_ncco method and two actions

ncco = Ncco.build_ncco(talk, connect)

The following JSON will be created

[
   {
      "action": "talk",
      "text": "Please wait while we connect you."
   },
   {
      "action": "connect",
      "endpoint" :[
         {
            "type": "phone",
            "number": "123456789"
         }
      ],
      "from": "12345678",
      "timeout":20
   }
]

If you use an NCCO object, you can validate it here.

If you are using NCCO builder, you can receive error messages in the terminal The following string can show a terminal error message if one of the required action options doesn't valid

string does not match regex "^[1-9]\d{6,14}$" (type=value_error.str.regex; pattern=^[1-9]\d{6,14}$)

Wrap-up

The new NCCO builder simplifies and can automate action creation. Based on official documentation and examples in this tutorial, you can use NCCO builder for your application. Sign in/Sign up for free and create your Voice application using the new programmatic creation of Call Control Objects.

Oleksii BorysenkoVonage Alumni

Oleksii is a Developer Advocate at Vonage, author and storyteller. His interests include AI/ML, unified communications, education technologies, cloud technologies, and open source.

Ready to start building?

Experience seamless connectivity, real-time messaging, and crystal-clear voice and video calls-all at your fingertips.

Subscribe to Our Developer Newsletter

Subscribe to our monthly newsletter to receive our latest updates on tutorials, releases, and events. No spam.