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 [email protected]:Nexmo/nexmo-python.git
or by opening it on GitHub desktop.
Usage
Begin by importing the nexmo module:
import nexmoThen 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
SMS Class
Creating an instance of the SMS class
To create an instance of the SMS class follow these steps:
- Import the class
#Option 1
from nexmo import Sms
#Option 2
from nexmo.sms import Sms
#Option 3
import nexmo #then tou can use nexmo.Sms() to create an instance- Create an instance
#Option 1 - pass key and secret to the constructor
sms = Sms(key=NEXMO_API_KEY, secret=NEXMO_API_SECRET)
#Option 2 - Create a client instance and then pass the client to the Sms instance
client = Client(key=NEXMO_API_KEY, secret=NEXMO_API_SECRET)
sms = Sms(client)Send an SMS
responseData = client.send_message(
{
"from": NEXMO_BRAND_NAME,
"to": TO_NUMBER,
"text": "A text message sent using the Nexmo SMS API",
}
)Reference: Send sms
Using the Sms class
from nexmo import Sms
sms = Sms(key=NEXMO_API_KEY, secret=NEXMO_API_SECRET)
sms.send_message({
"from": NEXMO_BRAND_NAME,
"to": TO_NUMBER,
"text": "A text message sent using the Nexmo SMS API",
})Support link: Send sms
Send SMS with unicode
responseData = client.send_message({
'from': NEXMO_BRAND_NAME,
'to': TO_NUMBER,
'text': 'こんにちは世界',
'type': 'unicode',
})Reference: Send sms with unicode
Using Sms Class
sms.send_message({
'from': NEXMO_BRAND_NAME,
'to': TO_NUMBER,
'text': 'こんにちは世界',
'type': 'unicode',
})Submit SMS Conversion
client.submit_sms_conversion("a-message-id")With the SMS Class
from nexmo import Client, Sms
client = Client(key=NEXMO_API_KEY, secret=NEXMO_SECRET)
sms = Sms(client)
response = sms.send_message({
'from': NEXMO_BRAND_NAME,
'to': TO_NUMBER,
'text': 'Hi from Vonage'
})
sms.submit_sms_conversion(response['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
with voice class
from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
voice.create_all({
'to': [{'type': 'phone', 'number': '14843331234'}],
'from': {'type': 'phone', 'number': '14843335555'},
'answer_url': ['https://example.com/answer']
})Testing screenshots:create call
Retrieve a list of calls
response = client.get_calls()Docs: https://developer.nexmo.com/api/voice#getCalls
with voice class
from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
voice.get_calls()Testing screenshots: get calls
Retrieve a single call
response = client.get_call(uuid)Docs: https://developer.nexmo.com/api/voice#getCall
with voice class
from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
voice.get_call(uuid)Testing Screenshots: get single call
Update a call
response = client.update_call(uuid, action='hangup')Docs: https://developer.nexmo.com/api/voice#updateCall
with voice class
from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
response = voice.create_all({
'to': [{'type': 'phone', 'number': '14843331234'}],
'from': {'type': 'phone', 'number': '14843335555'},
'answer_url': ['https://example.com/answer']
})
voice.update_call(response['uuid'], action='hangup')Support Link: update call
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
with voice class
from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
stream_url = 'https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3'
response = voice.create_call({
'to': [{'type': 'phone', 'number': '14843331234'}],
'from': {'type': 'phone', 'number': '14843335555'},
'answer_url': ['https://example.com/answer']
})
voice.send_audio(response['uuid'],stream_url=[stream_url])Support link: Send audio stream
Stop streaming audio to a call
response = client.stop_audio(uuid)Docs: https://developer.nexmo.com/api/voice#stopStream
Using voice class
from nexmo import Client, Voice
client = Client(application_id='0d4884d1-eae8-4f18-a46a-6fb14d5fdaa6', private_key='./private.key')
voice = Voice(client)
stream_url = 'https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3'
response = voice.create_call({
'to': [{'type': 'phone', 'number': '14843331234'}],
'from': {'type': 'phone', 'number': '14843335555'},
'answer_url': ['https://example.com/answer']
})
voice.send_audio(response['uuid'],stream_url=[stream_url])
voice.stop_audio(response['uuid'])Support Link: Stop audio stream
Send a synthesized speech message to a call
response = client.send_speech(uuid, text='Hello')Docs: https://developer.nexmo.com/api/voice#startTalk
Using voice class
from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
response = voice.create_call({
'to': [{'type': 'phone', 'number': '14843331234'}],
'from': {'type': 'phone', 'number': '14843335555'},
'answer_url': ['https://example.com/answer']
})
voice.send_speech(response['uuid'], text='Hello from nexmo')Support link: Send speech
Stop sending a synthesized speech message to a call
response = client.stop_speech(uuid)Docs: https://developer.nexmo.com/api/voice#stopTalk
Using voice class
>>> from nexmo import Client, Voice
>>> client = Client(application_id=APPLICATION_ID, private_key=APPLICATION_ID)
>>> voice = Voice(client)
>>> response = voice.create_call({
'to': [{'type': 'phone', 'number': '14843331234'}],
'from': {'type': 'phone', 'number': '14843335555'},
'answer_url': ['https://example.com/answer']
})
>>> voice.send_speech(response['uuid'], text='Hello from nexmo')
>>> voice.stop_speech(response['uuid'])Support link: Stop speech
Send DTMF tones to a call
response = client.send_dtmf(uuid, digits='1234')Docs: https://developer.nexmo.com/api/voice#startDTMF
Using voice class
from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
response = voice.create_call({
'to': [{'type': 'phone', 'number': '14843331234'}],
'from': {'type': 'phone', 'number': '14843335555'},
'answer_url': ['https://example.com/answer']
})
voice.send_dtmf(response['uuid'], digits='1234')Support link: Send DTMF
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 signatureDocs: 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)Contributing
We ❤️ 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 installThe tests are all written with pytest. You run them with:
make testLicense
This library is released under the MIT License.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent
