Vonage Client Library for Python
Project description
Vonage Client Library for Python
This is the Python client library for Nexmo's API. To use it you'll need a Nexmo account. Sign up for free at nexmo.com.
- Installation
- Usage
- SMS API
- Voice API
- Verify API
- Number Insight API
- Number Management API
- Managing Secrets
- Application API
- Overriding API url's
- License
Installation
To install the Python client library using pip:
pip install nexmo
To upgrade your installed client library using pip:
pip install nexmo --upgrade
Alternatively, you can clone the repository via the command line:
git clone git@github.com:Nexmo/nexmo-python.git
or by opening it on GitHub desktop.
Usage
Begin by importing the nexmo
module:
import nexmo
Then construct a client object with your key and secret:
client = nexmo.Client(key=api_key, secret=api_secret)
For production, you can specify the NEXMO_API_KEY
and NEXMO_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 = nexmo.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 NEXMO_SIGNATURE_SECRET
environment variable).
SMS API
Send a text message
response = client.send_message({'from': 'Python', 'to': 'YOUR-NUMBER', 'text': 'Hello world'})
response = response['messages'][0]
if response['status'] == '0':
print('Sent message', response['message-id'])
print('Remaining balance is', response['remaining-balance'])
else:
print('Error:', response['error-text'])
Docs: https://developer.nexmo.com/api/sms#send-an-sms
Tell Nexmo the SMS was received
The following submits a successful conversion to Nexmo with the current timestamp. This feature must be enabled on your account first.
response = client.submit_sms_conversion(message_id)
Signing a Message
You may also like to read the documentation about message signing.
The SMS API supports the ability to sign messages by generating and adding a signature using a "Signature Secret" rather than your API secret. The algorithms supported are:
md5hash1 md5 sha1 sha256 sha512
Both your application and Nexmo need to agree on which algorithm is used. In the dashboard, visit your account settings page and under "API Settings" you can select the algorithm to use. This is also the location where you will find your "Signature Secret" (it's different from the API secret).
Create a client using these credentials and the algorithm to use, for example:
client = nexmo.Client(
key = os.getenv('NEXMO_API_KEY'),
signature_secret = os.getenv('NEXMO_SIGNATURE_SECRET'),
signature_method = 'sha256'
)
Using this client, your SMS API messages will be sent as signed messages.
Verifying an Incoming Message Signature
You may also like to read the documentation about message signing.
If you have message signing enabled for incoming messages, the SMS webhook will include the fields sig, nonce and timestamp.
To verify the signature is from Nexmo, you create a Signature object using the incoming data, your signature secret and the signature method.
Then use the check_signature()
method with the actual signature that was received (usually present in request.form or request.args. you can merge those in a single variable called params) to make sure that it is correct.
Get the params
if request.is_json:
params = request.get_json()
else:
params = request.args or request.form
is_valid = client.check_signature(params)// is it valid? Will be true or false
Using your signature secret and the other supplied parameters, the signature can be calculated and checked against the incoming signature value.
Voice API
Make a call
response = client.create_call({
'to': [{'type': 'phone', 'number': '14843331234'}],
'from': {'type': 'phone', 'number': '14843335555'},
'answer_url': ['https://example.com/answer']
})
Docs: https://developer.nexmo.com/api/voice#createCall
Retrieve a list of calls
response = client.get_calls()
Docs: https://developer.nexmo.com/api/voice#getCalls
Retrieve a single call
response = client.get_call(uuid)
Docs: https://developer.nexmo.com/api/voice#getCall
Update a call
response = client.update_call(uuid, action='hangup')
Docs: https://developer.nexmo.com/api/voice#updateCall
Stream audio to a call
stream_url = 'https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3'
response = client.send_audio(uuid, stream_url=[stream_url])
Docs: https://developer.nexmo.com/api/voice#startStream
Stop streaming audio to a call
response = client.stop_audio(uuid)
Docs: https://developer.nexmo.com/api/voice#stopStream
Send a synthesized speech message to a call
response = client.send_speech(uuid, text='Hello')
Docs: https://developer.nexmo.com/api/voice#startTalk
Stop sending a synthesized speech message to a call
response = client.stop_speech(uuid)
Docs: https://developer.nexmo.com/api/voice#stopTalk
Send DTMF tones to a call
response = client.send_dtmf(uuid, digits='1234')
Docs: https://developer.nexmo.com/api/voice#startDTMF
Get recording
response = client.get_recording(RECORDING_URL)
Verify API
Start a verification
response = client.start_verification(number='441632960960', brand='MyApp')
if response['status'] == '0':
print('Started verification request_id={request_id}'.format(request_id=response['request_id']))
else:
print('Error:', response['error_text'])
Docs: https://developer.nexmo.com/api/verify#verify-request
The response contains a verification request id which you will need to store temporarily (in the session, database, url, etc).
Check a verification
response = client.check_verification('00e6c3377e5348cdaf567e1417c707a5', code='1234')
if response['status'] == '0':
print('Verification complete, event_id={event_id}'.format(event_id=response['event_id']))
else:
print('Error:', response['error_text'])
Docs: https://developer.nexmo.com/api/verify#verify-check
The verification request id comes from the call to the start_verification method. The PIN code is entered into your application by the user.
Cancel a verification
client.cancel_verification('00e6c3377e5348cdaf567e1417c707a5')
Docs: https://developer.nexmo.com/api/verify#verify-control
Trigger next verification step
client.trigger_next_verification_event('00e6c3377e5348cdaf567e1417c707a5')
Docs: https://developer.nexmo.com/api/verify#verify-control
Number Insight API
Basic Number Insight
client.get_basic_number_insight(number='447700900000')
Docs: https://developer.nexmo.com/api/number-insight#getNumberInsightBasic
Standard Number Insight
client.get_standard_number_insight(number='447700900000')
Docs: https://developer.nexmo.com/api/number-insight#getNumberInsightStandard
Advanced Number Insight
client.get_advanced_number_insight(number='447700900000')
Docs: https://developer.nexmo.com/api/number-insight#getNumberInsightAdvanced
Number Management API
List Your Numbers
client.get_account_numbers()
Docs: https://developer.nexmo.com/api/numbers#getOwnedNumbers
Search for a Number
client.get_available_numbers('GB', {"type":"SMS"})
Docs: https://developer.nexmo.com/api/numbers#getAvailableNumbers
Buy a Number
client.buy_number({"country": 'GB', "msisdn": '447700900000'})
Docs: https://developer.nexmo.com/api/numbers#buyANumber
Cancel a Number
client.cancel_number({"country": 'GB', "msisdn": '447700900000'})
Docs: https://developer.nexmo.com/api/numbers#cancelANumber
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.list_secrets(API_KEY)
Create A New Secret
Create a new secret (the created dates will help you know which is which):
client.create_secret(API_KEY, 'awes0meNewSekret!!;');
Delete A Secret
Delete the old secret (any application still using these credentials will stop working):
client.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 = nexmo.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 support@nexmo.com 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 url's
By default, our API url's are hardcoded. For use cases where these url's are not accessible, best practices to override these url's are the following:
- Setting new API url's when creating an instance of the client:
import nexmo
client = nexmo.Client()
client.host = 'new.host.url'
client.api_host = 'new.api.host'
- Creating a new class that extends from client class and overrides these values in the constructor:
class MyClient(nexmo.Client):
def __init__(self, NEXMO_API_KEY, NEXMO_API_SECRET, APPLICATION_ID, APPLICATION_PRIVATE_KEY_PATH):
super().__init__(application_id=APPLICATION_ID, private_key=APPLICATION_PRIVATE_KEY_PATH, key=NEXMO_API_KEY, secret=NEXMO_API_SECRET)
self.host = 'new.hosts.url'
self.api_host = 'new.api.hosts'
#usage
client = MyClient(NEXMO_API_KEY, NEXMO_API_SECRET, APPLICATION_ID, APPLICATION_PRIVATE_KEY_PATH)
For a more specific case, another way to customise is:
import nexmo
class NexmoClient(nexmo.Client):
def __init__(....):
super().__init__(....)
api_server = BasicAuthenticatedServer(
"mycustomurl",
user_agent=user_agent,
api_key=self.api_key,
api_secret=self.api_secret,
)
self.application_v2 = ApplicationV2(api_server)
Then proceed to create your personalised instance of the class.
Contributing
We :heart: contributions! But if you plan to work on something big or controversial, please contact us first!
We recommend working on nexmo-python
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 MIT License.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for nexmo-2.5.1-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | f46c8f3ed5fe751eb27de915904dfd34eabaf817f610211a2415f9af5215c687 |
|
MD5 | 252e2b3c095408e27a0dd604806adbee |
|
BLAKE2b-256 | 95d5046910f567b944756b909741470ea1dd940c8d36aeee8e24c3ec7c582115 |