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
• Number Management API
• Managing Secrets
• Application API
• Overriding API url's
• 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)

Signing a Message

You may also like to read the documentation about message signing.

The SMS API supports the ability to sign messages by generating and adding a signature using a "Signature Secret" rather than your API secret. The algorithms supported are:

md5hash1 md5 sha1 sha256 sha512

Both your application and Nexmo need to agree on which algorithm is used. In the dashboard, visit your account settings page and under "API Settings" you can select the algorithm to use. This is also the location where you will find your "Signature Secret" (it's different from the API secret).

Create a client using these credentials and the algorithm to use, for example:

client = nexmo.Client(
            key = os.getenv('NEXMO_API_KEY'),
            signature_secret = os.getenv('NEXMO_SIGNATURE_SECRET'),
            signature_method = 'sha256'
)

Using this client, your SMS API messages will be sent as signed messages.

Verifying an Incoming Message Signature

You may also like to read the documentation about message signing.

If you have message signing enabled for incoming messages, the SMS webhook will include the fields sig, nonce and timestamp.

To verify the signature is from Nexmo, you create a Signature object using the incoming data, your signature secret and the signature method.

Then use the check_signature() method with the actual signature that was received (usually present in request.form or request.args. you can merge those in a single variable called params) to make sure that it is correct.

Get the params

if request.is_json:
    params = request.get_json()
else:
    params = request.args or request.form
is_valid = client.check_signature(params)// is it valid? Will be true or false

Using your signature secret and the other supplied parameters, the signature can be calculated and checked against the incoming signature value.

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

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={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

Number Management API

List Your Numbers

client.get_account_numbers()

Docs: https://developer.nexmo.com/api/numbers#getOwnedNumbers

Search for a Number

client.get_available_numbers('GB', {"type":"SMS"})

Docs: https://developer.nexmo.com/api/numbers#getAvailableNumbers

Buy a Number

client.buy_number({"country": 'GB', "msisdn": '447700900000'})

Docs: https://developer.nexmo.com/api/numbers#buyANumber

Cancel a Number

client.cancel_number({"country": 'GB', "msisdn": '447700900000'})

Docs: https://developer.nexmo.com/api/numbers#cancelANumber

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

Overriding API url's

By default, our API url's are hardcoded. For use cases where these url's are not accessible, best practices to override these url's are the following:

• Setting new API url's when creating an instance of the client:

import nexmo
client = nexmo.Client()
client.host = 'new.host.url'
client.api_host = 'new.api.host'

• Creating a new class that extends from client class and overrides these values in the constructor:

class MyClient(nexmo.Client):
    def __init__(self, NEXMO_API_KEY, NEXMO_API_SECRET, APPLICATION_ID, APPLICATION_PRIVATE_KEY_PATH):
        super().__init__(application_id=APPLICATION_ID, private_key=APPLICATION_PRIVATE_KEY_PATH, key=NEXMO_API_KEY, secret=NEXMO_API_SECRET)
        self.host = 'new.hosts.url'
        self.api_host = 'new.api.hosts'

#usage
client = MyClient(NEXMO_API_KEY, NEXMO_API_SECRET, APPLICATION_ID, APPLICATION_PRIVATE_KEY_PATH)

For a more specific case, another way to customise is:

import nexmo

class NexmoClient(nexmo.Client):
    def __init__(....):
        super().__init__(....)
        api_server = BasicAuthenticatedServer(
            "mycustomurl",
            user_agent=user_agent,
            api_key=self.api_key,
            api_secret=self.api_secret,
        )
        self.application_v2 = ApplicationV2(api_server)

Then proceed to create your personalised instance of the class.

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.