Mariatta/nexmo-python

Nexmo REST API client for Python. API support for SMS, Voice, Text-to-Speech, Numbers, Verify (2FA) and more.

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#stopStream

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=' + 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=' + 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.create_application(name='Example App', type='voice', answer_url=answer_url, event_url=event_url)

Docs: https://developer.nexmo.com/api/application#create-an-application

Retrieve a list of applications

response = client.get_applications()

Docs: https://developer.nexmo.com/api/application#retrieve-your-applications

Retrieve a single application

response = client.get_application(uuid)

Docs: https://developer.nexmo.com/api/application#retrieve-an-application

Update an application

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

Docs: https://developer.nexmo.com/api/application#retrieve-your-applications

Delete an application

response = client.delete_application(uuid)

Docs: https://developer.nexmo.com/api/application#destroy-an-application

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 ❤️ 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