TELUS APIs

Available APIs and Services

1. Mobile Connect
2. Get Terminal Location SOAP Service
3. Send SMS SOAP Service

Mobile Connect

Mobile Connect is a global standard for federated authentication. The idea is that you would use the Mobile Connect app on your phone to log into various websites and applications, rather than having a separate username and password for each site that you use. This is similar to using your Google or Facebook account to log into sites like Pinterest and Goodreads.

First, you install Mobile connect on your phone and enroll yourself to use the service. You will be asked for your carrier billing information, which will be confirmed by your carrier to ensure your identity. You can then set a pin or fingerprint as your way to authenticate in the Mobile Connect app (so that your account is secure even in the event of a lost or stolen phone). Carriers that are currently supporting Mobile Connect in Canada include TELUS, Bell, and Rogers.

Next, when you visit a Mobile Connect enabled site on your laptop (or on any device), you can click the Mobile Connect button to log in rather than using a username and password. You enter your phone number and then you will receive a notification on your phone prompting you to authenticate in the Mobile Connect App. When you complete authentication in the app, you will be logged into the site on your laptop. Note that the site that has enabled Mobile Connect for authorization will not be able to see your phone number; they simply receive confirmation that you are authorized and a record that they will use to associate you to your account on the site.

No more remembering usernames and passwords: all authentication can be managed in one place through the Mobile Connect app. Add Mobile Connect authentication to your site or app to enable your users to use their phone as their login credentials.

To enable Mobile Connect on your application or site, you will need to import the following JavaScript components in your page:

    <script src="https://code.jquery.com/jquery-2.1.4.min.js"></script>

    <script src="https://ajax.googleapis.com/ajax/libs/jqueryui/1.11.4/jquery-ui.min.js"></script>

    <script src="/mc/js/EnStreamServerSDK.js"></script>

    <script src="/mc/js/app.js"></script>

JQuery components are required in order to perform AJAX Queries and to display the Mobile Connect dialogue on your page. EnStreamServerSDK.js includes the Mobile Connect logic. app.js contains the configuration for using Mobile Connect, including the URL to use and the callback function that will be used once the user completes authentication.

Next, you have to add a button to your page:

    <style>

        div.mcButton {

            position: absolute;

            width: 246px;

            height: 60px;

            top: 605px;

            left: 605px;

            background-image: url("img/mc_logos/MC-button2-246x60-colour.png");

        }

    </style>

    <div class="mcButton" id="mobile_connect" ></div>

Then you need to add the following script to handle when the user clicks the button:

    <script>

        $("#mobile_connect").click(function() {

            MobileConnectServerSDK.startAuthorization();

        });

   </script>

And lastly, you need to add an empty div for the Mobile Connect dialogue to use:

   <div id="mobileConnectDialog"  style="display: none ;"></div>

That's all the work that is required in your page, but now we need to set up callback handling. In a Java web application, we would create  

Get Terminal Location SOAP Service

WSDL: http://webservices.telus.com/parlayx21/072007/parlayx_terminal_location_service_2_3.wsdl

The Terminal Location API allows you to look up the location of a cell phone by its phone number in your application. For this event, this API works only for TELUS phone numbers, and the user of the phone must have authorized your application to perform this query. You will get a set of credentials for your application, SSL certificates, and then you must whitelist numbers that your application will be allowed to query. Please note that you must have access to and control of any phones that you want to whitelist. To whitelist a number, please ask one of the TELUS representatives at the event.

This location service strictly uses network triangulation to determine location. This means it is generally less accurate but will work in situations where GPS is not available (like in a basement) and is also able to report the last known location if the device cannot be found (which you cannot do with GPS).

You can use this service by sending a SOAP request with the following format:

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:loc="http://www.csapi.org/schema/parlayx/terminal_location/v2_3/local">

        <soapenv:Header/>

        <soapenv:Body>

            <loc:getLocation>

                <loc:address>tel:16042917290</loc:address>

                <loc:requestedAccuracy>5000</loc:requestedAccuracy>

                <loc:acceptableAccuracy>5000</loc:acceptableAccuracy>

            </loc:getLocation>

        </soapenv:Body>

    </soapenv:Envelope> 

loc:address -  The telephone number to find the location of

loc:requestedAccuracy -  The accuracy you would like on that location in meters

loc:acceptableAccuracy -  Location accuracy must be within this number of meters

Depending on the accuracy that you specify, different technologies will be used. Lower accuracy will take less time to ascertain.

We suggest using an accuracy level of 5000m or greater in order to get fast responses.

The response you receive will look something like this:

    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

        <soap:Body>

            <ns2:getLocationResponse xmlns:ns2="http://www.csapi.org/schema/parlayx/terminal_location/v2_3/local" xmlns:ns3="http://www.csapi.org/schema/parlayx/common/v2_1">

                <ns2:result>

                    <latitude>49.267</latitude>

                    <longitude>-123.0068</longitude>

                    <altitude>22.0</altitude>

                    <accuracy>182</accuracy>

                    <timestamp>2008-07-10T12:54:40.000-04:00</timestamp>

                </ns2:result>

            </ns2:getLocationResponse>

        </soap:Body>

    </soap:Envelope> 

 latitude, longitude: Coordinates where the subscriber is located

altitude: The subscribers elevation

accuracy: how accurate the location result is in meters

timestamp: the time at which the subscribers location was found

Send SMS SOAP Service

WSDL: http://webservices.telus.com/parlayx_sms_send_service_2_3.wsdl

The SMS API allows you to send SMS messages through your application. For this event, this API works only for TELUS phone numbers, and the user of the phone must have authorized your application to perform this query. You will get a set of credentials for your application, SSL certificates, and then you must whitelist numbers that your application will be allowed to query. Please note that you must have access to and control of any phones that you want to whitelist. To whitelist a number, please ask one of the TELUS representatives at the event.

While there are other services (like Twilio or, for TELUS customers, sending an email to <phone#>@msg.telus.com) that allow you to send SMS messages with fewer restrictions, those services have limitations in terms of the kind of content that can be sent and the frequency of content being sent. With this particular TELUS Send SMS service, there are no restrictions on content or frequency; it also allows for billing via SMS. As such, this service is most useful for premium SMS services.

Endpoint: https://webservices.telus.com/SendSmsService/services/SendSms

You can use this service by sending a SOAP request with the following format:

    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:loc="http://www.csapi.org/schema/parlayx/sms/send/v2_3/local">

        <soapenv:Header/>

        <soapenv:Body>

            <loc:sendSms>

                <!--1 or more repetitions:-->

                <loc:addresses>tel:16048183614</loc:addresses>

                <loc:senderName>1234</loc:senderName>

                <loc:message>Message 1 on 12-01-2012</loc:message>

                <!-- Optional -->

                <loc:receiptRequest>

                    <endpoint>http://yourendpoint.com/SmsNotificationService/services/SmsNotification</endpoint>

                    <interfaceName>SmsNotification</interfaceName>

                    <correlator>1010</correlator>

                </loc:receiptRequest>

            </loc:sendSms>

        </soapenv:Body>

    </soapenv:Envelope>

    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

        <soap:Body>

            <ns2:sendSmsResponse xmlns:ns2=http://www.csapi.org/schema/parlayx/sms/send/v2_3/local xmlns:ns3="http://www.csapi.org/schema/parlayx/common/v2_1">

                <ns2:result>267417690</ns2:result>

            </ns2:sendSmsResponse>

        </soap:Body>

    </soap:Envelope>

    <?xml version="1.0" encoding="UTF-8"?>

    <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

        <soap:Body>

            <ns2:notifySmsDeliveryReceipt xmlns:ns2="http://www.csapi.org/schema/parlayx/sms/notification/v2_2/local" xmlns:ns3="http://www.csapi.org/schema/parlayx/common/v2_1">

                <ns2:correlator>1010</ns2:correlator>

                <ns2:deliveryStatus>

                    <address>tel:16048183614</address>

                    <deliveryStatus>DeliveredToTerminal</deliveryStatus>

                </ns2:deliveryStatus>

            </ns2:notifySmsDeliveryReceipt>

        </soap:Body>

    </soap:Envelope>