README.md

Vonage Server SDK for Python

This is the Python server SDK for Vonage's API. To use it you'll need a Vonage account. Sign up for free at vonage.com.

• Installation
• Usage
• SMS API
• Messages API
• Voice API
• Verify API
• Number Insight API
• Number Management API
• Managing Secrets
• Application API
• Overriding API Attributes
• Frequently Asked Questions
• License

Installation

To install the Python client library using pip:

pip install vonage

To upgrade your installed client library using pip:

pip install vonage --upgrade

Alternatively, you can clone the repository via the command line:

git clone [email protected]:Vonage/vonage-python-sdk.git

or by opening it on GitHub desktop.

Usage

Begin by importing the vonage module:

import vonage

Then construct a client object with your key and secret:

client = vonage.Client(key=api_key, secret=api_secret)

For production, you can specify the VONAGE_API_KEY and VONAGE_API_SECRET environment variables instead of specifying the key and secret explicitly.

For newer endpoints that support JWT authentication such as the Voice API, you can also specify the application_id and private_key arguments:

client = vonage.Client(application_id=application_id, private_key=private_key)

To check signatures for incoming webhook requests, you'll also need to specify the signature_secret argument (or the VONAGE_SIGNATURE_SECRET environment variable).

To use the SDK to call Vonage APIs, pass in dicts with the required options to methods like Sms.send_message(). Examples of this are given below.

Simplified structure for calling API Methods

The client now instantiates a class object for each API when it is created, e.g. vonage.Client(key="mykey", secret="mysecret") instantiates instances of Account, Sms, NumberInsight etc. These instances can now be called directly from Client, e.g.

client = vonage.Client(key="mykey", secret="mysecret")

print(f"Account balance is: {client.account.get_balance()}")

print("Sending an SMS")
client.sms.send_message({
    "from": "Vonage",
    "to": "SOME_PHONE_NUMBER",
    "text": "Hello from Vonage's SMS API"
})

This means you don't have to create a separate instance of each class to use its API methods. Instead, you can access class methods from the client instance with

client.CLASS_NAME.CLASS_METHOD

SMS API

Although the Messages API adds more messaging channels, the SMS API is still supported.

Send an SMS

# New way
client = vonage.Client(key=VONAGE_API_KEY, secret=VONAGE_API_SECRET)
client.sms.send_message({
    "from": VONAGE_BRAND_NAME,
    "to": TO_NUMBER,
    "text": "A text message sent using the Vonage SMS API",
})

# Old way
from vonage import Sms
sms = Sms(key=VONAGE_API_KEY, secret=VONAGE_API_SECRET)
sms.send_message({
            "from": VONAGE_BRAND_NAME,
            "to": TO_NUMBER,
            "text": "A text message sent using the Vonage SMS API",
})

Send SMS with unicode

client = vonage.Client(key=VONAGE_API_KEY, secret=VONAGE_API_SECRET)
client.sms.send_message({
    'from': VONAGE_BRAND_NAME,
    'to': TO_NUMBER,
    'text': 'こんにちは世界',
    'type': 'unicode',
})

Submit SMS Conversion

client = vonage.Client(key=VONAGE_API_KEY, secret=VONAGE_SECRET)
response = client.sms.send_message({
    'from': VONAGE_BRAND_NAME,
    'to': TO_NUMBER,
    'text': 'Hi from Vonage'
})
client.sms.submit_sms_conversion(response['message-id'])

Messages API

The Messages API is an API that allows you to send messages via SMS, MMS, WhatsApp, Messenger and Viber. Call the API from your Python code by passing a dict of parameters into the client.messages.send_message() method.

It accepts JWT or API key/secret authentication.

Some basic samples are below. For more detailed information and code snippets, please visit the Vonage Developer Documentation.

Send an SMS

responseData = client.messages.send_message({
        'channel': 'sms', 
        'message_type': 'text', 
        'to': '447123456789', 
        'from': 'Vonage',
        'text': 'Hello from Vonage'
    })

Send an MMS

Note: only available in the US. You will need a 10DLC number to send an MMS message.

client.messages.send_message({
        'channel': 'mms', 
        'message_type': 'image', 
        'to': '11112223333', 
        'from': '1223345567',
        'image': {'url': 'https://example.com/image.jpg', 'caption': 'Test Image'}
    })

Send an audio file via WhatsApp

You will need a WhatsApp Business Account to use WhatsApp messaging. WhatsApp restrictions mean that you must send a template message to a user if they have not previously messaged you, but you can send any message type to a user if they have messaged your business number in the last 24 hours.

client.messages.send_message({
        'channel': 'whatsapp', 
        'message_type': 'audio', 
        'to': '447123456789', 
        'from': '440123456789',
        'audio': {'url': 'https://example.com/audio.mp3'}
    })

Send a video file via Facebook Messenger

You will need to link your Facebook business page to your Vonage account in the Vonage developer dashboard. (Click on the sidebar "External Accounts" option to do this.)

client.messages.send_message({
        'channel': 'messenger', 
        'message_type': 'video', 
        'to': '594123123123123', 
        'from': '1012312312312',
        'video': {'url': 'https://example.com/video.mp4'}
    })

Send a text message with Viber

client.messages.send_message({
    'channel': 'viber_service',
    'message_type': 'text',
    'to': '447123456789',
    'from': '440123456789',
    'text': 'Hello from Vonage!'
})

Voice API

Make a call

client = vonage.Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
client.voice.create_call({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})

Retrieve a list of calls

client = vonage.Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
client.voice.get_calls()

Retrieve a single call

client = vonage.Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
client.voice.get_call(uuid)

Update a call

client = vonage.Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
response = client.voice.create_call({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})
client.voice.update_call(response['uuid'], action='hangup')

Stream audio to a call

client = vonage.Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
stream_url = 'https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3'
response = client.voice.create_call({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})
client.voice.send_audio(response['uuid'],stream_url=[stream_url])

Stop streaming audio to a call

client = vonage.Client(application_id='0d4884d1-eae8-4f18-a46a-6fb14d5fdaa6', private_key='./private.key')
stream_url = 'https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3'
response = client.voice.create_call({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})
client.voice.send_audio(response['uuid'],stream_url=[stream_url])
client.voice.stop_audio(response['uuid'])

Send a synthesized speech message to a call

client = vonage.Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
response = client.voice.create_call({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})
client.voice.send_speech(response['uuid'], text='Hello from vonage')

Stop sending a synthesized speech message to a call

client = vonage.Client(application_id=APPLICATION_ID, private_key=APPLICATION_ID)
response = client.voice.create_call({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})
client.voice.send_speech(response['uuid'], text='Hello from vonage')
client.voice.stop_speech(response['uuid'])

Send DTMF tones to a call

client = vonage.Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
response = client.voice.create_call({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})
client.voice.send_dtmf(response['uuid'], digits='1234')

Get recording

response = client.get_recording(RECORDING_URL)

Verify API

Search for a Verification request

client = vonage.Client(key='API_KEY', secret='API_SECRET')

response = client.verify.search('69e2626cbc23451fbbc02f627a959677')

if response is not None:
    print(response['status'])

Send verification code

client = vonage.Client(key='API_KEY', secret='API_SECRET')

response = client.verify.start_verification(number=RECIPIENT_NUMBER, brand='AcmeInc')

if response["status"] == "0":
    print("Started verification request_id is %s" % (response["request_id"]))
else:
    print("Error: %s" % response["error_text"])

Send verification code with workflow

client = vonage.Client(key='API_KEY', secret='API_SECRET')

response = client.verify.start_verification(number=RECIPIENT_NUMBER, brand='AcmeInc', workflow_id=1)

if response["status"] == "0":
    print("Started verification request_id is %s" % (response["request_id"]))
else:
    print("Error: %s" % response["error_text"])

Check verification code

client = vonage.Client(key='API_KEY', secret='API_SECRET')

response = client.verify.check(REQUEST_ID, code=CODE)

if response["status"] == "0":
    print("Verification successful, event_id is %s" % (response["event_id"]))
else:
    print("Error: %s" % response["error_text"])

Cancel Verification Request

client = vonage.Client(key='API_KEY', secret='API_SECRET')

response = client.verify.cancel(REQUEST_ID)

if response["status"] == "0":
    print("Cancellation successful")
else:
    print("Error: %s" % response["error_text"])

Trigger next verification proccess

client = vonage.Client(key='API_KEY', secret='API_SECRET')

response = client.verify.trigger_next_event(REQUEST_ID)

if response["status"] == "0":
    print("Next verification stage triggered")
else:
    print("Error: %s" % response["error_text"])

Send payment authentication code

client = vonage.Client(key='API_KEY', secret='API_SECRET')

response = client.verify.psd2(number=RECIPIENT_NUMBER, payee=PAYEE, amount=AMOUNT)

if response["status"] == "0":
    print("Started PSD2 verification request_id is %s" % (response["request_id"]))
else:
    print("Error: %s" % response["error_text"])

Send payment authentication code with workflow

client = vonage.Client(key='API_KEY', secret='API_SECRET')

client.verify.psd2(number=RECIPIENT_NUMBER, payee=PAYEE, amount=AMOUNT, workflow_id: WORKFLOW_ID)

if response["status"] == "0":
    print("Started PSD2 verification request_id is %s" % (response["request_id"]))
else:
    print("Error: %s" % response["error_text"])

Number Insight API

Basic Number Insight

client.number_insight.get_basic_number_insight(number='447700900000')

Docs: https://developer.nexmo.com/api/number-insight#getNumberInsightBasic

Standard Number Insight

client.number_insight.get_standard_number_insight(number='447700900000')

Docs: https://developer.nexmo.com/api/number-insight#getNumberInsightStandard

Advanced Number Insight

client.number_insight.get_advanced_number_insight(number='447700900000')

Docs: https://developer.nexmo.com/api/number-insight#getNumberInsightAdvanced

Managing Secrets

An API is provided to allow you to rotate your API secrets. You can create a new secret (up to a maximum of two secrets) and delete the existing one once all applications have been updated.

List Secrets

secrets = client.account.list_secrets(API_KEY)

Create A New Secret

Create a new secret (the created dates will help you know which is which):

client.account.create_secret(API_KEY, 'awes0meNewSekret!!;');

Delete A Secret

Delete the old secret (any application still using these credentials will stop working):

client.account.delete_secret(API_KEY, 'my-secret-id')

Application API

Create an application

response = client.application_v2.create_application({name='Example App', type='voice'})

Docs: https://developer.nexmo.com/api/application.v2#createApplication

Retrieve a list of applications

response = client.application_v2.list_applications()

Docs: https://developer.nexmo.com/api/application.v2#listApplication

Retrieve a single application

response = client.application_v2.get_application(uuid)

Docs: https://developer.nexmo.com/api/application.v2#getApplication

Update an application

response = client.application_v2.update_application(uuid, answer_method='POST')

Docs: https://developer.nexmo.com/api/application.v2#updateApplication

Delete an application

response = client.application_v2.delete_application(uuid)

Docs: https://developer.nexmo.com/api/application.v2#deleteApplication

Validate webhook signatures

client = vonage.Client(signature_secret='secret')

if client.check_signature(request.query):
  # valid signature
else:
  # invalid signature

Docs: https://developer.nexmo.com/concepts/guides/signing-messages

Note: you'll need to contact [email protected] to enable message signing on your account before you can validate webhook signatures.

JWT parameters

By default, the library generates short-lived tokens for JWT authentication.

Use the auth method to specify parameters for a longer life token or to specify a different token identifier:

client.auth(nbf=nbf, exp=exp, jti=jti)

Overriding API Attributes

In order to rewrite/get the value of variables used across all the Vonage classes Python uses Call by Object Reference that allows you to create a single client for Sms/Voice Classes. This means that if you make a change on a client instance this will be available for the Sms class.

An example using setters/getters with Object references:

from vonage import Client, Sms

#Defines the client
client = Client(key='YOUR_API_KEY', secret='YOUR_API_SECRET')
print(client.host()) # using getter for host -- value returned: rest.nexmo.com

#Define the sms instance
sms = Sms(client)

#Change the value in client
client.host('mio.nexmo.com') #Change host to mio.nexmo.com - this change will be available for sms

Overriding API Host / Host Attributes

These attributes are private in the client class and the only way to access them is using the getters/setters we provide.

from vonage import Client

client = Client(key='YOUR_API_KEY', secret='YOUR_API_SECRET')
print(client.host()) # return rest.nexmo.com
client.host('mio.nexmo.com') # rewrites the host value to mio.nexmo.com
print(client.api_host()) # returns api.vonage.com
client.api_host('myapi.vonage.com') # rewrite the value of api_host

Frequently Asked Questions

Supported APIs

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	✅
Alerts 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	General Availability	✅
Reports API	Beta	❌
SMS API	General Availability	✅
Verify API	General Availability	✅
Voice API	General Availability	✅

asyncio Support

asyncio is a library to write concurrent code using the async/await syntax.

We don't currently support asyncio in the Python SDK but we are planning to do so in upcoming releases.

Contributing

We ❤️ contributions! But if you plan to work on something big or controversial, please contact us first!

We recommend working on vonage-python-sdk with a virtualenv. The following command will install all the Python dependencies you need to run the tests:

make install

The tests are all written with pytest. You run them with:

make test

License

This library is released under the Apache License.