Skip to content
This repository was archived by the owner on Mar 1, 2023. It is now read-only.
BranchesTags
 
 

Repository files navigation

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 nexmo.com.

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

SMS Class

Creating an instance of the SMS class

To create an instance of the SMS class follow these steps:

  • Import the class
#Option 1
from nexmo import Sms

#Option 2
from nexmo.sms import Sms

#Option 3
import nexmo #then tou can use nexmo.Sms() to create an instance
  • Create an instance
#Option 1 - pass key and secret to the constructor
sms = Sms(key=NEXMO_API_KEY, secret=NEXMO_API_SECRET)

#Option 2 - Create a client instance and then pass the client to the Sms instance
client = Client(key=NEXMO_API_KEY, secret=NEXMO_API_SECRET)
sms = Sms(client)

Send an SMS

    responseData = client.send_message(
        {
            "from": NEXMO_BRAND_NAME,
            "to": TO_NUMBER,
            "text": "A text message sent using the Nexmo SMS API",
        }
    )

Reference: Send sms

Using the Sms class

from nexmo import Sms
sms = Sms(key=NEXMO_API_KEY, secret=NEXMO_API_SECRET)
sms.send_message({
            "from": NEXMO_BRAND_NAME,
            "to": TO_NUMBER,
            "text": "A text message sent using the Nexmo SMS API",
})

Support link: Send sms

Send SMS with unicode

responseData = client.send_message({
    'from': NEXMO_BRAND_NAME,
    'to': TO_NUMBER,
    'text': 'こんにちは世界',
    'type': 'unicode',
})

Reference: Send sms with unicode

Using Sms Class

sms.send_message({
    'from': NEXMO_BRAND_NAME,
    'to': TO_NUMBER,
    'text': 'こんにちは世界',
    'type': 'unicode',
})

Submit SMS Conversion

client.submit_sms_conversion("a-message-id")

With the SMS Class

from nexmo import Client, Sms
client = Client(key=NEXMO_API_KEY, secret=NEXMO_SECRET)
sms = Sms(client)
response = sms.send_message({
    'from': NEXMO_BRAND_NAME,
    'to': TO_NUMBER,
    'text': 'Hi from Vonage'
})
sms.submit_sms_conversion(response['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

with voice class

from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
voice.create_all({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})

Testing screenshots:create call

Retrieve a list of calls

response = client.get_calls()

Docs: https://developer.nexmo.com/api/voice#getCalls

with voice class

from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
voice.get_calls()

Testing screenshots: get calls

Retrieve a single call

response = client.get_call(uuid)

Docs: https://developer.nexmo.com/api/voice#getCall

with voice class

from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
voice.get_call(uuid)

Testing Screenshots: get single call

Update a call

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

Docs: https://developer.nexmo.com/api/voice#updateCall

with voice class

from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
response = voice.create_all({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})
voice.update_call(response['uuid'], action='hangup')

Support Link: update call

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

with voice class

from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
stream_url = 'https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3'
response = voice.create_call({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})
voice.send_audio(response['uuid'],stream_url=[stream_url])

Support link: Send audio stream

Stop streaming audio to a call

response = client.stop_audio(uuid)

Docs: https://developer.nexmo.com/api/voice#stopStream

Using voice class

from nexmo import Client, Voice
client = Client(application_id='0d4884d1-eae8-4f18-a46a-6fb14d5fdaa6', private_key='./private.key')
voice = Voice(client)
stream_url = 'https://nexmo-community.github.io/ncco-examples/assets/voice_api_audio_streaming.mp3'
response = voice.create_call({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})
voice.send_audio(response['uuid'],stream_url=[stream_url])
voice.stop_audio(response['uuid'])

Support Link: Stop audio stream

Send a synthesized speech message to a call

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

Docs: https://developer.nexmo.com/api/voice#startTalk

Using voice class

from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
response = voice.create_call({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})
voice.send_speech(response['uuid'], text='Hello from nexmo')

Support link: Send speech

Stop sending a synthesized speech message to a call

response = client.stop_speech(uuid)

Docs: https://developer.nexmo.com/api/voice#stopTalk

Using voice class

>>> from nexmo import Client, Voice
>>> client = Client(application_id=APPLICATION_ID, private_key=APPLICATION_ID)
>>> voice = Voice(client)
>>> response = voice.create_call({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})
>>> voice.send_speech(response['uuid'], text='Hello from nexmo')
>>> voice.stop_speech(response['uuid'])

Support link: Stop speech

Send DTMF tones to a call

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

Docs: https://developer.nexmo.com/api/voice#startDTMF

Using voice class

from nexmo import Client, Voice
client = Client(application_id=APPLICATION_ID, private_key=PRIVATE_KEY)
voice = Voice(client)
response = voice.create_call({
  'to': [{'type': 'phone', 'number': '14843331234'}],
  'from': {'type': 'phone', 'number': '14843335555'},
  'answer_url': ['https://example.com/answer']
})
voice.send_dtmf(response['uuid'], digits='1234')

Support link: Send DTMF

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

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)

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.

About

Vonage Server SDK for Python. API support for SMS, Voice, Text-to-Speech, Numbers, Verify (2FA) and more.

developer.nexmo.com

Resources

Readme
License

Code of conduct

Code of conduct

Contributing

Contributing
Activity
Custom properties

Stars

11 stars

Watchers

0 watching

Forks

9 forks
Report repository

Releases

Packages

Contributors

Languages