4 How to implement BlueVia for Python - The APIs

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.

4.1 Send SMS

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.

4.2 Track SMS delivery

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

4.3 Send MMS

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 =           

4.4 Track MMS delivery

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"} ] } }

4.5 Receive SMS

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:

4.6 Receive MMS

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.

4.7 Retrieve MMS attachments

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"'

4.8 Get the terminal location

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.

4.9 Get the user context

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"}}}

4.10 Get advertisings - 3 legged oAuth

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'
    }
} }

4.11 Get advertisings - 2 legged oAuth

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

4.12 Payments - Get Payment Token

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.

4.13 Payments - Issue Payment

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'}})

4.14 Payments - Check Payment Status

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'}}