Skip to main content

Nexmo Client Library for Python

Project description

Nexmo Client Library for Python

PyPI version Build Status Coverage Status Python versions supported Code style: black

This is the Python client library for Nexmo's API. To use it you'll need a Nexmo account. Sign up for free at


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

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).


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'])
  print('Error:', response['error-text'])


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': ['']


Retrieve a list of calls

response = client.get_calls()


Retrieve a single call

response = client.get_call(uuid)


Update a call

response = client.update_call(uuid, action='hangup')


Stream audio to a call

stream_url = ''

response = client.send_audio(uuid, stream_url=[stream_url])


Stop streaming audio to a call

response = client.stop_audio(uuid)


Send a synthesized speech message to a call

response = client.send_speech(uuid, text='Hello')


Stop sending a synthesized speech message to a call

response = client.stop_speech(uuid)


Send DTMF tones to a call

response = client.send_dtmf(uuid, digits='1234')


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']))
  print('Error:', response['error_text'])


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']))
  print('Error:', response['error_text'])


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



Trigger next verification step



Number Insight API

Basic Number Insight



Standard Number Insight



Advanced Number Insight



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'})


Retrieve a list of applications

response = client.application_v2.list_applications()


Retrieve a single application

response = client.application_v2.get_application(uuid)


Update an application

response = client.application_v2.update_application(uuid, answer_method='POST')


Delete an application

response = client.application_v2.delete_application(uuid)


Validate webhook signatures

client = nexmo.Client(signature_secret='secret')

if client.check_signature(request.query):
  # valid signature
  # invalid signature


Note: you'll need to contact 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)


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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for nexmo, version 2.4.0
Filename, size File type Python version Upload date Hashes
Filename, size nexmo-2.4.0-py2.py3-none-any.whl (12.2 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size nexmo-2.4.0.tar.gz (35.7 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page