Vonage Users

Common errors

• ModuleNotFoundError: No module named 'vonage_users'

  cause The `vonage-users` package has not been installed in the current Python environment.
  fix Run `pip install vonage-users`.

• TypeError: VonageUsersClient.__init__ missing 1 required positional argument: 'client'

  cause You attempted to initialize `VonageUsersClient` without providing an instance of `vonage.Client`.
  fix First, create an authenticated `vonage.Client` instance, then pass it to `VonageUsersClient`. Example: `vonage_client = vonage.Client(...); users_client = VonageUsersClient(vonage_client)`.

• vonage.errors.ClientError: 401 Unauthorized

  cause The API credentials (key, secret, private key, application ID) provided to the `vonage.Client` are incorrect, incomplete, or lack the necessary permissions for the requested operation.
  fix Double-check your `VONAGE_API_KEY`, `VONAGE_API_SECRET`, `VONAGE_PRIVATE_KEY`, and `VONAGE_APPLICATION_ID` (if using JWT auth) in your environment variables or direct code. Ensure the associated Vonage application has the required permissions for User API operations.

Warnings

• breaking The `vonage-users` library explicitly requires the `vonage` SDK version 3.x (e.g., `>=3.0.0,<4.0.0`). Installing an older major version of the `vonage` SDK (e.g., v2.x) will lead to dependency conflicts or runtime errors due to incompatible client interfaces.
  Fix: Ensure you have `vonage` version 3.x installed. If issues persist, try `pip install 'vonage>=3.0.0,<4.0.0' vonage-users --upgrade` or create a clean virtual environment.
• gotcha Authentication for `vonage-users` is handled by an instance of the main `vonage.Client`. You must first initialize the `vonage.Client` with your API credentials (key, secret, private key, application ID) and then pass that instance to the `VonageUsersClient` constructor.
  Fix: Always initialize `vonage_client = vonage.Client(...)` and then `users_client = VonageUsersClient(vonage_client)`.
• gotcha When creating or updating users, ensuring the `name` field is unique across all users is critical. The API will return an error if a non-unique name is provided, which can be challenging to debug without proper error handling.
  Fix: Implement robust error handling (`try...except vonage.errors.ClientError`) around user creation/update calls and consider adding a unique identifier (e.g., UUID) or timestamp to user names if conflicts are common.

Install

• pip install vonage-users Install vonage-users

Imports

• VonageUsersClient

  from vonage_users import VonageUsersClient

• Client

  import vonage

  The base Vonage client, required for authentication and underlying HTTP communication.

Quickstart

This quickstart demonstrates how to initialize the `VonageUsersClient`, list existing users, create a new user, retrieve a user by ID, and then delete that user for cleanup. It uses environment variables for secure API key management and includes basic error handling for Vonage API specific errors. Ensure your Vonage API keys and application ID are set as environment variables or replaced directly in the code for testing.

import vonage
import os
from vonage_users import VonageUsersClient

# Initialize Vonage client using environment variables for sensitive data
# This library requires a vonage.Client instance for its operations.
vonage_client = vonage.Client(
    key=os.environ.get('VONAGE_API_KEY', 'YOUR_API_KEY'),
    secret=os.environ.get('VONAGE_API_SECRET', 'YOUR_API_SECRET'),
    private_key=os.environ.get('VONAGE_PRIVATE_KEY', 'YOUR_PRIVATE_KEY').replace('\\n', '\n'), # Handle multiline key
    application_id=os.environ.get('VONAGE_APPLICATION_ID', 'YOUR_APPLICATION_ID')
)

# Initialize Vonage Users client with the base client
users_client = VonageUsersClient(vonage_client)

try:
    # Example: List users
    print("\n--- Listing Users ---")
    users = users_client.get_users()
    if users:
        for user in users:
            print(f"User ID: {user.id}, Name: {user.name}, Display Name: {user.display_name}")
    else:
        print("No users found.")

    # Example: Create a user (requires appropriate permissions and valid data)
    print("\n--- Creating a Test User ---")
    test_user_name = "my_unique_test_user"
    try:
        new_user = users_client.create_user(
            name=test_user_name,
            display_name="My Test User",
            image_url="https://example.com/default.png",
            properties={"custom_tag": "dev"}
        )
        print(f"Successfully created user: ID={new_user.id}, Name={new_user.name}")

        # Example: Get a user by ID
        print(f"\n--- Retrieving User by ID: {new_user.id} ---")
        retrieved_user = users_client.get_user(new_user.id)
        print(f"Retrieved user: Name={retrieved_user.name}, Display Name={retrieved_user.display_name}")

        # Example: Delete the created user (cleanup)
        print(f"\n--- Deleting Test User: {new_user.id} ---")
        users_client.delete_user(new_user.id)
        print(f"User {new_user.id} deleted successfully.")
    except vonage.errors.ClientError as e:
        if 'name is not unique' in str(e):
            print(f"Skipping user creation: User '{test_user_name}' already exists. Error: {e}")
        else:
            print(f"Error creating/deleting user: {e}")
    except Exception as e:
        print(f"An unexpected error occurred during user creation/deletion: {e}")

except vonage.errors.ClientError as e:
    print(f"Vonage API Error: {e}")
    print("Please ensure your VONAGE_API_KEY, VONAGE_API_SECRET, VONAGE_PRIVATE_KEY, and VONAGE_APPLICATION_ID are correctly set and have the necessary permissions.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")