Welcome to Python libnexmo’s documentation!¶
Python libnexmo is a simple Python wrapper for the Nexmo api.
Philosophy¶
This library intends to be a very simple tool to use the Nexmo api in your Python project. It does not tries to pack every single one feature, but instead focus on staying minimal and efficient. If you fill something is missing, pull requests are welcome.
Compatibility¶
The library is compatible and tested against the two latest main Python version , a.k.a 2.7 and 3.4.
Example usage¶
Send a text message and print response status for each sms actually sent.
# -*- coding: utf-8 -*-
from __future__ import unicode_literals
from libnexmo import Nexmo
API_KEY = 'my_api_key'
API_SECRET = 'my_api_secret'
nexmo = Nexmo(API_KEY, API_SECRET)
frm = '+33123456789'
to = '+33987654321'
msg = 'Please remember to pick up the bread before coming'
response = nexmo.send_sms(frm, to, msg)
print response.message_count
for msg in response.messages:
print msg.status, msg.message_price
Contents¶
API Documentation¶
We are trying to map the Nexmo API as closely as possible.
Note
Since from is a reserved keyword in Python, we are using frm
instead.
Nexmo¶
-
class
libnexmo.Nexmo(api_key, api_secret)¶ Nexmo low level client.
The class is the main entry point to the library. Once initialized, it provides shortcuts to every feature in the library.
Parameters: - api_key – The Nexmo api key.
- api_secret – The Nexmo api secret.
-
send_request(url, params, method=u'GET')¶ Sends a raw request to the given api endpoint.
Parameters: - url – A Nexmpo api endpoint (json only)
- params – A parameter dictionnary
Returns a
NexmoResponse.Raises:
The library uses Requests to perform http requests. Requests exceptions won’t be caught in case of connection error.
Any
NexmoErrorsubclass.
-
send_sms(frm, to, text)¶ Sends a simple text message.
Example usage:
>>> msg = "Cherie, n'oublie pas les gauffres !" >>> nexmo.send_sms('+33123456780', '+33987654321', msg)
Parameters: - frm – The from field, a phone number (international format with or without a leading “+” or alphanumerical).
- to – The to field, a phone number, same format as the frm argument.
- text – The message body.
See
send_request()for return value and exceptions.
Note
Phone number formatting
Nexmo’s api expects phone numbers to be in international format, with the country code at the beginning and no leading “+”.
The library will therefore strip every character that is not a number, so you are free to use whatever format that you want.
Examples:
nexmo.send_sms(frm='33123456789', …)
nexmo.send_sms(frm='+33123456789', …)
nexmo.send_sms(frm='+33.123.456.789', …)
nexmo.send_sms(frm='+331 23 45 67 89', …)
nexmo.send_sms(frm='+331-23-45-67-89', …)
Response¶
-
class
libnexmo.NexmoResponse(json_data)¶ A convenient wrapper to manipulate the Nexmo json response.
The class makes it easy to retrieve information about sent messages, total price, etc.
Example:
>>> response = nexmo.send_sms(frm, to, txt) >>> print response.total_price 0.15 >>> print response.remaining_balance 1.00 >>> print response.message_count: 3 >>> for message in response.messages: ... print message.message_id, message.message_price 00000124 0.05 00000125 0.05 00000126 0.05
The class only handles successfull responses, since errors raise exceptions in the
Nexmoclass.