{"id":9400,"library":"vonage-users","title":"Vonage Users","description":"The `vonage-users` library provides a Pythonic interface to the Vonage Users API, enabling management of users, devices, and associated properties within the Vonage platform. It is built on top of the main `vonage` Python SDK for authentication and HTTP communication. As of version 1.2.1, it requires Python 3.9+ and the `vonage` SDK version 3.x. The release cadence is irregular, typically tied to Vonage API updates.","status":"active","version":"1.2.1","language":"en","source_language":"en","source_url":"https://github.com/Vonage/vonage-users-python","tags":["vonage","api","telecom","users","sdk"],"install":[{"cmd":"pip install vonage-users","lang":"bash","label":"Install vonage-users"}],"dependencies":[{"reason":"Required for authentication and HTTP communication with Vonage APIs.","package":"vonage"}],"imports":[{"symbol":"VonageUsersClient","correct":"from vonage_users import VonageUsersClient"},{"note":"The base Vonage client, required for authentication and underlying HTTP communication.","symbol":"Client","correct":"import vonage"}],"quickstart":{"code":"import vonage\nimport os\nfrom vonage_users import VonageUsersClient\n\n# Initialize Vonage client using environment variables for sensitive data\n# This library requires a vonage.Client instance for its operations.\nvonage_client = vonage.Client(\n    key=os.environ.get('VONAGE_API_KEY', 'YOUR_API_KEY'),\n    secret=os.environ.get('VONAGE_API_SECRET', 'YOUR_API_SECRET'),\n    private_key=os.environ.get('VONAGE_PRIVATE_KEY', 'YOUR_PRIVATE_KEY').replace('\\\\n', '\\n'), # Handle multiline key\n    application_id=os.environ.get('VONAGE_APPLICATION_ID', 'YOUR_APPLICATION_ID')\n)\n\n# Initialize Vonage Users client with the base client\nusers_client = VonageUsersClient(vonage_client)\n\ntry:\n    # Example: List users\n    print(\"\\n--- Listing Users ---\")\n    users = users_client.get_users()\n    if users:\n        for user in users:\n            print(f\"User ID: {user.id}, Name: {user.name}, Display Name: {user.display_name}\")\n    else:\n        print(\"No users found.\")\n\n    # Example: Create a user (requires appropriate permissions and valid data)\n    print(\"\\n--- Creating a Test User ---\")\n    test_user_name = \"my_unique_test_user\"\n    try:\n        new_user = users_client.create_user(\n            name=test_user_name,\n            display_name=\"My Test User\",\n            image_url=\"https://example.com/default.png\",\n            properties={\"custom_tag\": \"dev\"}\n        )\n        print(f\"Successfully created user: ID={new_user.id}, Name={new_user.name}\")\n\n        # Example: Get a user by ID\n        print(f\"\\n--- Retrieving User by ID: {new_user.id} ---\")\n        retrieved_user = users_client.get_user(new_user.id)\n        print(f\"Retrieved user: Name={retrieved_user.name}, Display Name={retrieved_user.display_name}\")\n\n        # Example: Delete the created user (cleanup)\n        print(f\"\\n--- Deleting Test User: {new_user.id} ---\")\n        users_client.delete_user(new_user.id)\n        print(f\"User {new_user.id} deleted successfully.\")\n    except vonage.errors.ClientError as e:\n        if 'name is not unique' in str(e):\n            print(f\"Skipping user creation: User '{test_user_name}' already exists. Error: {e}\")\n        else:\n            print(f\"Error creating/deleting user: {e}\")\n    except Exception as e:\n        print(f\"An unexpected error occurred during user creation/deletion: {e}\")\n\nexcept vonage.errors.ClientError as e:\n    print(f\"Vonage API Error: {e}\")\n    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.\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<1.0.0 (vonage-users) or vonage SDK <3.0.0"},{"fix":"Always initialize `vonage_client = vonage.Client(...)` and then `users_client = VonageUsersClient(vonage_client)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","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-users`.","cause":"The `vonage-users` package has not been installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'vonage_users'"},{"fix":"First, create an authenticated `vonage.Client` instance, then pass it to `VonageUsersClient`. Example: `vonage_client = vonage.Client(...); users_client = VonageUsersClient(vonage_client)`.","cause":"You attempted to initialize `VonageUsersClient` without providing an instance of `vonage.Client`.","error":"TypeError: VonageUsersClient.__init__ missing 1 required positional argument: 'client'"},{"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.","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.","error":"vonage.errors.ClientError: 401 Unauthorized"}]}