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¶
To install the Python client library using pip:
pip install nexmo
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
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
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
Application API¶
Create an application¶
response = client.create_application(name='Example App', type='voice', answer_url=answer_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)
API Coverage¶
- Account
- [X] Balance
- [X] Pricing
- [X] Settings
- [X] Top Up
- [X] Numbers
- [X] Search
- [X] Buy
- [X] Cancel
- [X] Update
- Number Insight
- [X] Basic
- [X] Standard
- [X] Advanced
- [ ] Webhook Notification
- Verify
- [X] Verify
- [X] Check
- [X] Search
- [X] Control
- Messaging
- [X] Send
- [ ] Delivery Receipt
- [ ] Inbound Messages
- [X] Search
- [X] Message
- [X] Messages
- [X] Rejections
- [X] US Short Codes
- [X] Two-Factor Authentication
- [X] Event Based Alerts
- [X] Sending Alerts
- [X] Campaign Subscription Management
- Voice
- [X] Outbound Calls
- [ ] Inbound Call
- [X] Text-To-Speech Call
- [X] Text-To-Speech Prompt
License¶
This library is released under the MIT License