Vonage Messages API Python Client

Common errors

• AttributeError: 'Client' object has no attribute 'messages'

  cause The `vonage-messages` package, which adds the `.messages` attribute to the `vonage.Client`, has not been installed.
  fix Install the `vonage-messages` package: `pip install vonage-messages`.

• ModuleNotFoundError: No module named 'vonage'

  cause The core `vonage` Python SDK, which is a required dependency for `vonage-messages`, is not installed.
  fix Install the `vonage` package: `pip install vonage`.

• from nexmo import Client

  cause Attempting to use an old import path from the deprecated `nexmo-python` SDK instead of the current `vonage-python-sdk`.
  fix Update your import statement to `from vonage import Client` and refactor subsequent API calls according to the `vonage` SDK documentation.

• vonage.errors.VonageError: HTTP error: 401 Client Error: Unauthorized for url: ...

  cause Invalid or missing Vonage API Key or API Secret used for authentication.
  fix Verify that your `VONAGE_API_KEY` and `VONAGE_API_SECRET` are correctly set in your environment variables or passed to the `Client` constructor, and that they are valid for your Vonage account.

Warnings

• gotcha The `vonage-messages` package is an extension and requires the core `vonage` package to be installed alongside it. Without `vonage`, you will encounter import errors or `AttributeError`.
  Fix: Ensure both `pip install vonage` and `pip install vonage-messages` are executed in your environment.
• breaking This library is designed for the modern Vonage Messages API, which handles SMS, MMS, and WhatsApp via a unified endpoint. It does not directly support the older, legacy Vonage (formerly Nexmo) SMS API. If you need the legacy SMS API, refer to the `vonage.Sms` client.
  Fix: Review the Vonage API documentation to determine if you need the Messages API or the legacy SMS API. For the Messages API, use `client.messages.send()`. For legacy SMS, use `client.sms.send_message()`.
• breaking Users migrating from the deprecated `nexmo-python` SDK to `vonage-python-sdk` will encounter significant breaking changes, including package renames (`nexmo` to `vonage`), module paths, and method signatures.
  Fix: Thoroughly review the official Vonage Python SDK migration guide. Update all imports from `nexmo` to `vonage` and adapt API calls to the new `vonage.Client` structure, especially for authentication and message sending.
• gotcha For convenience, the `vonage.Client` can automatically pick up `VONAGE_API_KEY` and `VONAGE_API_SECRET` from environment variables. If you pass empty strings or incorrect values, authentication will fail silently until an API call is made.
  Fix: Always verify your `VONAGE_API_KEY` and `VONAGE_API_SECRET` are correctly set as environment variables or explicitly passed to the `Client` constructor with valid credentials. Handle potential `VonageError` exceptions.

Install

• pip install vonage-messages Install vonage-messages
• pip install vonage Install core Vonage SDK (required)

Imports

• Client
  wrong:

  from vonage_messages import Client

  correct:

  from vonage import Client

  The `vonage-messages` package extends the `vonage.Client` object with the `.messages` attribute; it is not meant for direct import.

Quickstart

This quickstart demonstrates sending an SMS message using the Vonage Messages API. It initializes the `vonage.Client` (which is extended by `vonage-messages`) and then uses the `client.messages.send` method. Remember to replace placeholder numbers and either set API key/secret as environment variables or directly in the code.

import os
from vonage import Client

VONAGE_API_KEY = os.environ.get('VONAGE_API_KEY', 'YOUR_API_KEY')
VONAGE_API_SECRET = os.environ.get('VONAGE_API_SECRET', 'YOUR_API_SECRET')

if not VONAGE_API_KEY or not VONAGE_API_SECRET:
    print("Please set VONAGE_API_KEY and VONAGE_API_SECRET environment variables or replace placeholders.")
else:
    client = Client(key=VONAGE_API_KEY, secret=VONAGE_API_SECRET)

    try:
        response_data = client.messages.send(
            {
                "channel": "sms",
                "to": "YOUR_RECIPIENT_NUMBER", # e.g., "447900000000"
                "from": "VONAGE_NUMBER",       # Your Vonage virtual number
                "text": "Hello from Vonage Python SDK!"
            }
        )

        if response_data["messages"][0]["status"] == "0":
            print("Message sent successfully.")
        else:
            print(f"Message failed with error: {response_data['messages'][0]['error_text']}")

    except Exception as e:
        print(f"An error occurred: {e}")