This chapter assumes that the oAuth Dance has been successfully finished and focusses on calling the BlueVia API’s. Every API is described by explaining the parameters of the _signAndSend() function introduced in 3.1.
Input for _signAndSend(…)
requestUrl | https://api.bluevia.com/services/REST/SMS_Sandbox/outbound/requests |
method | POST |
token | Access Token and Secret |
parameters | {“version”:“v1”, “alt”:“json”} |
body | { “smsText”: { |
“message”: “Hello BlueVia”, | |
“originAddress”: { | |
“alias”: “493c2c9316b2c75e2766c97477450b13” | |
}, | |
“address”: { | |
“phoneNumber”: “447763654962” | |
}}} | |
extraHeaders | {‘Content-Type’: ‘application/json;charset=UTF8’} |
is_form_encoded | False |
Output of _signAndSend(…)
response["status"] = 201
response["location"] =
https://api.bluevia.com/services/REST/SMS_Sandbox/outbound/requests/
10001107290844296249296459706713/deliverystatus
content =
The HTTP status for success is 201. The URL to track the SMS delivery will be returned as the response header “location”. There is no content in the response to this request.
Input for _signAndSend(…)
requestUrl | https://api.bluevia.com/services/REST/SMS_Sandbox/outbound/requests/ |
10001107290844296249296459706713/deliverystatus | |
method | GET |
token | Access Token and Secret |
parameters | {“version”:“v1”, “alt”:“json”} |
body | "" |
extraHeaders | {} |
is_form_encoded | False |
The request URL is the tracking URL given back by the Send SMS API.
Output of _signAndSend(…)
response["status"] = 200
content =
{"smsDeliveryStatus":{
"smsDeliveryStatus":[
{"address":{"phoneNumber":"447763654962"},
"deliveryStatus":"DeliveredToTerminal"} ] } }
Note In the sandbox the delivery receipt only covers one recipient. In the real radio network you will receive a delivery receipt containing all recipients
Input for _signAndSend(…)
requestUrl | https://api.bluevia.com/services/REST/MMS_Sandbox/outbound/requests |
method | POST |
token | Access Token and Secret |
parameters | {“version”:“v1”, “alt”:“json”} |
body | –xPyeiBhGKAieLXuNeFUkLlSechFZBIJfL |
Content-Disposition: form-data; name=“root-fields” | |
Content-Type: application/json;charset=UTF–8 | |
Content-Transfer-Encoding: 8bit | |
{“message”: {“address”: {“phoneNumber”:“447762654962”}, | |
“subject”: “Hello Multimedia BlueVia”, | |
“originAddress”: {“alias”: “493c2c9316b2c75e2766c97477450b13”}}} | |
–xPyeiBhGKAieLXuNeFUkLlSechFZBIJfL | |
Content-Disposition: form-data; name=“attachments” | |
Content-Type: multipart/mixed; boundary=aFBZGYGFxeRbbvjrvqbQVEhBvrNiteCIx | |
… all the attachments are encoded here … | |
–aFBZGYGFxeRbbvjrvqbQVEhBvrNiteCIx– | |
–xPyeiBhGKAieLXuNeFUkLlSechFZBIJfL– | |
extraHeaders | {“Content-Length”: “43585”, |
“Content-Type”: “multipart/form-data; boundary=xPyeiBhGKAieLXuNeFUkLlSechFZBIJfL”} | |
is_form_encoded | False |
The body is multipart MIME encoded. It is a little bit BlueVia specific, so instead of using the python email package the bluevia package uses string manipulations. The extraHeaders are created to fit the body.
Output of _signAndSend(…)
response["status"] = 201
content =
Input for _signAndSend(…)
consumer | Consumer Token and Secret of your BlueVia application |
method | GET |
token | Access Token and Secret |
requestUrl | https://api.bluevia.com/services/REST/MMS_Sandbox/outbound/requests/ |
10001107290927269650615700340687/deliverystatus | |
parameters | {“version”:“v1”, “alt”:“json”} |
body | "" |
extraHeaders | {} |
is_form_encoded | False |
Output of _signAndSend(…)
response["status"] = 200
content =
{"messageDeliveryStatus":{
"messageDeliveryStatus":[
{"address":{"phoneNumber":"447762654962"},
"deliveryStatus":"DeliveredToTerminal"} ] } }
Input for _signAndSend(…)
requestUrl | https://api.bluevia.com/services/REST/SMS_Sandbox/inbound/445480605/messages |
method | GET |
token | Access Token and Secret |
parameters | {“version”:“v1”, “alt”:“json”} |
body | "" |
extraHeaders | {} |
is_form_encoded | False |
The URL contains the shortcode of the specific country (5480605) prefixed by the country code, 44 = UK (shown bold)
Output of _signAndSend(…)
response["status"] = 200
content =
{"receivedSMS":{"receivedSMS":
{"message":"SANDBWTUT01 BlueVia",
"originAddress":{"phoneNumber":"445480605"},
"destinationAddress":{"phoneNumber":"445480605"},
"dateTime":"2011-07-29T08:44:30.523Z"}}}
This is an example with one message retrieved. If there are more messages, then the return value contains an array of messages.
Notes:
Input for _signAndSend(…)
requestUrl | https://api.bluevia.com/services/REST/MMS_Sandbox/inbound/445480605/messages |
method | GET |
token | Access Token and Secret |
parameters | {“version”:“v1”, “alt”:“json”} |
body | "" |
extraHeaders | {} |
is_form_encoded | False |
The URL contains the short code of the specific country prefixed by the country code (shown bold)
Output of _signAndSend(…)
response["status"] = 200
content =
{"receivedMessages":{"receivedMessages":
{"messageIdentifier":"06603100100307629600",
"destinationAddress":{"phoneNumber":"445480605"},
"originAddress":{"phoneNumber":"445480605"},
"subject":"SANDBWTUT01 BlueVia Multimedia",
"dateTime":"2011-07-29T08:44:36.296Z"}}}
The important part of the MMS message compared to SMS is the messageIdentifier. This value wil be used to retrieve the attachments of an MMS, see below.
Input for _signAndSend(…)
requestUrl | https://api.bluevia.com/services/REST/MMS_Sandbox/inbound/445480605/ |
messages/06603100100307629600 | |
method | GET |
token | Access Token and Secret |
parameters | {“version”:“v1”, “alt”:“json”} |
body | "" |
extraHeaders | {} |
is_form_encoded | False |
The URL contains the short code of the specific country prefixed by the country code (445480605) and the message identifier retireved in 3.9 (06603100100307629600, both shown bold)
Output of _signAndSend(…)
response["status"] = 200
content =
--MIMEBoundaryurn_uuid_636C752383BEC3AFDD1222262665928
Content-Disposition: form-data; name="root-fields"
Content-Type: application/json;charset=UTF-8
Content-ID: <0.urn:uuid:636C752383BEC3AFDD1222262665929@apache.org>
{"message":{"address":[{"phoneNumber":"445480605"}],"originAddress":{"phoneNumber":"445480605"},
"subject":"SANDBWTUT01 BlueVia Multimedia"}}
--MIMEBoundaryurn_uuid_636C752383BEC3AFDD1222262665928
Content-disposition: form-data; name="attachments"
Content-Type: multipart/related; boundary=BbC04y
... _all the attachments are encoded here_ ...
--BbC04y--
--MIMEBoundaryurn_uuid_636C752383BEC3AFDD1222262665928--
NOTE: The text in content is currently lacking the first part necessary for parsing it with the standard python email package. The routine used in the bluevia package prefixes the content with
'Content-Type: multipart/mixed; boundary="--MIMEBoundaryurn_uuid_636C752383BEC3AFDD1222262665928"\r\n"'
Input for _signAndSend(…)
requestUrl | https://api.bluevia.com/services/REST/Location_Sandbox/TerminalLocation |
method | GET |
token | Access Token and Secret |
parameters | {“version”:“v1”, “alt”:“json”, |
“locatedParty”:“alias:493c2c9316b2c75e2766c97477450b13” } | |
body | "" |
extraHeaders | {} |
is_form_encoded | False |
The field parameters contains the Access Token to identify the terminal to be located (shown bold)
Output of _signAndSend(…)
response["status"] = 200
content =
{"terminalLocation":{
"locatedParty":{"alias":"493c2c9316b2c75e2766c97477450b13"},
"reportStatus":"Retrieved",
"currentLocation":{
"coordinates":{
"latitude":"51.524431",
"longitude":"-0.636370"
},
"accuracy":"100",
"timestamp":"2011-07-29T10:44:38"
}
}}
Note You can also add an accuracy parameter to the parameters dict.
Input for _signAndSend(…)
consumer | Consumer Token and Secret of your BlueVia application |
token | Access Token and Secret |
method | GET |
requestUrl | https://api.bluevia.com/services/REST/Directory_Sandbox/ |
alias:493c2c9316b2c75e2766c97477450b13/UserInfo | |
parameters | {“version”:“v1”, “alt”:“json”} |
body | "" |
extraHeaders | {} |
is_form_encoded | False |
The URL contains the Access Token to identify the user (shown bold)
Output of _signAndSend(…)
response["status"] = 200
content =
{"userInfo":
{"userProfile": {"userType":"Postpay","icb":"false","ocb":"false",
"parentalControl":"not active","operatorId":"O2","segment":"High Use"},
"userAccessInfo":{"apn":"mobile.o2.co.uk,wap.o2.co.uk"},
"userTerminalInfo":{"brand":"Sony Ericsson","model":"K800i",
"screenResolution":"240x320 pixel, 2 inch","mms":"no"}}}
Input for _signAndSend(…)
requestUrl | https://api.bluevia.com/services/REST/Advertising_Sandbox/simple/requests |
method | GET |
token | Access Token and Secret |
parameters | {‘ad_space’: ‘10977’, ‘ad_presentation’: ‘0101’, ‘version’: ‘v1’, |
‘user_agent’: ‘none’, ‘protection_policy’: 1, | |
‘ad_request_id’: ‘a1585b0e-d8dbFri Jul 29 09:44:38 2011’} | |
body | ‘ad_space=10977&ad_presentation=0101& |
protection_policy=1&user_agent=none& | |
ad_request_id=a1585b0e-d8dbFri+Jul+29+09%3A44%3A38+2011’ | |
extraHeaders | {“Content-Type”:“application/x-www-form-urlencoded”} |
is_form_encoded | True |
This is the only API that uses form encoding up to now. Further on, here you have to add your ad Space id and provide a unique string as ad_request_id .
Note:
Output of _signAndSend(…)
response["status"] = 201
content =
<?xml version="1.0" encoding="UTF-8"?><?xml version="1.0"?>
<NS1:adResponse xmlns:NS1="http://www.telefonica.com/schemas/UNICA/REST/sgap/v1/"
id="111122010-10-18T10:00:0030c8db243ad" version="2">
<NS1:ad id="52891020" ad_placement="1" campaign="52891004" flight="52891019">
<NS1:resource ad_presentation="0101">
<NS1:creative_element type="image">
<NS1:attribute type="locator">
https://api.bluevia.com/services/Ad/BlueViaBanner.png
</NS1:attribute>
<NS1:interaction type="click2wap">
<NS1:attribute type="URL">http://www.bluevia.com</NS1:attribute>
</NS1:interaction>
</NS1:creative_element>
</NS1:resource>
</NS1:ad>
</NS1:adResponse>
Note: The BlueVia Advertising API unfortunately only produces XML. The python library used in this tutorial converts the XML to JSON:
{''adResponse': {
'version':'2',
'id':'111122010-10-18T10:00:0030c8db243ad',
'ad': {
'resource': {
'ad_representation':'0101',
'creative_element': {
'attributes': [{
'type':'locator',
'value':'https://api.bluevia.com/services/Ad/BlueViaBanner.png'
}],
'interaction': {
'attributes': [{
'type':'URL',
'value':'http://www.bluevia.com'
}],
'type':'click2wap'
},
'type':'image'
}
},
'ad_place_ment':'1',
'flight':'52891019',
'id':'52891020',
'campaign':'52891004'
}
} }
Input for _signAndSend(…)
requestUrl | https://api.bluevia.com/services/REST/Advertising_Sandbox/simple/requests |
method | GET |
token | None |
parameters | {‘ad_space’: ‘10977’, ‘ad_presentation’: ‘0101’, ‘version’: ‘v1’, |
‘user_agent’: ‘none’, ‘country’: ‘GB’, ‘protection_policy’: 1, ‘ad_request_id’: | |
‘ad_request_id’: ‘6a36a734–78a6Fri Jul 29 15:55:48 2011’} | |
body | ‘ad_space=10977&ad_presentation=0101& |
protection_policy=1&user_agent=none& | |
ad_request_id=6a36a734–78a6Fri+Jul+29+15%3A55%3A48+2011’ | |
extraHeaders | {“Content-Type”:“application/x-www-form-urlencoded”} |
is_form_encoded | True |
The important differences to the 3 legged Advertising API are:
Output of _signAndSend(…)
Similar to 3-legged Advertising in 4.10
Input for _signAndSend(…)
requestUrl | https://api.bluevia.com/services/REST/Oauth/getRequestToken |
method | POST |
token | None |
parameters | {‘serviceInfo.name’: ‘Ringtone’, ‘serviceInfo.serviceID’: ‘13545’, |
‘paymentInfo.amount’: 249, ‘paymentInfo.currency’: ‘EUR’, | |
‘xoauth_apiName’: ‘Payment_Sandbox’, ‘oauth_callback’: ‘oob’} | |
body | paymentInfo.currency=EUR&paymentInfo.amount=249& |
serviceInfo.name=Wallpaper&serviceInfo.serviceID=13545 | |
extraHeaders | {“Content-Type”: “application/x-www-form-urlencoded;charset=UTF8”} |
is_form_encoded | True |
Output of _signAndSend(…)
response["status"] = 200
content = auth_token=4cdb2782174210d29e24b4b0a68fabcb&\
oauth_token_secret=70a52c83b60b3e99d770d2cc6e76fe7e\
&oauth_callback_confirmed=true
In the next step the customer authorizes the payment and afterwards the application exchanges the request token with an access token as with standard BlueVia oAuth. The payment access token is 48 hours valid.
Input for _signAndSend(…)
requestUrl | https://api.bluevia.com/services/RPC/Payment_Sandbox/payment |
method | POST |
token | Access Token and Secret |
parameters | {} |
body | { “methodCall”: { |
“version”: “v1”, | |
“params”: {“paymentParams”: { | |
“paymentInfo”: {“currency”: “EUR”,“amount”: “249”}, | |
“timestamp”: “2011–10–11T21:38:59Z” }}, | |
“id”: “bf957df2-fb2f–406f–9161–6aa1177cb718”, | |
“method”: “PAYMENT” }} | |
extraHeaders | {‘Content-Type’: ‘application/json;charset=UTF8’} |
is_form_encoded | False |
Output of _signAndSend(…)
response["status"] = 200
content = {'methodResponse': {'id': '89ac845b-18b4-49af-bdb7-8e66fe60bfb1',
'result': {'paymentResult': {'transactionId': '10001110112028067871578100252983',
'transactionStatus': 'PENDING',
'transactionStatusDescription': ''}},
'version': 'v1'}})
Input for _signAndSend(…)
requestUrl | https://api.bluevia.com/services/RPC/Payment_Sandbox/getPaymentStatus |
method | POST |
token | Access Token and Secret |
parameters | {} |
body | { “methodCall”: { |
“version”: “v1”, | |
“params”: {“getPaymentStatusParams”: { | |
“transactionId”: “10001110112039008051701961524255” }}, | |
“id”: “bf957df2-fb2f–406f–9161–6aa1177cb718”, | |
“method”: “GET_PAYMENT_STATUS” }} | |
extraHeaders | {‘Content-Type’: ‘application/json;charset=UTF8’} |
is_form_encoded | False |
Output of _signAndSend(…)
response["status"] = 200
content = {'methodResponse': {'id': '89ac845b-18b4-49af-bdb7-8e66fe60bfb1',
'result': {'getPaymentStatusResult': {
'transactionStatus': 'SUCCESS',
'transactionStatusDescription': 'Successful Transaction'}},
'version': 'v1'}}