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

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:

git clone git@github.com:Nexmo/nexmo-python.git

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)

In order to check signatures for incoming webhook requests, you'll also need to specify the signature_secret argument (or the NEXMO_SIGNATURE_SECRET environment variable).

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://docs.nexmo.com/messaging/sms-api/api-reference#request

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)

response = client.create_call({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#call_create

response = client.get_calls()

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#call_retrieve

response = client.get_call(uuid)

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#call_retrieve_single

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

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#call_modify_single

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://docs.nexmo.com/voice/voice-api/api-reference#stream_put

response = client.stop_audio(uuid)

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#stream_delete

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

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#talk_put

response = client.stop_speech(uuid)

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#talk_delete

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

Docs: https://docs.nexmo.com/voice/voice-api/api-reference#dtmf_put

response = client.get_recording(RECORDING_URL)

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://docs.nexmo.com/verify/api-reference/api-reference#vrequest

The response contains a verification request id which you will need to store temporarily (in the session, database, url etc).

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://docs.nexmo.com/verify/api-reference/api-reference#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.

client.cancel_verification('00e6c3377e5348cdaf567e1417c707a5')

Docs: https://docs.nexmo.com/verify/api-reference/api-reference#control

client.trigger_next_verification_event('00e6c3377e5348cdaf567e1417c707a5')

Docs: https://docs.nexmo.com/verify/api-reference/api-reference#control

client.get_basic_number_insight(number='447700900000')

Docs: https://docs.nexmo.com/number-insight/basic

client.get_standard_number_insight(number='447700900000')

Docs: https://docs.nexmo.com/number-insight/standard

client.get_advanced_number_insight(number='447700900000')

Docs: https://docs.nexmo.com/number-insight/advanced

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.

python secrets = client.list_secrets(API_KEY)

Create a new secret (the created dates will help you know which is which): python 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.create_application(name='Example App', type='voice', answer_url=answer_url, event_url=event_url)

Docs: https://docs.nexmo.com/tools/application-api/api-reference#create

response = client.get_applications()

Docs: https://docs.nexmo.com/tools/application-api/api-reference#list

response = client.get_application(uuid)

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

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

Docs: https://docs.nexmo.com/tools/application-api/api-reference#update

response = client.delete_application(uuid)

Docs: https://docs.nexmo.com/tools/application-api/api-reference#delete

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

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

Docs: https://docs.nexmo.com/messaging/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)

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

This library is released under the MIT License