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.
from vonage_messages 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 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 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')from vonage_video 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 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 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 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 import CaptionsOptions captions_options = CaptionsOptions(language='en-US') captions_data = vonage_client.video.start_captions(captions_options)from vonage_video import CaptionsData captions_data = CaptionsData(captions_id='your_captions_id') vonage_client.video.stop_captions(captions_data)from vonage_video 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 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 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 import ListArchivesFilter filter = ListArchivesFilter(offset=2) archives, count, next_page_offset = vonage_client.video.list_archives(filter) print(archives)from vonage_video 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 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 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 import ListBroadcastsFilter filter = ListBroadcastsFilter(page_size=10) broadcasts, count, next_page_offset = vonage_client.video.list_broadcasts(filter) print(broadcasts)from vonage_video 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 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 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 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 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 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 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 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 within a virtual environment - below we're using the venv] module:
# 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\activateThe 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:
PYTHONPATH=. 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.
