Vonage Voice Application Helpers

1.4.0 · active · verified Thu Apr 16

The `vonage-voice` library provides helper functionality for building Voice Applications with the Vonage Voice API in Python. It is designed to be used in conjunction with the main `vonage` Python SDK (version 3.0.0 or higher), which contains the core Voice API client. This package facilitates NCCO (Nexmo Call Control Object) generation and other voice-related utilities, simplifying the creation of interactive voice experiences. The current version is 1.4.0.

Common errors

```
ModuleNotFoundError: No module named 'vonage'
```
cause You installed `vonage-voice` but forgot to install the main `vonage` SDK, which is a required dependency for the core client.

fix Run `pip install vonage` to install the main Vonage Python SDK.
```
AttributeError: 'Voice' object has no attribute 'create_call' or 'Client' object has no attribute 'voice'
```
cause This often indicates the Vonage `Client` object was not correctly initialized with application credentials (application ID and private key) required for Voice API access, or an outdated `vonage` package version.

fix Ensure `Client` is initialized with `application_id` and `private_key` (not just `api_key` and `api_secret` for voice calls). Also, verify the `vonage` package is `3.0.0` or higher: `pip install --upgrade vonage`.
```
TypeError: __init__ missing 1 required positional argument: 'text' (for TalkNcco)
```
cause When creating an NCCO action like `TalkNcco`, required parameters are missing in its constructor.

fix Consult the documentation for the specific NCCO action (e.g., `TalkNcco`) and provide all mandatory arguments. For `TalkNcco`, the `text` parameter is required: `TalkNcco(text='Your message here')`.

Warnings

gotcha The `vonage-voice` package provides NCCO helpers and utilities, but *does not* contain the core Vonage API client for making calls, sending messages, or managing applications. The primary client is located in the `vonage` package.
Fix: Always install `vonage` alongside `vonage-voice` (e.g., `pip install vonage vonage-voice`) and import the `Client` from `vonage` (`from vonage import Client`).
breaking The `vonage-voice` package depends on `vonage>=3.0.0`. Older versions of the `vonage` SDK (pre-3.0.0) used a different client initialization and API structure, leading to compatibility issues or missing features.
Fix: Ensure you are using `vonage-voice` with `vonage` version 3.0.0 or higher. Upgrade both packages if necessary: `pip install --upgrade vonage vonage-voice`.
gotcha NCCOs built with `vonage-voice` must be served via a webhook endpoint that Vonage can access over HTTP/HTTPS. The library only helps *construct* the NCCO object, not host or deliver it.
Fix: Develop a web server (e.g., using Flask or FastAPI) to listen for Vonage webhooks, generate the NCCO dynamically, and return it as a JSON response with the `Content-Type: application/json` header.

Install

pip install vonage-voice vonage Install vonage-voice and core SDK

Imports

Ncco
```
from vonage_voice import Ncco
```
TalkNcco
```
from vonage_voice import TalkNcco
```
ConnectNcco
```
from vonage_voice import ConnectNcco
```
Client
wrong:
```
from vonage_voice import Client
```
correct:
```
from vonage import Client
```
The core Vonage API Client resides in the 'vonage' package, not 'vonage-voice'. `vonage-voice` provides NCCO helpers.

Quickstart

This quickstart demonstrates how to create a simple NCCO (Nexmo Call Control Object) using the `vonage-voice` helpers. It also shows the initialization of the core Vonage API client from the `vonage` package, which is necessary for making actual API calls or serving the NCCO. Replace placeholders with your actual API credentials and phone numbers.

import os
from vonage import Client
from vonage_voice import Ncco, TalkNcco

# Ensure VONAGE_API_KEY and VONAGE_API_SECRET are set as environment variables
# OR VONAGE_APPLICATION_ID and VONAGE_PRIVATE_KEY

# Initialize the Vonage Client (from the 'vonage' package)
client = Client(
    key=os.environ.get('VONAGE_API_KEY', 'YOUR_API_KEY'),
    secret=os.environ.get('VONAGE_API_SECRET', 'YOUR_API_SECRET'),
    application_id=os.environ.get('VONAGE_APPLICATION_ID', ''),
    private_key=os.environ.get('VONAGE_PRIVATE_KEY', '').replace('\\n', '\n')
)

# Create an NCCO using vonage-voice helpers
ncco = Ncco()
ncco.add_action(TalkNcco(text='Hello from Vonage! This is an NCCO generated by vonage-voice.'))

# In a real application, you would return this NCCO as a JSON response
# to a webhook for an incoming call. For demonstration, print:
print(ncco.build())

# Example of making an outbound call (using the core 'vonage' client):
# Requires VONAGE_APPLICATION_ID and VONAGE_PRIVATE_KEY for voice calls.
# try:
#     call = client.voice.create_call({
#         'to': [{'type': 'phone', 'number': 'RECIPIENT_PHONE_NUMBER'}],
#         'from': {'type': 'phone', 'number': 'VIRTUAL_NUMBER'},
#         'answer_url': ['https://example.com/webhooks/answer'] # Your public webhook URL
#     })
#     print(f"Call initiated with UUID: {call['uuid']}")
# except Exception as e:
#     print(f"Error initiating call: {e}")

view raw JSON →