This chapter is about understanding how to use the python classes.
After importing the bluevia package the first step is to initialize a BlueVia oAuth object with the Consumer credentials from the BlueVia application generation (see above):
>>> import bluevia
>>> o = bluevia.BlueViaOauth('yT11072616762766', 'hofF15263457')
Then we need to get the oAuth Request Token:
>>> o.fetch_request_token()
(200, 'https://connect.bluevia.com/authorise?oauth_token=14a1dc2ca3e94fae00776f7affabec1')
The result is a tuple containing the HTTP status code of the current request (200 = success) and the oAuth authorization URL. On the web page behind this URL the customer needs to authorize that the appliction can call BlueVia on his behalf. This currently involves 4 steps:
a) The customer gets information about this application and needs to press Continue
b) The customer then needs to login into BlueVia (assumed he had already registered earlier). During the test phase BlueVia developers only can access the radio networks vie the application. Hence you should login with your developer credentials to follow this tutorial.
c) The customer explicitely authorizes the application to use BlueVia API’s on his behalf. For commercial applications he would see the price af the charged APIs in this view.
d) The authorization gets confirmed by the BlueVia platform and a oAuth verifier is generated and shown (here 648748).
Notes:
Last step is to exchange the oAuth Request Token with the oAuth Access Token that finally allows your app to act on behalf the customer.
>>> o.fetch_access_token("648748")
200
Done! Since the HTTP request code is 200, we have received successfully the oAuth Access Token. In order to reuse this token we need to save it
>>> o.saveAccessToken("Tutorial.pkl")
Note: This routine stores all credentials in unencrypted format. While this is fine for the tutorial, this should never be done in a commercial application! Use getConsumer() and getAccessToken() and their counterparts setConsumer() and setAccessToken() instead with your secure storage routines.
>>> s = bluevia.BlueViaOutboundSms()
>>> s.loadAccessToken("Tutorial.pkl")
True
>>> r = s.sendSMS(["44776_6_4_9_"], "Hello BlueVia")
>>> r
(201,
'https://api.bluevia.com/services/REST/SMS_Sandbox/outbound/requests/
10001107271733589985821123953097/deliverystatus')
After initializing the BlueViaOutboundSMS object we need to add the oAuth credentials to it. This will be done throughout the tutorial with the function loadAccessToken(). Sending the SMS then takes just a list of mobile numbers (recipients, one or more, obfuscated here) and the actual SMS message.
The result parameter 201 shows success and the URL allows to track the delivery status
>>> trackUrl = r[1]
>>> s.deliveryStatus(trackUrl)
{'smsDeliveryStatus': [
{'address':
{'phoneNumber': '44776_6_4_9_'},
'deliveryStatus': 'DeliveredToTerminal'
}
]}
The status shows that the SMS is delivered to the terminal.
Note: If you have added your own mobile number to the call, you might wonder why you didn’t receive an SMS. You are just in the Sandbox! No real network call will happen. Would you instead use
>>> s = bluevia.BlueViaOutboundSms(sandbox="")
>>> s.loadAccessToken("Tutorial.pkl")
then the SMS would have reached your terminal (as long as you have free developer SMS credits)
Usage of the BlueVia location API follows - exactly like the other API’s - the approach of sending SMS. Initiate the Location object (this time with real access to the network to locate your terminal. Remember, location is free of charge in UK, so no need to play in sandbox to save free credits. Nevertheless, as a rule of thumb, use the real mobile network only when necesary to save resources).
Load the credentials of the oAuth Dance and request your terminal’s location:
>>> l = bluevia.BlueViaLocation(sandbox="")
>>> l.loadAccessToken("Tutorial.pkl")
True
>>> l.locateTerminal()
(200,
{'terminalLocation': {
'reportStatus': 'Retrieved',
'currentLocation': {
'timestamp': '2011-07-28T10:52:18',
'coordinates': {
'latitude': '51.524978',
'longitude': '-0.087268'
},
'accuracy': '538'
},
'locatedParty': {
'alias': '309d757356bde464b8469aeff133346d'
}
}})
The relevant parts here are latitude, longitude and accuracy (The output again is pretty printed).
Note: The value behind “alias” is the Access Token derived in the oAuth Dance. This token is usually used to identify the customer in BlueVia calls instead of his mobile number. The BlueVia platform maps Access Token to Mobile Number.
Send SMS and track delivery
s = bluevia.BlueViaOutboundSms()
s.loadAccessToken("Tutorial.pkl")
r = s.sendSMS(["447763654962"], "Hello BlueVia")
s.deliveryStatus(r[1])
Receive SMS (first send one or more SMS to the sandbox shortcode)
s.sendSMS(["445480605"], "SANDBWTUT01 BlueVia")
si = bluevia.BlueViaInboundSMS()
si.loadAccessToken("Tutorial.pkl")
si.receiveSMS("445480605")
Send MMS
m = bluevia.BlueViaOutboundMms()
m.loadAccessToken("Tutorial.pkl")
m.sendMMS("447762654962", "Hello Multimedia BlueVia", \
["Message\n Number 1", "Yet another\n Message"], \
["samples/atextfile.txt", "samples/image.jpg"])
Receive MMS and retrieve the attachemnts (first send one or more MMS to the sandbox shortcode)
m.sendMMS("445480605", "SANDBWTUT01 BlueVia Multimedia", \
["Message\n Number 1", "Yet another\n Message"], \
["samples/atextfile.txt", "samples/image.jpg"])
mi = bluevia.BlueViaInboundMMS()
mi.loadAccessToken("Tutorial.pkl")
r = mi.receiveMMS("445480605")
mid = r[1]['receivedMessages']['messageIdentifier']
mi.retrieveAttachments("445480605", mid)
User Context API
u = bluevia.BlueViaUserContext()
u.loadAccessToken("Tutorial.pkl")
u.getUserInfo()
Location API
l = bluevia.BlueViaLocation()
l.loadAccessToken("Tutorial.pkl")
l.locateTerminal()
Advertising API (3 legged oAuth)
a = bluevia.BlueViaAds("10977")
a.loadAccessToken("Tutorial.pkl")
a.getAd_3l()
Advertising API (2 legged oAuth)
o = bluevia.BlueViaOauth('zc11071902739459', 'ttGU85551435')
o.fetch_request_token()
o.saveAccessToken("Tutorial_2_legged.pkl") # saves Request Token only!
a = bluevia.BlueViaAds("10977")
a.loadAccessToken("Tutorial_2_legged.pkl") # Request Token only!
a.getAd_2l("GB")