Nexmo 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
- Managing Secrets
- Application API
- 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:
git clone git@github.com:Nexmo/nexmo-python.git
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)
In order 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://docs.nexmo.com/messaging/sms-api/api-reference#request
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)
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://docs.nexmo.com/voice/voice-api/api-reference#call_create
Retrieve a list of calls
response = client.get_calls()
Docs: https://docs.nexmo.com/voice/voice-api/api-reference#call_retrieve
Retrieve a single call
response = client.get_call(uuid)
Docs: https://docs.nexmo.com/voice/voice-api/api-reference#call_retrieve_single
Update a call
response = client.update_call(uuid, action='hangup')
Docs: https://docs.nexmo.com/voice/voice-api/api-reference#call_modify_single
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://docs.nexmo.com/voice/voice-api/api-reference#stream_put
Stop streaming audio to a call
response = client.stop_audio(uuid)
Docs: https://docs.nexmo.com/voice/voice-api/api-reference#stream_delete
Send a synthesized speech message to a call
response = client.send_speech(uuid, text='Hello')
Docs: https://docs.nexmo.com/voice/voice-api/api-reference#talk_put
Stop sending a synthesized speech message to a call
response = client.stop_speech(uuid)
Docs: https://docs.nexmo.com/voice/voice-api/api-reference#talk_delete
Send DTMF tones to a call
response = client.send_dtmf(uuid, digits='1234')
Docs: https://docs.nexmo.com/voice/voice-api/api-reference#dtmf_put
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=' + response['request_id']
else:
print 'Error:', response['error_text']
Docs: https://docs.nexmo.com/verify/api-reference/api-reference#vrequest
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=' + response['event_id']
else:
print 'Error:', response['error_text']
Docs: https://docs.nexmo.com/verify/api-reference/api-reference#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://docs.nexmo.com/verify/api-reference/api-reference#control
Trigger next verification step
client.trigger_next_verification_event('00e6c3377e5348cdaf567e1417c707a5')
Docs: https://docs.nexmo.com/verify/api-reference/api-reference#control
Number Insight API
Basic Number Insight
client.get_basic_number_insight(number='447700900000')
Docs: https://docs.nexmo.com/number-insight/basic
Standard Number Insight
client.get_standard_number_insight(number='447700900000')
Docs: https://docs.nexmo.com/number-insight/standard
Advanced Number Insight
client.get_advanced_number_insight(number='447700900000')
Docs: https://docs.nexmo.com/number-insight/advanced
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.create_application(name='Example App', type='voice', answer_url=answer_url, event_url=event_url)
Docs: https://docs.nexmo.com/tools/application-api/api-reference#create
Retrieve a list of applications
response = client.get_applications()
Docs: https://docs.nexmo.com/tools/application-api/api-reference#list
Retrieve a single application
response = client.get_application(uuid)
Docs: https://docs.nexmo.com/tools/application-api/api-reference#retrieve
Update an application
response = client.update_application(uuid, answer_method='POST')
Docs: https://docs.nexmo.com/tools/application-api/api-reference#update
Delete an application
response = client.delete_application(uuid)
Docs: https://docs.nexmo.com/tools/application-api/api-reference#delete
Validate webhook signatures
client = nexmo.Client(signature_secret='secret')
if client.check_signature(request.query):
# valid signature
else:
# invalid signature
Docs: https://docs.nexmo.com/messaging/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)
Contributing
We
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