Nexmo Client Library for Python
Project description
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 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)
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
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)
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.4.0-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6f7d44d898f1c022b62ea5440e48d089feda4e0dc3b460746ff376c6196eb355 |
|
MD5 | 652c54db8fbd49e1a9300b13cb06cf00 |
|
BLAKE2b-256 | 3587e5514c51239cebc8f1f5ebb6b3648ae11cd45972493115a61b26c76b0f63 |