Vonage

4.7.2 · active · verified Sun Mar 01

Official Python SDK for Vonage APIs (formerly Nexmo) — SMS, Voice, WhatsApp, Verify, Video. v4.0 (2023) is a complete architectural rewrite from v3. Old nexmo package and old vonage v3 patterns are entirely broken in v4. Now a monorepo: top-level vonage package plus separate vonage_sms, vonage_voice, vonage_verify etc. packages installed as dependencies. All responses are Pydantic models.

Warnings

breaking v4.0 is a complete rewrite. vonage.Client() does not exist in v4. All v3 code (client.send_message(), client.get_balance(), etc.) raises AttributeError. All tutorials and LLM-generated code using v3 patterns are broken.
Fix: Migrate to v4: from vonage import Vonage, Auth; client = Vonage(auth=Auth(...)). Import API-specific models from vonage_sms, vonage_voice, etc.
breaking nexmo PyPI package reached EOL October 2021, frozen at v7.2.0. 'import nexmo' still installs and runs but receives no updates. All new code must use 'vonage' package.
Fix: pip uninstall nexmo && pip install vonage. Update all imports from nexmo to vonage.
gotcha SMS and basic APIs use API key + secret auth. Voice, Video, and Messages APIs require JWT auth (application_id + private_key). Using API key/secret for JWT-only endpoints returns 401.
Fix: For Voice/Video: Auth(application_id='APP_ID', private_key='/path/to/private.key'). For SMS: Auth(api_key='KEY', api_secret='SECRET').
gotcha v4 responses are Pydantic models, not dicts. Code accessing response['message-id'] or response.get('messages') fails with TypeError. Use attribute access or .model_dump().
Fix: Use response.model_dump_json(exclude_unset=True) for serialization, or access fields as attributes.
gotcha API-specific models (SmsMessage, ListCallsFilter, etc.) must be imported from their sub-packages (vonage_sms, vonage_voice), not from vonage directly.
Fix: from vonage_sms import SmsMessage (not from vonage import SmsMessage)

Install

pip install vonage Python (installs vonage + all sub-packages)

Imports

Vonage (v4)

from vonage import Vonage, Auth
from vonage_sms import SmsMessage

auth = Auth(api_key='YOUR_KEY', api_secret='YOUR_SECRET')
client = Vonage(auth=auth)

message = SmsMessage(to='1234567890', from_='Vonage', text='Hello')
response = client.sms.send(message)

v3 Client() pattern is completely removed in v4. vonage.Client does not exist. All v3 tutorials are broken.

nexmo (old package)
```
# Install vonage instead
pip install vonage
```
The nexmo PyPI package is frozen at v7.2.0 (EOL October 2021). All new code must use the vonage package.

Quickstart

SMS uses API key/secret auth. Voice and Video require JWT auth via application_id + private_key. Responses are Pydantic models — use .model_dump_json() or access attributes directly.

import os
from vonage import Vonage, Auth
from vonage_sms import SmsMessage

auth = Auth(
    api_key=os.environ['VONAGE_API_KEY'],
    api_secret=os.environ['VONAGE_API_SECRET']
)
client = Vonage(auth=auth)

message = SmsMessage(
    to='15551234567',
    from_='Vonage',
    text='Hello from Vonage!'
)

response = client.sms.send(message)
print(response.model_dump_json(exclude_unset=True))

# For Voice/JWT auth, use:
# auth = Auth(application_id='APP_ID', private_key='path/to/private.key')

view raw JSON →