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
• Application API
• Coverage
• License

To install the Python client library using pip:

pip install nexmo

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

If the argument signature_method is omitted, it will default to the md5 hash algorithm. Otherwise, it will use the selected method as in md5, sha1, sha256 or sha512 with hmac.

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

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

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://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={event_id}'.format(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

response = client.create_application(name='Example App', type='voice', answer_url=answer_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


or by using signature method via POST:

client = nexmo.Client(signature_secret='secret', signature_method='sha256')

if client.check_signature(request.body.decode()):
  # 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)

• Account
  • [X] Balance
  • [X] Pricing
  • [X] Settings
  • [X] Top Up
  • [X] Numbers
    • [X] Search
    • [X] Buy
    • [X] Cancel
    • [X] Update
• Number Insight
  • [X] Basic
  • [X] Standard
  • [X] Advanced
  • [ ] Webhook Notification
• Verify
  • [X] Verify
  • [X] Check
  • [X] Search
  • [X] Control
• Messaging
  • [X] Send
  • [ ] Delivery Receipt
  • [ ] Inbound Messages
  • [X] Search
    • [X] Message
    • [X] Messages
    • [X] Rejections
  • [X] US Short Codes
    • [X] Two-Factor Authentication
    • [X] Event Based Alerts
      • [X] Sending Alerts
      • [X] Campaign Subscription Management
• Voice
  • [X] Outbound Calls
  • [ ] Inbound Call
  • [X] Text-To-Speech Call
  • [X] Text-To-Speech Prompt

This library is released under the MIT License