pybluevia documentation - media.readthedocs.org filethe procedure to get a bluevia access token is...

pyBlueVia DocumentationRelease 0.1.0

Jose Antonio Rodríguez

February 06, 2013

CONTENTS

1 Introduction 31.1 Apache2 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2 User Guide 52.1 Creating the API wrapper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Getting an access token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.3 SMS features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.4 MMS features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3 API Reference 133.1 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.2 Api class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.3 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4 Introduction 23

5 User Guide 25

6 Api Reference 27

Python Module Index 29

i

pyBlueVia Documentation, Release 0.1.0

A Python wrapper around the BlueVia API

pyBlueVia is an Apache2 Licensed library, written in Python, for making easier the usage of BlueVia API.

pyBlueVia implements an Api class which wraps the BlueVia API, offering methods for:

• Managing OAuth 2.0 authorization process for APIs which need an access token.

• Sending SMS and MMS.

• Asking for the delivery status of sent SMS/MMS.

• Retrieve SMS/MMS sent to your app.

• Parsing notifications (delivery status and incoming SMS/MMS) coming from BlueVia.

CONTENTS 1

http://bluevia.com


2 CONTENTS

CHAPTER

ONE

INTRODUCTION

1.1 Apache2 License

PyBluevia is released under terms of Apache2 License.

This basically means that, being open source, it can be used in any commercial product even when the product itselfis not open source.

1.1.1 pyBlueVia License

Copyright 2013 Telefonica Investigación y Desarrollo, S.A.U

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except incompliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is dis-tributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, eitherexpress or implied. See the License for the specific language governing permissions and limitations underthe License.

1.2 Installation

This part of the documentation covers the installation of pyBlueVia.

1.2.1 Pip

Installing pyBlueVia is simple with pip:

$ pip install pyBlueVia

1.2.2 Get the code

pyBlueVia is developed on GitHub.

You can either clone the public repository:

3

http://opensource.org/licenses/Apache-2.0

http://www.apache.org/licenses/LICENSE-2.0

http://www.pip-installer.org/

https://github.com/telefonicaid/pyBlueVia


$ git clone git://github.com/telefonicaid/pyBlueVia.git

Download the tarball:

$ curl -OL https://github.com/telefonicaid/pyBlueVia/tarball/master

Or, download the zipball:

$ curl -OL https://github.com/telefonicaid/pyBlueVia/zipball/master

Once you have a copy of the source, you can embed it in your Python package, or install it into your site-packageseasily:

$ python setup.py install

4 Chapter 1. Introduction

https://github.com/telefonicaid/pyBlueVia/tarball/master

https://github.com/telefonicaid/pyBlueVia/zipball/master

CHAPTER

TWO

USER GUIDE

2.1 Creating the API wrapper

The first step to use pyBlueVia is to create an Api object, which represents a BlueVia app, identified by the credentials(Client id and Client secret) you got from BlueVia when creating an api-key. Those credentials must be passed to theApi constructor.

import bluevia

# Get your own Client Id and Client Secret creating a new app at bluevia.comCLIENT_ID = ’634dca1685cd2d1c8c5f2577d7595c2f’CLIENT_SECRET = ’d03136863ff1a493a1f5c9a9ca8ca42e’

bluevia_client = bluevia.Api(CLIENT_ID, CLIENT_SECRET)

Althouth this is all you need to start making calls to BlueVia, some funcionalities (such as sending SMS/MMS orquering the delivery status of sent SMS/MMS) need the user permission because they are done on behalf of the user.

BlueVia uses OAuth 2.0 to manage users’ authorization, so an access token is required to to make those calls. To learnhow to get BlueVia access tokens see Getting an access token.

In the case that you already have an access token (maybe because you got it previously and stored it) you can pass itas a parameter when creating the Api object:

ACCESS_TOKEN = ’079b8f16c9a159c0d7e2fb0fcfe58d40’

bluevia_client = bluevia.Api(CLIENT_ID, CLIENT_SECRET, ACCESS_TOKEN)

Or you can set it through the access_token attribute:

bluevia_client = bluevia.Api(CLIENT_ID, CLIENT_SECRET)bluevia_client.access_token = ACCESS_TOKEN

2.2 Getting an access token

In order to call some BlueVia features that requires users’ authorization your app need an OAuth 2.0 access_token.The procedure to get a BlueVia access token is the usual OAuth dance:

1. The user is redirected to the Authorization Server web site, where she logs in, sees your app’ details, and givesher permission for your app to call BlueVia on her behalf.

2. After finishing the authorization process, the Authorization Server redirect the user to the so-called redirect uri(hosted by your app) where you receives an auth code.

5

http://tools.ietf.org/html/rfc6749

http://tools.ietf.org/html/rfc6749


3. The last step is to exchange the auth code by the access token which represent the user’s grant to access BlueViaon her behalf.

The above is the so-called “web flow” because is specially thought for web based apps, where redirections makesense. If you are making a non-web based app (desktop or native app), the second step can be modified so that theAuthorization Server does not make the redirection but shows the auth code on the screen. In this case your app hasto ask the user to enter that code. Let’s call this flow the “desktop flow”.

2.2.1 Web flow

The first step is to redirect the user to the Authorization Server. pyBlueVia helps you to build the AuthorizationServer’s URL by using the get_authorization_uri() method with the following parameters:

• scope: pyBlueVia support two scopes, which represent the BlueVia features to be authorized:

– bluevia.SMS_MT: ask for authorization to send SMS and query its delivery status.

– bluevia.MMS_MT: ask for authorization to send MMS and query its delivery status.

• redirect_uri: URL hosted by your app where the Authorization Server will redirect the user after complet-ing the authorization process.

• state: an optional app-dependant string that will be included as a query parameter in the redirect uri sent toyour app. It can be used to correlate both steps.

redirect_uri = ’https://mydomain.com:8443/authorization_response’oauth_state = str(uuid.uuid4())uri = bluevia_client.get_authorization_uri([bluevia.SMS_MT, bluevia.MMS_MT], redirect_uri, oauth_state)# Redirect to the returned uri

Once the user has been redirected to the redirect uri hosted by your app, pyBlueVia can help you to parse the queryparameters, using the parse_authorization_response() method.

This method returns the auth code along with the state (if it was included in the first step):

# ’uri’ contains the request uri received by your app as redirected from the Authorization Serveruri = ’https://mydomain.com/authorization_response?code=TANf0C&state=3829167f-7f5e-42b7-944d-469f9662e738’auth_code, state = bluevia.Api.parse_authorization_response(uri)

If this method is called with a state value as an input parameter, pyBlueVia will check that this value matches the onereceived in the URL, and raise an exception if they don’t match:

try:uri = ’https://mydomain.com/authorization_response?code=TANf0C&state=3829167f-7f5e-42b7-944d-469f9662e738’auth_code, state = bluevia.Api.parse_authorization_response(uri, ’3829167f-7f5e-42b7-944d-469f9662e738’)

except AuthResponseError:print ’state parameters do not match.’

The last step consist in exchanging the returned auth code for an access token. This is easily done with theget_access_token() method:

access_token = bluevia_client.get_access_token(auth_code)

After calling this method, the access token is also available through the access_token attribute. This access tokenrepresents the user’s authorization to use those BlueVia features covered by the requested scopes.

See Also:

A full example of how to get an access token using the web flow.

6 Chapter 2. User Guide

https://github.com/telefonicaid/pyBlueVia/blob/master/examples/getting_access_token_web.py


2.2.2 Desktop flow

The main difference between the web flow and the desktop flow is that you don’t provide a callback url when callingthe get_authorization_uri() method:

uri = bluevia_client.get_authorization_uri([bluevia.SMS_MT, bluevia.MMS_MT])

Since this is not a web app, the redirection to the Authorization Server is usually done by opening a web browserpointing at the returned uri. In this case, the Authorization Server could not redirect the user to any uri whenfinishing the authorization process, so the auth code will be shown in the browser.

The next step is to ask your user to enter such code into your app (by the means you wish). Then you can call theget_access_token() method to get the access token:

auth_code = raw_input(’Enter the auth code: ’)access_token = bluevia_client.get_access_token(auth_code)

See Also:

A full example of how to get an access token using the desktop flow.

2.3 SMS features

pyBlueVia allows you to perform the following actions regarding SMS:

• Send an SMS

• Query the delivery status of a sent SMS

• Get incomming SMS

See Also:

Full examples of how to use SMS features and how to deal with SMS notifications.

2.3.1 Sending an SMS

Sending an SMS is as easy as calling the send_sms() method passing the recipient phone number and the text tobe sent:

sms_id = bluevia_client.send_sms(to=’34600000000’, message=’Hello world!’)

This method returns an id which represents the sending, but it says nothing about whether the SMS has reached therecipient. pyBlueVia offers another method to ask for the delivery status of a sent SMS.

Note: This feature requires an access token.

2.3.2 Quering the delivery status of a sent SMS

There are two ways of getting information about the delivery status of a sent SMS:

• Polling: You explicitly ask for the delivery status using the id got when sending the SMS.

• Notifications: BlueVia sends to your app a notification with the delivery status information.

2.3. SMS features 7

https://github.com/telefonicaid/pyBlueVia/blob/master/examples/getting_access_token_desktop.py

https://github.com/telefonicaid/pyBlueVia/blob/master/examples/using_bluevia_api.py

https://github.com/telefonicaid/pyBlueVia/blob/master/examples/using_bluevia_api_notifications.py


Polling

You can ask for the delivery status of a sent SMS calling the get_sms_delivery_status() method passing theid got when sending the SMS. This method returns a dictionary with the recipient phone number and the status of thesent SMS:

>>> delivery_status = bluevia_client.get_sms_delivery_status(sms_id)>>> print delivery_status{u’status’: u’delivered’, u’address’: u’34600000000’}


Notifications

If you want to receive SMS delivery status notifications from BlueVia the first step is telling BlueVia where to sendthose notifications. This is done at the time of sending the SMS, passing an additional parameter (callback_url)with an URL hosted by your app where delivery status notifications will be processed:

callback_url = ’https://mydomain.com:8443/delivery_status’bluevia_client.send_sms(to=’34600000000’, message=’Hello world!’, callback_url=callback_url)

Then BlueVia will send a notification to that URL. These notifications can be parsed by pyBlueVia using theparse_delivery_status() method, passing the Content-Type HTTP header value together with the bodyof the received HTTP request:

>>> delivery_status = bluevia.Api.parse_delivery_status(content_type, content)>>> print delivery_status{u’status’: u’delivered’, u’id’: u’97286813874922402286’, u’address’: u’34600000000’}

In this case the returned dictionary also includes an id field with the same value returned by send_sms().

2.3.3 Getting incoming SMS

Each time someone sends an SMS to a BlueVia short number using your app keyword as the first word in the text, thatSMS is available for being queried by your app. There are two ways of getting incoming SMS:

• Polling: You explicitly ask for the available incoming SMS.

• Notifications: BlueVia sends to your app a notification each time an SMS is available.

Polling

In order to ask BlueVia for incoming SMS for your app, simply call the get_incoming_sms() method. It returnsa list of dictionaries (one per SMS) with the following SMS data:

• id: Unique identifier representing this incoming SMS.

• from: phone number from which the SMS was sent.

• obfuscated: a bool indicating whether the from is obfuscated or not (see warning below).

• to: short number to which the SMS was sent.

• message: SMS text, including the keyword.

• timestamp: date and time of when the SMS was sent, represented as a Python datetime object.


http://bluevia.com/en/page/tech.overview.shortcodes

http://docs.python.org/2/library/datetime.html#datetime.datetime


>>> sms = bluevia_client.get_incoming_sms()>>> print sms{u’obfuscated’: False, u’from’: u’34600000000’, u’timestamp’: datetime.datetime(2012, 12, 27, 16, 17, 42, 418000), u’to’: u’34217040’, u’message’: u’keyword Hello world!’, u’id’: u’97286813874922402286’}

Note that once BlueVia has returned a set of incoming SMS, they are deleted from theserver, so each call to get_incoming_sms() always returns new SMS (if any).

Warning: Due to privacy reasons, some countries do not allow apps to see the phone number from which theSMS has been sent. In those cases BlueVia returns an obfuscated identity which uniquely (and anonymously)represents the sender, and even can be used as a receipt when sending SMS. The obfuscated flag in theget_incoming_sms() response indicates whether the from identity is obfuscated or not.

Notifications

If you want to receive a notification each time an SMS with your keyword is sent to a BlueVia short number, the firststep is to edit your api-key at http://bluevia.com to configure the URL where your app will be listening to notifications.

These notifications can be parsed by pyBlueVia to extract the incoming SMS information using theparse_incoming_sms() method, passing the Content-Type HTTP header value together with the body ofthe received HTTP request:

>>> sms = bluevia.Api.parse_incoming_sms(content_type, content)>>> print sms{u’obfuscated’: False, u’from’: u’34600000000’, u’timestamp’: datetime.datetime(2012, 12, 27, 16, 17, 42, 418000), u’to’: u’34217040’, u’message’: u’keyword Hello world!’, u’id’: u’97286813874922402286’}

The returned dictionary is exactly the same that each element of the list returned by get_incoming_sms().

2.4 MMS features

pyBlueVia allows you to perform the following actions regarding MMS:

• Send an MMS

• Query the delivery status of a sent MMS

• Get incomming MMS

See Also:

Full examples of how to use MMS features and how to deal with MMS notifications.

2.4.1 Sending an MMS

In order to send an MMS you must call the send_mms() method with the following parameters:

• to: the receipt phone number.

• subject: the MMS subject.

• attachments: a list of attachments to be sent inside the MMS. Each attachment can be:

– A string, if the attachment is textual content.

– A file-like object.

– A tuple with two elements:

* A string with the attachment’s content type.

2.4. MMS features 9

http://bluevia.com

https://github.com/telefonicaid/pyBlueVia/blob/master/examples/using_bluevia_api.py

https://github.com/telefonicaid/pyBlueVia/blob/master/examples/using_bluevia_api_notifications.py


* The attachment’s binary content.

mms_id = bluevia_client.send_mms(to=’34600000000’, subject=’Hello world!’,attachments=(’Look at this pictures’,

open(’picture.gif’, ’rb’),(’image/gif’, ’GIF89a[...]’)))

This method returns an id which represents the sending, but it says nothing about whether the MMS has reached therecipient. pyBlueVia offers another method to ask for the delivery status of a sent MMS.


2.4.2 Quering the delivery status of a sent MMS

There are two ways of getting information about the delivery status of a sent MMS:

• Polling: You explicitly ask for the delivery status using the id got when sending the MMS.

• Notifications: BlueVia sends to your app a notification with the delivery status information.

Polling

You can ask for the delivery status of a sent MMS calling the get_mms_delivery_status() method passingthe id got when sending the MMS. This method returns a dictionary with the recipient phone number and the statusof the sent MMS:

>>> delivery_status = bluevia_client.get_mms_delivery_status(sms_id)>>> print delivery_status{u’status’: u’delivered’, u’address’: u’34600000000’}


Notifications

If you want to receive MMS delivery status notifications from BlueVia the first step is telling BlueVia where to sendthose notifications. This is done at the time of sending the MMS, passing an additional parameter (callback_url)with an URL hosted by your app where delivery status notifications will be processed:

callback_url = ’https://mydomain.com:8443/delivery_status’mms_id = bluevia_client.send_mms(to=’34600000000’, subject=’Hello world!’, callback_url=callback_url,

attachments=(’Look at this pictures’,open(’picture.gif’, ’rb’),(’image/gif’, ’GIF89a[...]’)))

Then BlueVia will send a notification to that URL. These notifications can be parsed by pyBlueVia using theparse_delivery_status() method, passing the Content-Type HTTP header value together with the bodyof the received HTTP request:

>>> delivery_status = bluevia.Api.parse_delivery_status(content_type, content)>>> print delivery_status{u’status’: u’delivered’, u’id’: u’97286813874922402286’, u’address’: u’34600000000’}

In this case the returned dictionary also includes an id field with the same value returned by send_mms().



2.4.3 Getting incoming MMS

Each time someone sends an MMS to a BlueVia short number using your app keyword as the first word in the subject(or in the first textual attachment), that MMS is available for being queried by your app. There are two ways of gettingincoming MMS:

• Polling: You explicitly ask for the available incoming MMS.

• Notifications: BlueVia sends to your app a notification each time an MMS is available.

Polling

In order to ask BlueVia for incoming MMS for your app, simply call the get_incoming_mms() method, which re-turns a list of MMS ids. Then to retrieve each MMS content, you must call the get_incoming_mms_details()method, passing an MMS id as parameter. This method returns a dictionary with the following keys:

• id: Unique identifier representing this incoming MMS.

• from: phone number from which the MMS was sent.

• obfuscated: a bool indicating whether the from is obfuscated or not (see warning below).

• to: short number to which the MMS was sent.

• subject: MMS subject, including the keyword.

• timestamp: date and time of when the MMS was sent, represented as a Python datetime object.

• attachments: an array of tuples (one per attachment) containing:

– the attachment’s content type.

– the attachment’s binary content.

>>> mms_list = bluevia_client.get_incoming_mms()>>> mms = bluevia_client.get_incoming_mms_details(mms_list[0])>>> print mms{u’obfuscated’: False, u’from’: u’34600000000’, u’attachments’: [(’text/plain’, ’Look at this picture’), (’image/gif’, ’GIF89a[...]’)], u’timestamp’: datetime.datetime(2012, 12, 28, 10, 39, 5, 242000), u’to’: u’34217040’, u’id’: u’2515357468066729’, u’subject’: u’keyword Photo’}

Note that once BlueVia has returned a set of incoming MMS, they are deleted from theserver, so each call to get_incoming_mms() always returns new MMS (if any).

Warning: Due to privacy reasons, some countries do not allow apps to see the phone number from which theMMS has been sent. In those cases BlueVia returns an obfuscated identity which uniquely (and anonymously)represents the sender, and even can be used as a receipt when sending MMS. The obfuscated flag in theget_incoming_mms() response indicates whether the from identity is obfuscated or not.

Notifications

If you want to receive a notification each time an MMS with your keyword is sent to a BlueVia short number, the firststep is to edit your api-key at http://bluevia.com to configure the URL where your app will be listening to notifications.

These notifications can be parsed by pyBlueVia to extract the incoming MMS information using theparse_incoming_mms() method, passing the Content-Type HTTP header value together with the body ofthe received HTTP request:

>>> mms = bluevia.Api.parse_incoming_mms(content_type, content)>>> print mms{u’obfuscated’: False, u’from’: u’34600000000’, u’attachments’: [(’text/plain’, ’Look at this picture’), (’image/gif’, ’GIF89a[...]’)], u’timestamp’: datetime.datetime(2012, 12, 28, 10, 39, 5, 242000), u’to’: u’34217040’, u’id’: u’2515357468066729’, u’subject’: u’keyword Photo’}

2.4. MMS features 11

http://bluevia.com/en/page/tech.overview.shortcodes

http://docs.python.org/2/library/datetime.html#datetime.datetime

http://bluevia.com


The returned dictionary is exactly the same returned by get_incoming_mms_details().


CHAPTER

THREE

API REFERENCE

Find here the detailed description of pyBlueVia classes, methods and exceptions.

3.1 Summary

Api(client_id, client_secret[, ...]) This is the main pyBlueVia class, which wraps the BlueVia API.Api.client_id OAuth client id set when creating the Api object (read only).Api.client_secret OAuth client secret set when creating the Api object (read only).Api.access_token OAuth access token provided when creating the Api object, or fetched throughApi.get_authorization_uri(scope[, ...]) Build the OAuth authorization URI.Api.parse_authorization_response(uri[, ...]) Parse the OAuth authorization response and returns the Authorization Code and State.Api.get_access_token(authorization_code[, ...]) Exchange the given authorization code for an access token.Api.send_sms(to, message[, callback_url]) Send an SMS.Api.get_sms_delivery_status(sms_id) Ask for the delivery status of a sent SMS.Api.parse_delivery_status(content_type, content) Parse a delivery status notification sent by BlueVia to your app.Api.get_incoming_sms() Get the list of incoming SMS that have not been retrieved yet.Api.parse_incoming_sms(content_type, content) Parse an SMS notification sent by BlueVia to your app.Api.send_mms(to, subject, attachments[, ...]) Send a MMS.Api.get_mms_delivery_status(mms_id) Ask for the delivery status of a sent MMS.Api.get_incoming_mms() Get the list of incoming MMS that have not been retrieved yet.Api.get_incoming_mms_details(mms_id) Get the content (metadata and attachment) of an incoming MMS.Api.parse_incoming_mms(content_type, content) Parse a MMS notification sent by BlueVia to your app.

3.2 Api class

class bluevia.Api(client_id, client_secret[, access_token, sandbox=False])This is the main pyBlueVia class, which wraps the BlueVia API.

The first step to use pyBlueVia is to create an Api object.

Parameters

• client_id – OAuth 2.0 client id.

• client_secret – OAuth 2.0 client secret.

• access_token – (optional) OAuth 2.0 access token needed to send sms and mms orto get their delivery status. If not provided here it can be set later setting the

13


attribute access_token or during the OAuth authorization process when callingget_access_token().

• sandbox (bool) – (optional) set to True in order to use the BlueVia Sandbox feature. De-fault is False.

Usage:

>>> import bluevia>>> bluevia_client = bluevia.Api(CLIENT_ID, CLIENT_SECRET, ACCESS_TOKEN)>>> bluevia_client.send_sms(to=’34600000000’, message=’Hello world!’)

client_idOAuth client id set when creating the Api object (read only).

client_secretOAuth client secret set when creating the Api object (read only).

access_tokenOAuth access token provided when creating the Api object, or fetched throughget_access_token(). It can also be set assigning a value to this attribute.

get_authorization_uri(scope[, redirect_uri[, state]])Build the OAuth authorization URI.

As a first step to get an access token (needed to call some of the BlueVia APIs) the user must be redirectedto the Authorization Server, where she will authorize your app to make such calls on her behalf. The URIwhere the user must be redirected is built by this method based on the input parameters.

Parameters

• scope – scope (or array/tuple of scopes) for which the authorization is requested. Sup-ported scope values are: bluevia.SMS_MT and bluevia.MMS_MT which ask forpermission to send SMS and MMS, respectively (and ask for the delivery status).

• redirect_uri – (optional) following the OAuth dance, after completing the authorization,the user will be redirected to this URI (hosted by your app) including query parametersthat could be parsed by parse_authorization_response() as a previous step toget the access token. If this parameter is not provided, the Authorization Server will showan authorization code that the user must provide to your app to continue with the processof getting the access token.

• state – (optional) if provided, the Authorization Server will include it in the redirect uriand will be returned by parse_authorization_response(). It may be used tocorrelate authorization requests with their responses.

Returns The authorization URI.

Usage:

>>> import bluevia>>> bluevia_client = bluevia.Api(CLIENT_ID, CLIENT_SECRET)>>> uri = bluevia_client.get_authorization_uri([bluevia.SMS_MT, bluevia.MMS_MT],... ’https://mydomain.com/authorization_response’,... ’3829167f-7f5e-42b7-944d-469f9662e738’)>>> print urihttps://id.tu.com/authorize?scope=sms.send+mms.send&state=3829167f-7f5e-42b7-944d-469f9662e738&redirect_uri=https%3A%2F%2Fmydomain.com%2Fauthorization_response&response_type=code&client_id=634dca1685cd2d1c8c5f2577d7595c2f

See Also:

OAuth 2.0 specification: Authorization Request.

14 Chapter 3. API Reference

http://tools.ietf.org/html/rfc6749#section-4.1.1


static parse_authorization_response(uri[, state_to_check ])Parse the OAuth authorization response and returns the Authorization Code and State.

If a redirect uri parameter was provided to get_authorization_uri(), the Authorization Serverredirect the user to that URI including the result of the authorization process as query parameters. Thismethod will parse that URI and returns the authorization code needed to get the access token and the stateprovided to get_authorization_uri(), if any.

Parameters

• uri – the URI where the Authorization Server redirected the user after the authorizationprocess.

• state_to_check – (optional) if provided, this value will be checked against the value in-cluded in the parsed URI, if any. If they don’t match a AuthResponseError exceptionwill be raised.

Returns The authorization code to be used to call get_access_token(), or a tuple con-taining the authorization code and the state if it was included in the parsed URI.

Usage:

>>> import bluevia>>> bluevia_client = bluevia.Api(CLIENT_ID, CLIENT_SECRET)>>> uri = ’https://mydomain.com/authorization_response?code=TANf0C&state=3829167f-7f5e-42b7-944d-469f9662e738’>>> auth_code, state = bluevia_client.parse_authorization_response(uri)>>> print auth_codeTANf0C

See Also:

OAuth 2.0 specification: Authorization Response.

get_access_token(authorization_code[, redirect_uri])Exchange the given authorization code for an access token.

Parameters

• authorization_code – the authorization code returned byparse_authorization_response() or provided to your app by other means (forthose apps not providing a redirect uri parameter to get_authorization_uri()).

• redirect_uri – (optional) if provided, it must be the same passed toget_authorization_uri(). If not provided pyBlueVia remembers the onepassed to get_authorization_uri(), if any.

Returns The access token to be used to call BlueVia APIs, valid for the requested scopes. Thereturned access token is also stored in the access_token attribute.

Usage:

>>> import bluevia>>> bluevia_client = bluevia.Api(CLIENT_ID, CLIENT_SECRET)>>> access_token = bluevia_client.get_access_token(’TANf0C’)>>> print access_token079b8f16c9a159c0d7e2fb0fcfe58d40

See Also:

OAuth 2.0 specification: Access Token Request and Access Token Response.

send_sms(to, message[, callback_url])Send an SMS.

3.2. Api class 15





Parameters

• to – the phone number (or obfuscated identity) to where the SMS will be sent.

• message – the SMS text.

• callback_url – (optional) if included, BlueVia will send delivery status notifications tothat URL, that could be parsed using parse_delivery_status().

Returns A unique id representing the sent SMS. It can be used to callget_sms_delivery_status().

Note: This method needs an access token.

Usage:

>>> import bluevia>>> bluevia_client = bluevia.Api(CLIENT_ID, CLIENT_SECRET, ACCESS_TOKEN)>>> sms_id = bluevia_client.send_sms(to=’34600000000’, message=’Hello world!’,... callback_url=’https://mydomain.com/delivery_status’)

get_sms_delivery_status(sms_id)Ask for the delivery status of a sent SMS.

Parameters sms_id – the SMS id returned by send_sms().

Returns

A dictionary with the following keys:

• address: phone number (or obfuscated identity) to which the message was sent.

• status: delivery status.


Usage:

>>> import bluevia>>> bluevia_client = bluevia.Api(CLIENT_ID, CLIENT_SECRET, ACCESS_TOKEN)>>> sms_id = bluevia_client.send_sms(to=’34600000000’, message=’Hello world!’)>>> delivery_status = bluevia_client.get_sms_delivery_status(sms_id)>>> print delivery_status{u’status’: u’delivered’, u’address’: u’34600000000’}

static parse_delivery_status(content_type, content)Parse a delivery status notification sent by BlueVia to your app.

When sending an SMS or MMS, if the parameter callback_url is provided, BlueVia will send deliverystatus notifications to that URL. You should implement an HTTP server that listen to that URL to receivethese notifications.

Parameters

• content_type – the Content Type of the request sent by BlueVia to the callback URL.

• content – the entire body of the request sent by BlueVia to the callback URL.

Returns


• id: SMS/MMS id (the same returned when sending the message).





Usage:

>>> import bluevia>>> delivery_status = bluevia.Api.parse_delivery_status(content_type, content)>>> print delivery_status{u’status’: u’delivered’, u’id’: u’97286813874922402286’, u’address’: u’34600000000’}

get_incoming_sms()Get the list of incoming SMS that have not been retrieved yet.

Incoming SMS are those sent to a BlueVia short number using your app’s keyword as the first word in thetext. Once those SMS has been retrieved they are deleted from the server.

Returns

A list of dictionaries (one per SMS) with the following keys:

• id: SMS id.

• from: phone number (or obfuscated identity) from which the SMS was sent.

• obfuscated: a bool indicating whether the from is obfuscated or not.



• timestamp: date and time of when the SMS was sent.

If there are no incoming SMS to be returned, this method returns an empty list.

Usage:

>>> import bluevia>>> bluevia_client = bluevia.Api(CLIENT_ID, CLIENT_SECRET)>>> sms_list = bluevia_client.get_incoming_sms()>>> print sms_list[{u’obfuscated’: False, u’from’: u’34600000000’, u’timestamp’: datetime.datetime(2012, 12, 27, 16, 17, 42, 418000), u’to’: u’34217040’, u’message’: u’keyword First SMS’, u’id’: u’97286813874922402286’},{u’obfuscated’: False, u’from’: u’34600000000’, u’timestamp’: datetime.datetime(2012, 12, 27, 16, 18, 26, 845000), u’to’: u’34217040’, u’message’: u’keyword Second SMS’, u’id’: u’87728496828692402123’}]

static parse_incoming_sms(content_type, content)Parse an SMS notification sent by BlueVia to your app.

You can configure BlueVia to send incoming SMS notifications to your app at bluevia.com, providing aURL and (optionally) the server certificate you use to listen to BlueVia.

Parameters

• content_type – the Content Type of the request sent by BlueVia to the provisioned URL.Both application/json and application/xml are supported.

• content – the entire body of the request sent by BlueVia to the provisioned URL.

Returns


• id: SMS id.

• from: phone number (or obfuscated identity) from which the SMS was sent.


3.2. Api class 17




• timestamp: date and time of when the SMS was sent.

Usage:

>>> import bluevia>>> sms = bluevia.Api.parse_incoming_sms(content_type, content)>>> print sms{u’obfuscated’: False, u’from’: u’34600000000’, u’timestamp’: datetime.datetime(2012, 12, 27, 16, 17, 42, 418000), u’to’: u’34217040’, u’message’: u’keyword Hello world!’, u’id’: u’97286813874922402286’}

send_mms(to, subject, attachments[, callback_url])Send a MMS.

Parameters

• to – the phone number (or obfuscated identity) to where the MMS will be sent.

• subject – the MMS subject.

• attachments – a list of attachments to be sent inside the MMS. Each attachment can be:

– A string, if the attachment is textual content.

– A file-like object.

– A tuple with two elements:

* A string with the attachment’s content type.

* The attachment’s binary content.

• callback_url – (optional) if included, BlueVia will send delivery status notifications tothat URL, that could be parsed using parse_delivery_status().

Returns A unique id representing the sent MMS. It can be used to callget_mms_delivery_status().


Usage:

>>> import bluevia>>> bluevia_client = bluevia.Api(CLIENT_ID, CLIENT_SECRET, ACCESS_TOKEN)>>> mms_id = bluevia_client.send_mms(to=’34600000000’, subject=’Hello world!’,... callback_url=’https://mydomain.com/delivery_status’,... attachments=(’Look at this pictures’,... open(’picture.gif’, ’rb’),... (’image/gif’, ’GIF89a[...]’)))

get_mms_delivery_status(mms_id)Ask for the delivery status of a sent MMS.

Parameters mms_id – the MMS id returned by send_mms().

Returns







Usage:

>>> import bluevia>>> bluevia_client = bluevia.Api(CLIENT_ID, CLIENT_SECRET, ACCESS_TOKEN)>>> mms_id = bluevia_client.send_mms(to=’34600000000’, subject=’Hello world!’,... callback_url=’https://mydomain.com/delivery_status’,... attachments=(’Look at this pictures’,... open(’picture.gif’, ’rb’),... (’image/gif’, ’GIF89a[...]’)))>>> delivery_status = bluevia_client.get_mms_delivery_status(mms_id)>>> print delivery_status{u’status’: u’delivered’, u’address’: u’34600000000’}

get_incoming_mms()Get the list of incoming MMS that have not been retrieved yet.

Incoming MMS are those sent to a BlueVia short number using your app’s keyword as the first word inthe subject (or in the first text attachment). Once those MMS has been retrieved they are deleted from theserver.

Returns A list of MMS id. The actual content of each MMS must be retrieved withget_incoming_mms_details().

If there are no incoming MMS to be returned, this method returns an empty list.

Usage:

>>> import bluevia>>> bluevia_client = bluevia.Api(CLIENT_ID, CLIENT_SECRET)>>> mms_list = bluevia_client.get_incoming_mms()>>> print mms_list[u’97286813874922402286’,u’87728496828692402123’]

get_incoming_mms_details(mms_id)Get the content (metadata and attachment) of an incoming MMS.

Parameters mms_id – the MMS id returned by get_incoming_mms().

Returns


• id: MMS id.

• from: phone number (or obfuscated identity) from which the MMS was sent.




• timestamp: date and time of when the MMS was sent.


– the attachment’s content type.

– the attachment’s binary content.

Usage:

3.2. Api class 19


>>> import bluevia>>> bluevia_client = bluevia.Api(CLIENT_ID, CLIENT_SECRET)>>> mms_list = bluevia_client.get_incoming_mms()>>> mms = bluevia_client.get_incoming_mms_details(mms_list[0])>>> print mms{u’obfuscated’: False, u’from’: u’34600000000’, u’attachments’: [(’text/plain’, ’Look at this picture’), (’image/gif’, ’GIF89a[...]’)], u’timestamp’: datetime.datetime(2012, 12, 28, 10, 39, 5, 242000), u’to’: u’34217040’, u’id’: u’2515357468066729’, u’subject’: u’keyword Photo’}

static parse_incoming_mms(content_type, content)Parse a MMS notification sent by BlueVia to your app.

You can configure BlueVia to send incoming MMS notifications to your app at bluevia.com, providing aURL and (optionally) the server certificate you use to listen to BlueVia.

Parameters

• content_type – the Content Type of the request sent by BlueVia to the provisionedURL.

• content – the entire body of the request sent by BlueVia to the provisioned URL(including the MIME attachments).

Returns


• id: MMS id.

• from: phone number (or obfuscated identity) from which the MMS was sent.




• timestamp: date and time of when the MMS was sent.


– the Content-Type of the attachment.

– the attachment itself.

Usage:

>>> import bluevia>>> mms = bluevia.Api.parse_incoming_mms(content_type, content)>>> print mms{u’obfuscated’: False, u’from’: u’34600000000’, u’attachments’: [(’text/plain’, ’Look at this picture’), (’image/gif’, ’GIF89a[...]’)], u’timestamp’: datetime.datetime(2012, 12, 28, 10, 39, 5, 242000), u’to’: u’34217040’, u’id’: u’2515357468066729’, u’subject’: u’keyword Photo’}

3.3 Exceptions

exception bluevia.BVExceptionThe base pyBlueVia exception from which other exceptions inherit. It can be used to catch any pyBlueViaexception.

exception bluevia.APIErrorBlueVia has returned an API exception. Details can be got through the following attributes:

http_status_code = Nonethe HTTP status code returned by BlueVia.



http_reason = Nonea description (if available) of the HTTP status code.

id = Nonethe exception id as returned by BlueVia (it might be None).

message = Nonethe exception description as returned by BlueVia.

exception bluevia.ContentTypeErrorUnsupported Content-Type.

exception bluevia.AccessTokenErrorTrying to call a method which needs access token and it has not been set.

exception bluevia.AuthResponseErrorAn error occurred trying to parse the URI to which the Authorization Server redirects after finishing the autho-rization process.

3.3. Exceptions 21

CHAPTER

FOUR

INTRODUCTION

• Apache2 License

• Installation

23


24 Chapter 4. Introduction

CHAPTER

FIVE

USER GUIDE

• Creating the API wrapper

• Getting an access token

• SMS features

• MMS features

25

CHAPTER

SIX

API REFERENCE

• Summary

• Api class

• Exceptions

27


28 Chapter 6. Api Reference

PYTHON MODULE INDEX

bbluevia, 13

29

pybluevia documentation - media.readthedocs.org filethe procedure to get a bluevia access token is...

Documents