{"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":"python","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,"search_vec":"'1.4.0':75 '3.0.0':39 'api':21,47,78 'applic':3,16 'build':14 'call':54 'client':48 'communic':82 'conjunct':31 'contain':43 'control':55 'core':45 'creation':66 'current':72 'design':26 'experi':70 'facilit':51 'function':12 'generat':57 'helper':4,11 'higher':41 'interact':68 'librari':9 'main':34 'ncco':52,80 'nexmo':53 'object':56 'packag':50 'provid':10 'python':23,36 'relat':62 'sdk':37 'simplifi':64 'telephoni':77 'use':29 'util':63 'version':38,73 'voic':2,8,15,20,46,61,69,76 'voice-rel':60 'vonag':1,7,19,35,79 'vonage-voic':6 'webhook':81","created_at":"2026-04-16T18:50:02.029482+00:00","updated_at":"2026-04-16T18:50:02.029482+00:00","problems":{"verify_error":"error: Failed to parse: `vonage-voice vonage`\n  Caused by: Expected one of `@`, `(`, `<`, `=`, `>`, `~`, `!`, `;`, found `v`\nvonage-voice vonage\n             ^"},"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.5.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://www.vonage.com","github":"https://github.com/Vonage/vonage-python-sdk","docs":null,"changelog":null,"pypi":"https://pypi.org/project/vonage-voice/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["communication","http-networking"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"install_fail","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-05","install_tag":null}}