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.
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.
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).
To create an instance of the SMS class follow these steps:
#Option 1
from nexmo import Sms
#Option 2
from nexmo.sms import Sms
#Option 3
import nexmo #then you can use nexmo.Sms() to 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)
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",
})
sms.send_message({
'from': NEXMO_BRAND_NAME,
'to': TO_NUMBER,
'text': 'こんにちは世界',
'type': 'unicode',
})
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'])
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']
})
from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
voice.get_calls()
from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
voice.get_call(uuid)
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')
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])
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'])
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')
>>> 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'])
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')
response = client.get_recording(RECORDING_URL)
To create an instance of the Verify class, Just follow the next steps:
#First way
from nexmo import Verify
#Second way
from nexmo.verify import Verify
#Third valid way
import nexmo #then you can use nexmo.Verify() to create an instance
#First way - pass key and secret to the constructor
verify = Verify(key=NEXMO_API_KEY, secret=NEXMO_API_SECRET)
#Second way - Create a client instance and then pass the client to the Verify contructor
client = Client(key=NEXMO_API_KEY, secret=NEXMO_API_SECRET)
verify = Verify(client)
client = Client(key='API_KEY', secret='API_SECRET')
verify = Verify(client)
response = verify.search('69e2626cbc23451fbbc02f627a959677')
if response is not None:
print(response['status'])
client = Client(key='API_KEY', secret='API_SECRET')
verify = Verify(client)
response = verify.request(number=RECIPIENT_NUMBER, brand='AcmeInc')
if response["status"] == "0":
print("Started verification request_id is %s" % (response["request_id"]))
else:
print("Error: %s" % response["error_text"])
client = Client(key='API_KEY', secret='API_SECRET')
verify = Verify(client)
response = verify.request(number=RECIPIENT_NUMBER, brand='AcmeInc', workflow_id=1)
if response["status"] == "0":
print("Started verification request_id is %s" % (response["request_id"]))
else:
print("Error: %s" % response["error_text"])
client = Client(key='API_KEY', secret='API_SECRET')
verify = Verify(client)
response = verify.check(REQUEST_ID, code=CODE)
if response["status"] == "0":
print("Verification successful, event_id is %s" % (response["event_id"]))
else:
print("Error: %s" % response["error_text"])
client = Client(key='API_KEY', secret='API_SECRET')
verify = Verify(client)
response = verify.cancel(REQUEST_ID)
if response["status"] == "0":
print("Cancellation successful")
else:
print("Error: %s" % response["error_text"])
client = Client(key='API_KEY', secret='API_SECRET')
verify = Verify(client)
response = verify.trigger_next_event(REQUEST_ID)
if response["status"] == "0":
print("Next verification stage triggered")
else:
print("Error: %s" % response["error_text"])
client = Client(key='API_KEY', secret='API_SECRET')
verify = Verify(client)
response = verify.psd2(number=RECIPIENT_NUMBER, payee=PAYEE, amount=AMOUNT)
if response["status"] == "0":
print("Started PSD2 verification request_id is %s" % (response["request_id"]))
else:
print("Error: %s" % response["error_text"])
client = Client(key='API_KEY', secret='API_SECRET')
verify = Verify(client)
verify.psd2(number=RECIPIENT_NUMBER, payee=PAYEE, amount=AMOUNT, workflow_id: WORKFLOW_ID)
if response["status"] == "0":
print("Started PSD2 verification request_id is %s" % (response["request_id"]))
else:
print("Error: %s" % response["error_text"])
client.get_basic_number_insight(number='447700900000')
Docs: https://developer.nexmo.com/api/number-insight#getNumberInsightBasic
client.get_standard_number_insight(number='447700900000')
Docs: https://developer.nexmo.com/api/number-insight#getNumberInsightStandard
client.get_advanced_number_insight(number='447700900000')
Docs: https://developer.nexmo.com/api/number-insight#getNumberInsightAdvanced
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.
secrets = client.list_secrets(API_KEY)
Create a new secret (the created dates will help you know which is which):
client.create_secret(API_KEY, 'awes0meNewSekret!!;');
Delete the old secret (any application still using these credentials will stop working):
client.delete_secret(API_KEY, 'my-secret-id')
response = client.application_v2.create_application({name='Example App', type='voice'})
Docs: https://developer.nexmo.com/api/application.v2#createApplication
response = client.application_v2.list_applications()
Docs: https://developer.nexmo.com/api/application.v2#listApplication
response = client.application_v2.get_application(uuid)
Docs: https://developer.nexmo.com/api/application.v2#getApplication
response = client.application_v2.update_application(uuid, answer_method='POST')
Docs: https://developer.nexmo.com/api/application.v2#updateApplication
response = client.application_v2.delete_application(uuid)
Docs: https://developer.nexmo.com/api/application.v2#deleteApplication
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.
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)
In order to rewrite/get the value of variables used across all the Nexmo classes Python uses Call by Object Reference that allows you to create a single client for Sms/Voice Classes. This means that if you make a change on a client instance this will be available for the Sms class.
An example using setters/getters with Object references:
from nexmo import Client, Sms
#Defines the client
client = Client(key='YOUR_API_KEY', secret='YOUR_API_SECRET')
print(client.host()) # using getter for host -- value returned: rest.nexmo.com
#Define the sms instance
sms = Sms(client)
#Change the value in client
client.host('mio.nexmo.com') #Change host to mio.nexmo.com - this change will be available for sms
These attributes are private in the client class and the only way to access them is using the getters/setters we provide.
from nexmo import Client
client = Client(key='YOUR_API_KEY', secret='YOUR_API_SECRET')
print(client.host()) # return rest.nexmo.com
client.host('mio.nexmo.com') # rewrites the host value to mio.nexmo.com
print(client.api_host()) # returns api.nexmo.com
client.api_host('myapi.nexmo.com') # rewrite the value of api_host
Back in 2014 when Guido van Rossum, Python's creator and principal author, made the announcement, January 1, 2020 seemed pretty far away. Python 2.7’s sunset has happened, after which there’ll be absolutely no more support from the core Python team. Many utilized projects pledge to drop Python 2 support in or before 2020. (Official statement here).
Just because 2.7 isn’t going to be maintained past 2020 doesn’t mean your applications or libraries suddenly stop working but as of this moment we won't give official support for upcoming releases. Please read the official "Porting Python 2 Code to Python 3" guide. Please also read the Python 3 Statement Practicalities for advice on sunsetting your Python 2 code.
The following is a list of Vonage APIs and whether the Python SDK provides support for them:
| API | API Release Status | Supported? |
|---|---|---|
| Account API | General Availability | ✅ |
| Alerts API | General Availability | ✅ |
| Application API | General Availability | ✅ |
| Audit API | Beta | ❌ |
| Conversation API | Beta | ❌ |
| Dispatch API | Beta | ❌ |
| External Accounts API | Beta | ❌ |
| Media API | Beta | ❌ |
| Messages API | Beta | ❌ |
| Number Insight API | General Availability | ✅ |
| Number Management API | General Availability | ✅ |
| Pricing API | General Availability | ✅ |
| Redact API | General Availability | ✅ |
| Reports API | Beta | ❌ |
| SMS API | General Availability | ✅ |
| Verify API | General Availability | ✅ |
| Voice API | General Availability | ✅ |
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
This library is released under the MIT License.
FAQs
Nexmo Client Library for Python
We found that nexmo demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.