Vonage Numbers

1.0.5 · active · verified Thu Apr 16

The `vonage-numbers` library provides a dedicated Python client for interacting with the Vonage Numbers API. It allows developers to programmatically manage their Vonage phone numbers, including searching, buying, updating, and canceling them. It is built on top of the `vonage-python` SDK and is currently at version 1.0.5, with updates tied to the underlying Vonage API and SDK changes.

Common errors

```
ModuleNotFoundError: No module named 'vonage'
```
cause The core `vonage-python` SDK, which `vonage-numbers` depends on for client initialization and API interaction, is not installed.

fix Install the `vonage-python` SDK: `pip install vonage-python`
```
TypeError: Numbers.__init__() missing 1 required positional argument: 'client'
```
cause You attempted to instantiate the `vonage_numbers.Numbers` client without providing an initialized `vonage.Client` instance.

fix First, create an authenticated `vonage.Client` instance, then pass it to `Numbers`: `client = vonage.Client(key='...', secret='...'); numbers_client = Numbers(client)`
```
vonage.exceptions.VonageClientException: You need to supply a key and secret to the Vonage client
```
cause The `vonage.Client` was initialized without valid API key and secret, or the provided credentials were incorrect.

fix Ensure `VONAGE_API_KEY` and `VONAGE_API_SECRET` environment variables are set correctly, or pass your valid API key and secret directly as arguments to `vonage.Client(key='YOUR_API_KEY', secret='YOUR_API_SECRET')`.

Warnings

gotcha The `vonage-numbers` library is a thin wrapper around the `vonage-python` SDK. You must install `vonage-python` separately for `vonage-numbers` to function correctly.
Fix: Ensure both `vonage-numbers` and `vonage-python` are installed: `pip install vonage-numbers vonage-python`
gotcha The `vonage_numbers.Numbers` client requires an initialized `vonage.Client` instance to be passed to its constructor. Directly instantiating `Numbers()` without the client will result in a `TypeError`.
Fix: First create `client = vonage.Client(key='YOUR_KEY', secret='YOUR_SECRET')`, then `numbers_client = Numbers(client)`.
breaking While `vonage-numbers` itself is stable, underlying changes to the Vonage Numbers API can lead to unexpected request/response formats or deprecated endpoints. Keep an eye on official Vonage API documentation.
Fix: Regularly consult the official Vonage Developer Documentation for the Numbers API to stay updated on schema changes or deprecated features.

Install

pip install vonage-numbers Install vonage-numbers

Imports

Numbers
```
from vonage_numbers import Numbers
```
Client
```
import vonage
```
The core Vonage client (for authentication) is imported from the parent `vonage-python` SDK and then passed to the `vonage-numbers` client.

Quickstart

Initialize the core `vonage.Client` with API credentials, then use it to instantiate the `vonage_numbers.Numbers` client to perform operations like fetching all owned numbers. Ensure `VONAGE_API_KEY` and `VONAGE_API_SECRET` environment variables are set.

import vonage
from vonage_numbers import Numbers
import os

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 VONAGE_API_KEY == "YOUR_API_KEY" or VONAGE_API_SECRET == "YOUR_API_SECRET":
    print("Please set VONAGE_API_KEY and VONAGE_API_SECRET environment variables or replace placeholders.")
else:
    try:
        # Initialize Vonage client
        client = vonage.Client(key=VONAGE_API_KEY, secret=VONAGE_API_SECRET)

        # Initialize Numbers client
        numbers_client = Numbers(client)

        # Example: get all numbers
        print("Fetching all Vonage numbers...")
        all_numbers = numbers_client.get_all_numbers()
        if all_numbers and all_numbers.get('numbers'):
            print(f"Successfully retrieved {len(all_numbers['numbers'])} numbers.")
            for number_data in all_numbers['numbers'][:2]: # Print first 2 for brevity
                print(f"- Number: {number_data.get('msisdn')}, Country: {number_data.get('country')}")
        else:
            print("No numbers found or response was empty.")

    except vonage.exceptions.VonageClientException as e:
        print(f"Vonage API Error: {e}")
    except Exception as e:
        print(f"An unexpected error occurred: {e}")

view raw JSON →