This is the Python server SDK to help you use Vonage APIs in your Python application. To use it you'll need a Vonage account. Sign up for free on the Vonage site.
- Installation
- Migration Guides
- Calling Vonage APIs
- Usage
- Account API
- Application API
- HTTP Client
- JWT Client
- Messages API
- Network Number Verification API
- Network Sim Swap API
- Number Insight API
- Numbers API
- SMS API
- Subaccounts API
- Users API
- Verify API
- Verify API (Legacy)
- Video API
- Voice API
- Vonage Utils Package
- Frequently Asked Questions
- Contributing
- License
- Additional Resources
It's recommended to create a new virtual environment to install the SDK. You can do this with
# Create the virtual environment
python3 -m venv venv
# Activate the virtual environment in Mac/Linux
. ./venv/bin/activate
# Or on Windows Command Prompt
venv\Scripts\activateTo install the Python SDK package using pip:
pip install vonageTo upgrade your installed client library using pip:
pip install vonage --upgradeAlternatively, you can clone the repository via the command line, or by opening it on GitHub desktop.
This version of the Vonage Python SDK (4.x+) works very differently to the previous SDK. See the v3 -> v4 migration guide for help migrating your application code using v3 of the SDK to the new structure.
This SDK includes support for the Vonage Video API. If you have an application that uses OpenTok for video and want to migrate (which is highly recommended!) then A migration guide is available here which will help you to migrate your applications to use Vonage Video.
The Vonage Python SDK is a monorepo, with separate packages for each API. When you install the Python SDK, you'll see there's a top-level package, vonage, and then specialised packages for every API class.
Most methods to call Vonage APIs are accessed through the top-level vonage package. Many require specific custom data models accessed though the specific Vonage package corresponding to the API you're trying to use.
For example, to send an SMS, you will access the SMS method from vonage and the SmsMessage object from the vonage-sms package. This looks something like this:
from vonage_sms import SmsMessage, SmsResponse
message = SmsMessage(to='1234567890', from_='Acme Inc.', text='Hello, World!')
response: SmsResponse = vonage_client.sms.send(message) # vonage_client is an instance of `vonage.Vonage`
print(response.model_dump(exclude_unset=True))Many of the use cases require you to buy a Vonage Number, which you can do in the Vonage Developer Dashboard.
from vonage import Vonage, Auth, HttpClientOptions
# Create an Auth instance
auth = Auth(api_key='your_api_key', api_secret='your_api_secret')
# Create HttpClientOptions instance
# (not required unless you want to change options from the defaults)
options = HttpClientOptions(api_host='api.nexmo.com', timeout=30)
# Create a Vonage instance
vonage = Vonage(auth=auth, http_client_options=options)The Vonage class provides access to various Vonage APIs through its properties. For example, to use methods to call the SMS API:
from vonage_sms import SmsMessage
message = SmsMessage(to='1234567890', from_='Vonage', text='Hello World')
response = client.sms.send(message)
print(response.model_dump_json(exclude_unset=True))You can also access the underlying HttpClient instance through the http_client property:
user_agent = vonage.http_client.user_agentMost responses to API calls in the SDK are Pydantic models. To convert a Pydantic model to a dict, use model.model_dump. To convert to a JSON string, use model.model_dump_json
response = vonage.api_package.api_call(...)
response_dict = response.model_dump()
response_json = response.model_dump_json()balance = vonage_client.account.get_balance()
print(balance)response = vonage_client.account.top_up(trx='1234567890')
print(response)This will return a Pydantic object (SettingsResponse) containing multiple settings for your account.
settings: SettingsResponse = vonage_client.account.update_default_sms_webhook(
mo_callback_url='https://example.com/inbound_sms_webhook',
dr_callback_url='https://example.com/delivery_receipt_webhook',
)
print(settings)from vonage_account import GetCountryPricingRequest
response = vonage_client.account.get_country_pricing(
GetCountryPricingRequest(type='sms', country_code='US')
)
print(response)response = vonage_client.account.get_all_countries_pricing(service_type='sms')
print(response)from vonage_account import GetPrefixPricingRequest
response = client.account.get_prefix_pricing(
GetPrefixPricingRequest(prefix='44', type='sms')
)
print(response)response = vonage_client.account.list_secrets()
print(response)secret = vonage_client.account.create_secret('Mytestsecret12345')
print(secret)secret = vonage_client.account.get_secret(MY_SECRET_ID)
print(secret)Note: it isn't possible to revoke all account secrets, there must always be one valid secret. Attempting to do so will give a 403 error.
client.account.revoke_secret(MY_SECRET_ID)With no custom options specified, this method will get the first 100 applications. It returns a tuple consisting of a list of ApplicationData objects and an int showing the page number of the next page of results.
from vonage_application import ListApplicationsFilter, ApplicationData
applications, next_page = vonage_client.application.list_applications()
# With options
options = ListApplicationsFilter(page_size=3, page=2)
applications, next_page = vonage_client.application.list_applications(options)from vonage_application import ApplicationConfig
app_data = vonage_client.application.create_application()
# Create with custom options (can also be done with a dict)
from vonage_application import ApplicationConfig, Keys, Voice, VoiceWebhooks
voice = Voice(
webhooks=VoiceWebhooks(
event_url=VoiceUrl(
address='https://example.com/event',
http_method='POST',
connect_timeout=500,
socket_timeout=3000,
),
),
signed_callbacks=True,
)
capabilities = Capabilities(voice=voice)
keys = Keys(public_key='MY_PUBLIC_KEY')
config = ApplicationConfig(
name='My Customised Application',
capabilities=capabilities,
keys=keys,
)
app_data = vonage_client.application.create_application(config)app_data = client.application.get_application('MY_APP_ID')
app_data_as_dict = app.model_dump(exclude_none=True)To update an application, pass config for the updated field(s) in an ApplicationConfig object
from vonage_application import ApplicationConfig, Keys, Voice, VoiceWebhooks
config = ApplicationConfig(name='My Updated Application')
app_data = vonage_client.application.update_application('MY_APP_ID', config)vonage_client.applications.delete_application('MY_APP_ID')from vonage_http_client import HttpClient, HttpClientOptions
from vonage_http_client.auth import Auth
# Create an Auth instance
auth = Auth(api_key='your_api_key', api_secret='your_api_secret')
# Create HttpClientOptions instance
options = HttpClientOptions(api_host='api.nexmo.com', timeout=30)
# Create a HttpClient instance
client = HttpClient(auth=auth, http_client_options=options)
# Make a GET request
response = client.get(host='api.nexmo.com', request_path='/v1/messages')
# Make a POST request
response = client.post(host='api.nexmo.com', request_path='/v1/messages', params={'key': 'value'})The HttpClient class exposes two properties, last_request and last_response that cache the last sent request and response.
# Get last request, has type requests.PreparedRequest
request = client.last_request
# Get last response, has type requests.Response
response = client.last_responseThe HttpClient class also supports appending additional information to the User-Agent header via the append_to_user_agent method:
client.append_to_user_agent('additional_info')The HttpClient class automatically handles JWT and basic authentication based on the Auth instance provided. It uses JWT authentication by default, but you can specify the authentication type when making a request:
# Use basic authentication for this request
response = client.get(host='api.nexmo.com', request_path='/v1/messages', auth_type='basic')Error objects are exposed in the package scope, so you can catch errors like this:
from vonage_http_client import HttpRequestError
try:
client.post(...)
except HttpRequestError:
...This JWT Generator can be used implicitly, just by using the Vonage Python SDK to make JWT-authenticated API calls.
It can also be used as a standalone JWT generator for use with Vonage APIs, like so:
from vonage_jwt import JwtClientjwt_client = JwtClient(application_id, private_key)jwt_client.generate_application_jwt()Optional JWT claims can be provided in a python dictionary:
claims = {'jti': 'asdfzxcv1234', 'nbf': now + 100}
jwt_client.generate_application_jwt(claims)You can use the verify_jwt.verify_signature method to verify a JWT signature is valid.
from vonage_jwt import verify_signature
verify_signature(TOKEN, SIGNATURE_SECRET) # Returns a booleanIn order to send a message, you must construct a message object of the correct type. These are all found under vonage_messages.models.
from vonage_messages.models import Sms
message = Sms(
from_='Vonage APIs',
to='1234567890',
text='This is a test message sent from the Vonage Python SDK',
)This message can now be sent with
vonage_client.messages.send(message)All possible message types from every message channel have their own message model. They are named following this rule: {Channel}{MessageType}, e.g. Sms, MmsImage, RcsFile, MessengerAudio, WhatsappSticker, ViberVideo, etc.
The different message models are listed at the bottom of the page.
Some message types have submodels with additional fields. In this case, import the submodels as well and use them to construct the overall options.
e.g.
from vonage_messages.models import MessengerImage, MessengerOptions, MessengerResource
messenger = MessengerImage(
to='1234567890',
from_='1234567890',
image=MessengerResource(url='https://example.com/image.jpg'),
messenger=MessengerOptions(category='message_tag', tag='invalid_tag'),
)To send a message, access the Messages.send method via the main Vonage object, passing in an instance of a subclass of BaseMessage like this:
from vonage import Auth, Vonage
from vonage_messages.models import Sms
vonage_client = Vonage(Auth(application_id='my-application-id', private_key='my-private-key'))
message = Sms(
from_='Vonage APIs',
to='1234567890',
text='This is a test message sent from the Vonage Python SDK',
)
vonage_client.messages.send(message)Note: to use this method, update the api_host attribute of the vonage_http_client.HttpClientOptions object to the API endpoint corresponding to the region where the WhatsApp number is hosted.
For example, to use the EU API endpoint, set the api_host attribute to 'api-eu.vonage.com'.
from vonage import Vonage, Auth, HttpClientOptions
auth = Auth(application_id='MY-APP-ID', private_key='MY-PRIVATE-KEY')
options = HttpClientOptions(api_host='api-eu.vonage.com')
vonage_client = Vonage(auth, options)
vonage_client.messages.mark_whatsapp_message_read('MESSAGE_UUID')Note: as above, to use this method you need to update the api_host attribute of the vonage_http_client.HttpClientOptions object to the API endpoint corresponding to the region where the WhatsApp number is hosted.
For example, to use the EU API endpoint, set the api_host attribute to 'api-eu.vonage.com'.
from vonage import Vonage, Auth, HttpClientOptions
auth = Auth(application_id='MY-APP-ID', private_key='MY-PRIVATE-KEY')
options = HttpClientOptions(api_host='api-eu.vonage.com')
vonage_client = Vonage(auth, options)
vonage_client.messages.revoke_rcs_message('MESSAGE_UUID')To send a message, instantiate a message model of the correct type as described above. This is a list of message models that can be used:
Sms
MmsImage, MmsVcard, MmsAudio, MmsVideo
RcsText, RcsImage, RcsVideo, RcsFile, RcsCustom
WhatsappText, WhatsappImage, WhatsappAudio, WhatsappVideo, WhatsappFile, WhatsappTemplate, WhatsappSticker, WhatsappCustom
MessengerText, MessengerImage, MessengerAudio, MessengerVideo, MessengerFile
ViberText, ViberImage, ViberVideo, ViberFile
The Vonage Number Verification API uses Oauth2 authentication, which this SDK will also help you to do. Verifying a number has 3 stages:
- Get an OIDC URL for use in your front-end application
- Use this URL in your own application to get an authorization code
- Make a Number Verification Request using this code to verify the number
This package contains methods to help with Steps 1 and 3.
from vonage_network_number_verification import CreateOidcUrl
url_options = CreateOidcUrl(
redirect_uri='https://example.com/redirect',
state='c9896ee6-4ff8-464c-b393-d56d6e638f88',
login_hint='+990123456',
)
url = number_verification.get_oidc_url(url_options)
print(url)Get your user's device to follow this URL and a code to use for number verification will be returned in the final redirect query parameters. Note: your user must be connected to their mobile network.
from vonage_network_number_verification import NumberVerificationRequest
response = number_verification.verify(
NumberVerificationRequest(
code='code',
redirect_uri='https://example.com/redirect',
phone_number='+990123456',
)
)
print(response.device_phone_number_verified)from vonage_network_sim_swap import SwapStatus
swap_status: SwapStatus = vonage_client.sim_swap.check(phone_number='MY_NUMBER')
print(swap_status.swapped)from vonage_network_sim_swap import LastSwapDate
swap_date: LastSwapDate = vonage_client.sim_swap.get_last_swap_date
print(swap_date.last_swap_date)from vonage_number_insight import BasicInsightRequest
response = vonage_client.number_insight.basic_number_insight(
BasicInsightRequest(number='12345678900')
)
print(response.model_dump(exclude_none=True))from vonage_number_insight import StandardInsightRequest
vonage_client.number_insight.standard_number_insight(
StandardInsightRequest(number='12345678900')
)
# Optionally, you can get caller name information (additional charge) by setting the `cnam` parameter = True
vonage_client.number_insight.standard_number_insight(
StandardInsightRequest(number='12345678900', cnam=True)
)When making an asynchronous advanced number insight request, the API will return basic information about the request to you immediately and send the full data to the webhook callback URL you specify.
from vonage_number_insight import AdvancedAsyncInsightRequest
vonage_client.number_insight.advanced_async_number_insight(
AdvancedAsyncInsightRequest(callback='https://example.com', number='12345678900')
)from vonage_number_insight import AdvancedSyncInsightRequest
vonage_client.number_insight.advanced_sync_number_insight(
AdvancedSyncInsightRequest(number='12345678900')
)numbers, count, next_page = vonage_client.numbers.list_owned_numbers()
print(numbers)
print(count)
print(next_page)
# With filtering
from vonage_numbers import ListOwnedNumbersFilter
numbers, count, next_page = vonage_client.numbers.list_owned_numbers(
ListOwnedNumbersFilter(country='GB', size=3, index=2)
)
numbers, count, next_page_index = vonage_client.numbers.list_owned_numbers()
print(numbers)
print(count)
print(next_page_index)from vonage_numbers import SearchAvailableNumbersFilter
numbers, count, next_page_index = vonage_client.numbers.search_available_numbers(
SearchAvailableNumbersFilter(
country='GB', size=10, pattern='44701', search_pattern=1
)
)
print(numbers)
print(count)
print(next_page_index)from vonage_numbers import NumberParams
status = vonage_client.numbers.buy_number(NumberParams(country='GB', msisdn='447007000000'))
print(status)from vonage_numbers import NumberParams
status = vonage_client.numbers.cancel_number(NumberParams(country='GB', msisdn='447007000000'))
print(status)from vonage_numbers import UpdateNumberParams
status = vonage_client.numbers.update_number(
UpdateNumberParams(
country='GB',
msisdn='447007000000',
mo_http_url='https://example.com',
mo_smpp_sytem_type='inbound',
voice_callback_type='tel',
voice_callback_value='447008000000',
voice_status_callback='https://example.com',
)
)
print(status)Create an SmsMessage object, then pass into the Sms.send method.
from vonage_sms import SmsMessage, SmsResponse
message = SmsMessage(to='1234567890', from_='Acme Inc.', text='Hello, World!')
response: SmsResponse = vonage_client.sms.send(message)
print(response.model_dump(exclude_unset=True))response = vonage_client.subaccounts.list_subaccounts()
print(response.model_dump)from vonage_subaccounts import SubaccountOptions
response = vonage_client.subaccounts.create_subaccount(
SubaccountOptions(
name='test_subaccount', secret='1234asdfA', use_primary_account_balance=False
)
)
print(response)from vonage_subaccounts import ModifySubaccountOptions
response = vonage_client.subaccounts.modify_subaccount(
'test_subaccount',
ModifySubaccountOptions(
suspended=True,
name='modified_test_subaccount',
),
)
print(response)from vonage_subaccounts import ListTransfersFilter
filter = {'start_date': '2023-08-07T10:50:44Z'}
response = vonage_client.subaccounts.list_balance_transfers(ListTransfersFilter(**filter))
for item in response:
print(item.model_dump())from vonage_subaccounts import TransferRequest
request = TransferRequest(
from_='test_api_key', to='test_subaccount', amount=0.02, reference='A reference'
)
response = vonage_client.subaccounts.transfer_balance(request)
print(response)from vonage_subaccounts import ListTransfersFilter
filter = {'start_date': '2023-08-07T10:50:44Z'}
response = vonage_client.subaccounts.list_credit_transfers(ListTransfersFilter(**filter))
for item in response:
print(item.model_dump())from vonage_subaccounts import TransferRequest
request = TransferRequest(
from_='test_api_key', to='test_subaccount', amount=0.02, reference='A reference'
)
response = vonage_client.subaccounts.transfer_balance(request)
print(response)from vonage_subaccounts import TransferNumberRequest
request = TransferNumberRequest(
from_='test_api_key', to='test_subaccount', number='447700900000', country='GB'
)
response = vonage_client.subaccounts.transfer_number(request)
print(response)With no custom options specified, this method will get the last 100 users. It returns a tuple consisting of a list of UserSummary objects and a string describing the cursor to the next page of results.
from vonage_users import ListUsersRequest
users, _ = vonage_client.users.list_users()
# With options
params = ListUsersRequest(
page_size=10,
cursor=my_cursor,
order='desc',
)
users, next_cursor = vonage_client.users.list_users(params)from vonage_users import User, Channels, SmsChannel
user_options = User(
name='my_user_name',
display_name='My User Name',
properties={'custom_key': 'custom_value'},
channels=Channels(sms=[SmsChannel(number='1234567890')]),
)
user = vonage_client.users.create_user(user_options)user = client.users.get_user('USR-87e3e6b0-cd7b-45ef-a0a7-bcd5566a672b')
user_as_dict = user.model_dump(exclude_none=True)from vonage_users import User, Channels, SmsChannel, WhatsappChannel
user_options = User(
name='my_user_name',
display_name='My User Name',
properties={'custom_key': 'custom_value'},
channels=Channels(sms=[SmsChannel(number='1234567890')], whatsapp=[WhatsappChannel(number='9876543210')]),
)
user = vonage_client.users.update_user(id, user_options)vonage_client.users.delete_user(id)from vonage_verify import VerifyRequest, SmsChannel
# All channels have associated models
sms_channel = SmsChannel(to='1234567890')
params = {
'brand': 'Vonage',
'workflow': [sms_channel],
}
verify_request = VerifyRequest(**params)
response = vonage_client.verify.start_verification(verify_request)If using silent authentication, the response will include a check_url field with a url that should be accessed on the user's device to proceed with silent authentication. If used, silent auth must be the first element in the workflow list.
silent_auth_channel = SilentAuthChannel(channel=ChannelType.SILENT_AUTH, to='1234567890')
sms_channel = SmsChannel(to='1234567890')
params = {
'brand': 'Vonage',
'workflow': [silent_auth_channel, sms_channel],
}
verify_request = VerifyRequest(**params)
response = vonage_client.verify.start_verification(verify_request)vonage_client.verify.check_code(request_id='my_request_id', code='1234')vonage_client.verify.cancel_verification('my_request_id')vonage_client.verify.trigger_next_workflow('my_request_id')from vonage_verify_legacy import VerifyRequest
params = {'number': '1234567890', 'brand': 'Acme Inc.'}
request = VerifyRequest(**params)
response = vonage_client.verify_legacy.start_verification(request)from vonage_verify_legacy import Psd2Request
params = {'number': '1234567890', 'payee': 'Acme Inc.', 'amount': 99.99}
request = VerifyRequest(**params)
response = vonage_client.verify_legacy.start_verification(request)vonage_client.verify_legacy.check_code(request_id='my_request_id', code='1234')# Search for single request
response = vonage_client.verify_legacy.search('my_request_id')
# Search for multiple requests
response = vonage_client.verify_legacy.search(['my_request_id_1', 'my_request_id_2'])response = vonage_client.verify_legacy.cancel_verification('my_request_id')response = vonage_client.verify_legacy.trigger_next_event('my_request_id')Note: Network Unblock is switched off by default. Contact Sales to enable the Network Unblock API for your account.
response = vonage_client.verify_legacy.request_network_unblock('23410')You will use the custom Pydantic data models to make most of the API calls in this package. They are accessed from the vonage_video.models package.
from vonage_video.models import TokenOptions
token_options = TokenOptions(session_id='your_session_id', role='publisher')
client_token = vonage_client.video.generate_client_token(token_options)from vonage_video.models import SessionOptions
session_options = SessionOptions(media_mode='routed')
video_session = vonage_client.video.create_session(session_options)streams = vonage_client.video.list_streams(session_id='your_session_id')stream_info = vonage_client.video.get_stream(session_id='your_session_id', stream_id='your_stream_id')from vonage_video.models import StreamLayoutOptions
layout_options = StreamLayoutOptions(type='bestFit')
updated_streams = vonage_client.video.change_stream_layout(session_id='your_session_id', stream_layout_options=layout_options)from vonage_video.models import SignalData
signal_data = SignalData(type='chat', data='Hello, World!')
vonage_client.video.send_signal(session_id='your_session_id', data=signal_data)vonage_client.video.disconnect_client(session_id='your_session_id', connection_id='your_connection_id')vonage_client.video.mute_stream(session_id='your_session_id', stream_id='your_stream_id')vonage_client.video.mute_all_streams(session_id='your_session_id', excluded_stream_ids=['stream_id_1', 'stream_id_2'])vonage_client.video.disable_mute_all_streams(session_id='your_session_id')from vonage_video.models import CaptionsOptions
captions_options = CaptionsOptions(language='en-US')
captions_data = vonage_client.video.start_captions(captions_options)from vonage_video.models import CaptionsData
captions_data = CaptionsData(captions_id='your_captions_id')
vonage_client.video.stop_captions(captions_data)from vonage_video.models import AudioConnectorOptions
audio_connector_options = AudioConnectorOptions(session_id='your_session_id', token='your_token', url='https://example.com')
audio_connector_data = vonage_client.video.start_audio_connector(audio_connector_options)from vonage_video.models import ExperienceComposerOptions
experience_composer_options = ExperienceComposerOptions(session_id='your_session_id', token='your_token', url='https://example.com')
experience_composer = vonage_client.video.start_experience_composer(experience_composer_options)from vonage_video.models import ListExperienceComposersFilter
filter = ListExperienceComposersFilter(page_size=10)
experience_composers, count, next_page_offset = vonage_client.video.list_experience_composers(filter)
print(experience_composers)experience_composer = vonage_client.video.get_experience_composer(experience_composer_id='experience_composer_id')vonage_client.video.stop_experience_composer(experience_composer_id='experience_composer_id')from vonage_video.models import ListArchivesFilter
filter = ListArchivesFilter(offset=2)
archives, count, next_page_offset = vonage_client.video.list_archives(filter)
print(archives)from vonage_video.models import CreateArchiveRequest
archive_options = CreateArchiveRequest(session_id='your_session_id', name='My Archive')
archive = vonage_client.video.start_archive(archive_options)archive = vonage_client.video.get_archive(archive_id='your_archive_id')
print(archive)vonage_client.video.delete_archive(archive_id='your_archive_id')from vonage_video.models import AddStreamRequest
add_stream_request = AddStreamRequest(stream_id='your_stream_id')
vonage_client.video.add_stream_to_archive(archive_id='your_archive_id', params=add_stream_request)vonage_client.video.remove_stream_from_archive(archive_id='your_archive_id', stream_id='your_stream_id')archive = vonage_client.video.stop_archive(archive_id='your_archive_id')
print(archive)from vonage_video.models import ComposedLayout
layout = ComposedLayout(type='bestFit')
archive = vonage_client.video.change_archive_layout(archive_id='your_archive_id', layout=layout)
print(archive)from vonage_video.models import ListBroadcastsFilter
filter = ListBroadcastsFilter(page_size=10)
broadcasts, count, next_page_offset = vonage_client.video.list_broadcasts(filter)
print(broadcasts)from vonage_video.models import CreateBroadcastRequest, BroadcastOutputSettings, BroadcastHls, BroadcastRtmp
broadcast_options = CreateBroadcastRequest(session_id='your_session_id', outputs=BroadcastOutputSettings(
hls=BroadcastHls(dvr=True, low_latency=False),
rtmp=[
BroadcastRtmp(
id='test',
server_url='rtmp://a.rtmp.youtube.com/live2',
stream_name='stream-key',
)
],
)
)
broadcast = vonage_client.video.start_broadcast(broadcast_options)
print(broadcast)broadcast = vonage_client.video.get_broadcast(broadcast_id='your_broadcast_id')
print(broadcast)broadcast = vonage_client.video.stop_broadcast(broadcast_id='your_broadcast_id')
print(broadcast)from vonage_video.models import ComposedLayout
layout = ComposedLayout(type='bestFit')
broadcast = vonage_client.video.change_broadcast_layout(broadcast_id='your_broadcast_id', layout=layout)
print(broadcast)from vonage_video.models import AddStreamRequest
add_stream_request = AddStreamRequest(stream_id='your_stream_id')
vonage_client.video.add_stream_to_broadcast(broadcast_id='your_broadcast_id', params=add_stream_request)vonage_client.video.remove_stream_from_broadcast(broadcast_id='your_broadcast_id', stream_id='your_stream_id')from vonage_video.models import InitiateSipRequest, SipOptions, SipAuth
sip_request_params = InitiateSipRequest(
session_id='your_session_id',
token='your_token',
sip=SipOptions(
uri=f'sip:{vonage_number}@sip.nexmo.com;transport=tls',
from_=f'test@vonage.com',
headers={'header_key': 'header_value'},
auth=SipAuth(username='1485b9e6', password='fL8jvi4W2FmS9som'),
secure=False,
video=False,
observe_force_mute=True,
),
)
sip_call = vonage_client.video.initiate_sip_call(sip_request_params)
print(sip_call)# Play into all connections
session_id = 'your_session_id'
digits = '1234#*p'
vonage_client.video.play_dtmf(session_id=session_id, digits=digits)
# Play into one connection
session_id = 'your_session_id'
digits = '1234#*p'
connection_id = 'your_connection_id'
vonage_client.video.play_dtmf(session_id=session_id, digits=digits, connection_id=connection_id)To create a call, you must pass an instance of the CreateCallRequest model to the create_call method. If supplying an NCCO, import the NCCO actions you want to use and pass them in as a list to the ncco model field.
from vonage_voice.models import CreateCallRequest, Talk
ncco = [Talk(text='Hello world', loop=3, language='en-GB')]
call = CreateCallRequest(
to=[{'type': 'phone', 'number': '1234567890'}],
ncco=ncco,
random_from_number=True,
)
response = vonage_client.voice.create_call(call)
print(response.model_dump())# Gets the first 100 results and the record_index of the
# next page if there's more than 100
calls, next_record_index = vonage_client.voice.list_calls()
# Specify filtering options
from vonage_voice.models import ListCallsFilter
call_filter = ListCallsFilter(
status='completed',
date_start='2024-03-14T07:45:14Z',
date_end='2024-04-19T08:45:14Z',
page_size=10,
record_index=0,
order='asc',
conversation_uuid='CON-2be039b2-d0a4-4274-afc8-d7b241c7c044',
)
calls, next_record_index = vonage_client.voice.list_calls(call_filter)call = vonage_client.voice.get_call('CALL_ID')ncco = [Talk(text='Hello world')]
vonage_client.voice.transfer_call_ncco('UUID', ncco)vonage_client.voice.transfer_call_answer_url('UUID', 'ANSWER_URL')End the call for a specified UUID, removing them from it.
vonage_client.voice.hangup('UUID')vonage_client.voice.mute('UUID')
vonage_client.voice.unmute('UUID')Prevent/allow a specified UUID participant to be able to hear audio.
vonage_client.voice.earmuff('UUID')
vonage_client.voice.unearmuff('UUID')from vonage_voice.models import AudioStreamOptions
# Only the `stream_url` option is required
options = AudioStreamOptions(
stream_url=['https://example.com/audio'], loop=2, level=0.5
)
response = vonage_client.voice.play_audio_into_call('UUID', options)vonage_client.voice.stop_audio_stream('UUID')from vonage_voice.models import TtsStreamOptions
# Only the `text` field is required
options = TtsStreamOptions(
text='Hello world', language='en-ZA', style=1, premium=False, loop=2, level=0.5
)
response = voice.play_tts_into_call('UUID', options)vonage_client.voice.stop_tts('UUID')response = voice.play_dtmf_into_call('UUID', '1234*#')from utils import format_phone_number, remove_none_values
# Use format_phone_number
try:
formatted_number = format_phone_number('123-456-7890')
print(formatted_number)
except (InvalidPhoneNumberError, InvalidPhoneNumberTypeError) as e:
print(e)
# Use remove_none_values to remove null values from a Vonage API response when converting to a dictionary with the `asdict` method
from dataclasses import asdict
vonage_api_response = vonage.api.method()
cleaned_dict = asdict(my_dataclass, dict_factory=remove_none_values)
print(cleaned_dict)The following is a list of Vonage APIs and whether the Python SDK provides support for them:
| API | API Release Status | Supported? |
|---|---|---|
| Account API | General Availability | ✅ |
| Application API | General Availability | ✅ |
| Audit API | Beta | ❌ |
| Conversation API | Beta | ❌ |
| Dispatch API | Beta | ❌ |
| External Accounts API | Beta | ❌ |
| Media API | Beta | ❌ |
| Messages API | General Availability | ✅ |
| Number Insight API | General Availability | ✅ |
| Number Management API | General Availability | ✅ |
| Pricing API | General Availability | ✅ |
| Redact API | Developer Preview | ❌ |
| Reports API | Beta | ❌ |
| SMS API | General Availability | ✅ |
| Subaccounts API | General Availability | ✅ |
| Verify API | General Availability | ✅ |
| Verify API (Legacy) | General Availability | ✅ |
| Video API | General Availability | ✅ |
| Voice API | General Availability | ✅ |
asyncio is a library to write concurrent code using the async/await syntax.
We don't currently support asyncio in the Python SDK.
We ❤️ contributions! But if you plan to work on something big or controversial, please contact us by raising an issue first!
We recommend working on vonage-python-sdk with a [virtualenv][virtualenv]. The following command will install all the Python dependencies you need to run the tests:
pip install -r requirements.txtThe tests are all written with pytest. You run them with:
pytest -vWe use Black for code formatting, with our config in the pyproject.toml file. To ensure a PR follows the right format, you can set up and use our pre-commit settings with
pre-commit installThen when you commit code, if it's not in the right format, it will be automatically fixed for you. After that, just commit again and everything should work as expected!
This library is released under the Apache License.
