{"id":9404,"library":"vonage-voice","title":"Vonage Voice Application Helpers","description":"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.","status":"active","version":"1.4.0","language":"en","source_language":"en","source_url":"https://github.com/Vonage/vonage-python-sdk/tree/main/src/vonage_voice","tags":["voice","telephony","api","vonage","ncco","webhook","communications"],"install":[{"cmd":"pip install vonage-voice vonage","lang":"bash","label":"Install vonage-voice and core SDK"}],"dependencies":[{"reason":"Provides the core Vonage API client, which vonage-voice extends and depends on.","package":"vonage","optional":false}],"imports":[{"symbol":"Ncco","correct":"from vonage_voice import Ncco"},{"symbol":"TalkNcco","correct":"from vonage_voice import TalkNcco"},{"symbol":"ConnectNcco","correct":"from vonage_voice import ConnectNcco"},{"note":"The core Vonage API Client resides in the 'vonage' package, not 'vonage-voice'. `vonage-voice` provides NCCO helpers.","wrong":"from vonage_voice import Client","symbol":"Client","correct":"from vonage import Client"}],"quickstart":{"code":"import os\nfrom vonage import Client\nfrom vonage_voice import Ncco, TalkNcco\n\n# Ensure VONAGE_API_KEY and VONAGE_API_SECRET are set as environment variables\n# OR VONAGE_APPLICATION_ID and VONAGE_PRIVATE_KEY\n\n# Initialize the Vonage Client (from the 'vonage' package)\nclient = Client(\n    key=os.environ.get('VONAGE_API_KEY', 'YOUR_API_KEY'),\n    secret=os.environ.get('VONAGE_API_SECRET', 'YOUR_API_SECRET'),\n    application_id=os.environ.get('VONAGE_APPLICATION_ID', ''),\n    private_key=os.environ.get('VONAGE_PRIVATE_KEY', '').replace('\\\\n', '\\n')\n)\n\n# Create an NCCO using vonage-voice helpers\nncco = Ncco()\nncco.add_action(TalkNcco(text='Hello from Vonage! This is an NCCO generated by vonage-voice.'))\n\n# In a real application, you would return this NCCO as a JSON response\n# to a webhook for an incoming call. For demonstration, print:\nprint(ncco.build())\n\n# Example of making an outbound call (using the core 'vonage' client):\n# Requires VONAGE_APPLICATION_ID and VONAGE_PRIVATE_KEY for voice calls.\n# try:\n#     call = client.voice.create_call({\n#         'to': [{'type': 'phone', 'number': 'RECIPIENT_PHONE_NUMBER'}],\n#         'from': {'type': 'phone', 'number': 'VIRTUAL_NUMBER'},\n#         'answer_url': ['https://example.com/webhooks/answer'] # Your public webhook URL\n#     })\n#     print(f\"Call initiated with UUID: {call['uuid']}\")\n# except Exception as e:\n#     print(f\"Error initiating call: {e}\")","lang":"python","description":"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."},"warnings":[{"fix":"Always install `vonage` alongside `vonage-voice` (e.g., `pip install vonage vonage-voice`) and import the `Client` from `vonage` (`from vonage import Client`).","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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.","severity":"breaking","affected_versions":"<1.0.0 (vonage-voice) or <3.0.0 (vonage)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Run `pip install vonage` to install the main Vonage Python SDK.","cause":"You installed `vonage-voice` but forgot to install the main `vonage` SDK, which is a required dependency for the core client.","error":"ModuleNotFoundError: No module named 'vonage'"},{"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`.","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.","error":"AttributeError: 'Voice' object has no attribute 'create_call' or 'Client' object has no attribute 'voice'"},{"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')`.","cause":"When creating an NCCO action like `TalkNcco`, required parameters are missing in its constructor.","error":"TypeError: __init__ missing 1 required positional argument: 'text' (for TalkNcco)"}]}