repository·main·Indexed 42 days ago
https://github.com/vonage/vonage-python-sdkA comprehensive server-side library for integrating Vonage APIs, including SMS, Voice, Video, and Messages, into Python applications. The SDK provides a central client for API access and specialized packages for account management, application configuration, JWT generation via JwtClient, and Identity Insights. It includes the vonage-http-client for authenticated requests and supports multiple messaging channels such as WhatsApp, RCS, Messenger, and Viber.
The vonage_verify_legacy package provides methods for interacting with Vonage's legacy Verify API, specifically for 2-factor authentication (2FA) via SMS or TTS.
Note: This is a legacy package. For most modern use cases, it is recommended to use the current Vonage Verify API, which supports additional channels like Email, WhatsApp, and Messenger, as well as Silent Authentication.
vonage package. All operations are performed through a vonage.Vonage client instance (e.g., vonage_client).The account package provides methods for managing Vonage accounts, including querying account balances, performing top-ups, checking service pricing, managing account settings (like SMS webhooks), and handling account secrets.
It is recommended to use this package as part of the main vonage package. The following examples assume you have already instantiated the main client as vonage_client.
The vonage_video module provides methods for managing video sessions, streams, signals, and advanced features like archiving, broadcasting, and SIP calls.
It is recommended to use this module as part of the main vonage package. Most API calls require an instance of the vonage.Vonage class (referred to here as vonage_client). The API uses custom Pydantic data models for request parameters to ensure type safety and validation.
import vonage
# Assuming you have initialized your client
vonage_client = vonage.Vonage(api_key='...', api_secret='...')
# Access video features via the .video property
# vonage_client.video.<method_name>(...)The Vonage Number Insight package allows you to retrieve information about phone numbers using three levels of insight: basic, standard, and advanced.
cnam parameter to True (note: this incurs an additional charge).Asynchronous Advanced Insight is recommended to avoid timeouts. In an asynchronous request, the API returns basic request information immediately and sends the full dataset to a specified callback webhook URL.
It is recommended to use this package as part of the main vonage package. The following examples assume you have already instantiated the vonage.Vonage class as vonage_client.
API methods are accessed as named attributes on the vonage.Vonage instance. For example, to use the Video API, use vonage_client.video.method_name().
Data models and errors are not accessed through the main vonage package. Instead, they are imported from their specific API packages:
from vonage_verify import VerifyRequest).vonage-messages, vonage-voice, or vonage-video), import from the .models submodule (e.g., from vonage_messages.models import MessengerImage).# Example: Using Verify API
from vonage_verify import VerifyRequest, SmsChannel
sms_channel = SmsChannel(to='1234567890')
verify_request = VerifyRequest(brand='Vonage', workflow=[sms_channel])
# Accessing the method via the client
response = vonage_client.verify.start_verification(verify_request)VonageError, you will encounter specific error types like RateLimitedError (for HTTP 429). Error objects include a .response attribute to access the underlying HTTP response details.asyncio. All methods are synchronous.VonageError type is the base exception class for all exceptions related to the Vonage SDK. You can access it directly from the vonage_utils package or via the main SDK module using vonage.VonageError to implement robust error handling for your integration.The Vonage Python SDK is organized as a monorepo. While the top-level vonage package provides access to most API methods, specialized data models and request/response objects are located in specific API packages (e.g., vonage-sms, vonage-account).
To use an API, you typically use the vonage.Vonage client instance for the method call, but import the specific message or request objects from their corresponding sub-package.
Example: Sending an SMS
vonage to access the .sms.send() method.vonage_sms to import SmsMessage and SmsResponse.from vonage_sms import SmsMessage, SmsResponse
# message is created using the specialized package
message = SmsMessage(to='1234567890', from_='Acme Inc.', text='Hello, World!')
# the call is made via the top-level vonage client
response: SmsResponse = vonage_client.sms.send(message) # vonage_client is an instance of `vonage.Vonage`The HttpClientOptions class allows you to customize the behavior of the HTTP client. You can configure:
api_host: The API host.rest_host: The REST host.timeout: Request timeout.pool_connections: Connection pool settings.pool_max_size: Maximum pool size.max_retries: Maximum number of retries.The Vonage Number Verification API uses OAuth2 authentication to verify a mobile device's phone number without user input. The process consists of three stages:
This package provides helper methods for stages 1 and 3.