Monday, September 25, 2017

Mobitel Charging As A Service API

September 25, 2017 Posted by Akalanka No comments

Mobitel's Charging as a service API via Inzpire enables developers to integrate carrier billing to the applications with the minimum amount of hassle. This is one of the two charging related APIs in the Mobitel API suite in Inzpire along with the Subscription API. Using this API requires you to be registered as a developer in the Inzpire developer portal. You can refer this post to learn how to register yourself.

Step 1: Create an application key in API Manager

First you have to create an application in case if you have not already created one. To create an application click on 'Apps' link on the API portal and click on 'Create new App' on the top. Fill the following details to create the application
    • Title - name of your application
    • Description- brief description on what your app will do
    • OAuth Redirect URI - The redirect URI used in oAuth flow if your application uses oAuth based authorization in any of the APIs. More on this later.

  • You can view your newly created app under 'Apps' and click on the app name to view further details. Note the ClientID in the and click the 'show' checkbox to view the ClientID. You will need this in consuming the APIs below
  • Go to the API product page here and select the Charging As A Service API
  • Click on the 'Subscribe' button and select the the application that you just created on the menu that pops up. Now your app is subscribed to the Charging As A Service API


Step 2: Call CaaS API

The charging as a service API exposes the following two services

  • Charging request service
    • This service needs to be called to initiate a transaction. 
    • It will send a USSD popup to the user with the details of the transaction and will request the user to approve the same. 
    • It will return a reference number for the transaction which will be used with the confirmation service to check if the customer has approved the charging request
    • If the user fails to approve the transaction due to any reason, you can re-initiate the process by calling this service after 2 minutes
  • Transaction confirmation service - This service needs to be called to confirm the transaction. The service call will return a successful response if the user has given the consent to the USSD popup message sent previously to obtain consent.

2.1 API definition - Charging Request


  • URL: 
    • API Endpointhttps://apphub.mobitel.lk/mobext/mapi/caas/chargRequest
  • Request type:
    • HTTP POST
  • Headers:
    • x-ibm-client-id : The application's client ID
  • Body: The body should be a JSON formatted string with the following parameters
    • amount: The amount that needs to be charged in Rupees  
    • customer: The customer mobile number from which the amount should be charged
      • eg: {"amount":"5","receiver":"0712755777"}
  • Response: received as a JSON formatted string with the following parameters
    • reference: reference number of the transaction. Very important as this reference is used in the next API call to complete the transaction
    • message: verbose response message
    • status: response code
You can play with the API by visiting the online portal here


2.2 API definition - Charge confirmation
  • URL: 
    • API Endpointhttps://apphub.mobitel.lk/mobext/mapi/caas/confirm
  • Request type:
    • HTTP POST
  • Headers:
    • x-ibm-client-id : The application's client ID
  • Body: The body should be a JSON formatted string with the following parameters
    • ref: the reference number received in the previous API call
      • eg: {"ref":"320438941208291"}
  • Response: received as a JSON formatted string with the following parameters
    • reference: reference number of the transaction. Useful for logging and tracking purposes.
    • message: verbose response message
    • status: response code
You can play with the API by visiting the online portal here

Thursday, July 13, 2017

How to use Mobitel's SMS API in Inzpire

July 13, 2017 Posted by Akalanka 1 comment
 

Mobitel's SMS API in Inzpire makes integrating SMS capabilities to your applications easier than ever before. With multiple charging options with a string focus on value added service delivery,  we have tried our best to keep it simple and flexible for you to reach your customers.

Inzpire follows a simple service delivery model with an all revenue share model for the developer. This means that you can get your service up and running with zero initial investment and start earning revenue from day one. This is a great model for startups and individuals to turn awesome ideas to reality.

The workflow to use the SMS API is pretty straightforward for the developer via the Inzpire platform.

Let's see how you can create an SMS based service delivery application with Inzpire APIs. Popular examples would be news alert services, SMS voting services, etc.

Step 1: Create an SMS application

You can create an SMS application by logging in to the developer self care portal in Inzpire https://developer.mobitel.lk/selfcare Click 'Provision' link under the 'SMS' menu in the left navbar and you will get the SMS provisioning form.


  • App ID - This is the auto generated ID of the application. This is already unique and you are required to save this for calling the SMS API later.
  • App Key: This is the auto generated key for the application. The key and ID both will be required to call the SMS API later in this tutorial.
  • Service Name: This is the name of the service your application will provide. This will also be the alias under which all the SMSs will be sent by your application via the Inzpire platform. i.e. if you name your service 'NewsAlerts', all the SMSs sent by your application to your customer will bear the sender as 'NewsAlerts'. The service name should be alphanumeric and no longer than 11 characters.
  • Short/Long Code: This is the number under which your application will be available to Mobitel subscribers. You can choose from a pre-defined pool of short codes (eg: 77001,77002 etc.) 
  • Keyword: This will be the keyword which will be used to identify you application. Since the short/long codes mentioned above are shared between applications, the keyword is an important parameter which will distinguish your application from other applications operating on the same short/long code.
  • Callback URL: This is the URL which the Inzpire platform will forward SMSs send your short/long code and keyword. The request will be sent as an HTTP POST. You should have a service running at this callback URL to receive the HTTP POST request to receive SMSs sent by your customers. Tips on building the SMS receiver service can be found in Step 2.
  • Charging Type: This is where we have kept is all simple and amazing. You can select one of the two following charging options for your customer.
    • One time charging:

    • In this method any SMS sent by your customer will be charged a fixed amount and forwarded to your application. This is suitable for services with one off requests where your application responds eg: Assume that you selected the short code 77001 and keyword 'cricket' and built an application to send the latest score of the currently playing cricket match. Once the customer sends an SMS starting with 'cricket' to 77001, the customer (in this case your customer) will be charged the amount you have defined here. If the charging is successful, you will receive an HTTP POST request to your callback URL.
    • Subscription charging

    • In this method the customer is expected to register for your service prior to any interaction. eg: Assume that you created a news alert service on short-code 77001 with keyword 'NewsAlerts' with a subscription charging model. The customer will first have to send an SMS 'REG NewsAlerts' to 77001. The customer will be charged according to the subscription plan you have configured here and you will receive a callback request. You can configure the charging cycle and the charging amount for pre paid and postpaid customers independently.
      • Charging type: This is the charging cycle duration for the subscription service. eg: Daily, Weekly, Monthly. 
      • Charging amount: this is the amount in rupees that should be charged to the customer for the subscription. At the point of initial subscription, the customer will be charged this amount and will be subsequently charged according to the charging cycle defined previously. At any point if the subscription fails due to insufficient credit, the subscription will be suspended and SMSs sent via the send SMS API will not be received by the customer. Once the credit level is sufficient for the charging the subscription, it will be charged and the subscription will be restored.
Upon completion, click the submit button and your SMS application will be created. Please note that SMS applications require administrator approval and your application will be shown in Home page in the developer selfcare portal subject to approval only.

Step 2: Create SMS receive service for callback URL
  
You should have a HTTP web server running at a public location for the Inzpire SMS service to push received SMSs. The URL of this service should be entered in the callback URL when provisioning an SMS application as described in the previous step. The request will be a HTTP POST with the following parameters.

  • senderMask: This is the customer's Mobile number in a masked format. This is the unique identification of a customer and can be used to send reply messages as shown in the following steps. This mask is a one to one mapping from the actual mobile number and is unique to your application.
  • message: This is the content of the SMS sent by the customer
  • shortCode: This is the short/long code to which this SMS was received. It will be the same as the short/long code you selected during provisioning of the SMS application. If you have multiple services running on multiple short codes
  • time: time at which the SMS was received by the platform
  • appId: This is the unique application ID of the SMS application to which this SMS was received by.
  • appKey: This is the application key of the SMS application to which this SMS was received by. The combination of appId and appKey can be used by you as a basic form of authentication to ascertain that this request was sent by the Inzpire platform and not a bogus request. Furthermore it will help you to relevant service if the same SMS receive service is used for multiple applications.
Once you have completed the SMS receive service, you will be able to receive SMSs sent by your customers to your short/long code with the proper keyword to your service. Continue to next step for testing your SMS receiver.

Step 3: Testing SMS receiving

The SMS sent by your customer should be in one of the following formats:

  • One time charging: <Keyword><space><custom text>
    • eg: cricket<space>SLvsIND
    • Only the <keyword> parameter will be relevant to the Inzpire platform. The <keyword><space> and any accompanying text will be sent to the callback URL via the HTTP POST request in the 'message' parameter.
    • The customer will be charged the specified amount and you will receive the callback only upon successful charging.
  • Subscription charging
    • Step 3.1: Register to service- REG<space><Keyword>
      • eg: REG<space>newsalerts
      • At this point the customer will be charged the relevant specified amount for the subscription and you will receive the callback upon successful charging
    • Step 3.2: Consume service- <Keyword><space><Custom text>
      • eg: newsalerts<space>foreign
      • Only the <keyword> parameter will be relevant to the Inzpire platform. The <keyword><space> and any accompanying text will be sent to the callback URL via the HTTP POST request in the 'message' parameter. However in applications with subscription charging the customer has to register to the service as described in Step 3.1 above prior to consuming service. This step is optional and there might be subscription style services where the customer only registers to a service and no further action from the customer is required. eg: customer sends REG<space>newsalerts and the application developed by the developer will send news alerts in real time via the send SMS API without any prompt from the customer.
Step 4: Send a reply to your customer

In this step we will see how you can send replies to your customers via Inzpire SMS API. Up to now you did not call any API on Inzpire since SMS receiving is built on a callback model where you provide the callback URL. For consuming APIs you need to be familiar with Inzpire API portal. 

  • Step 4.1: Navigate to Inzpire API portal at https://developer.mobitel.lk/mobext/mapi/product and login with the same credentials you used in the developer self care portal
  • Step 4.2: To consume APIs via the API manager you need to create an application key. Click on 'Apps' link on the API portal and click on 'Create new App' on the top. Fill the following details to create the application
    • Title - name of your application
    • Description- brief description on what your app will do
    • OAuth Redirect URI - The redirect URI used in oAuth flow if your application uses oAuth based authorization in any of the APIs. More on this later.

  • You can view your newly created app under 'Apps' and click on the app name to view further details. Note the ClientID in the and click the 'show' checkbox to view the ClientID. You will need this in consuming the API
  • Go to the API product page here and select the SendSMS API
  • Click on the 'Subscribe' button and select the the application that you just created on the menu that pops up. Now your app is subscribed to the SMS sending API


Calling the API is pretty straightforward as a HTTP POST. You can play with the API by visiting the console here.

API definition
  • URL
    • API Endpointhttps://apphub.mobitel.lk/mobext/mapi/mspacesms/send
  • Headers:
    • x-ibm-client-id : The application's client ID
    • content-type: application/json
  • Body: The body should be a JSON formatted string with the following parameters
    • recipientMask: This is the masked mobile number of the customer you want to send the SMS to. The masked number can be obtained from any SMS your received to your application.
    • message: Content of the SMS
    • characterEncoding: should be set to 'ascii'
    • appID: This is the SMS application ID
    • appKey: This is the SMS application key. You can send SMS only to customers who have contacted you via the application bearing this appID and appKey
      • eg: {"receipientMask":"28.186.206.2","message":"18","characterEncoding":"petmiet","appID":"5127123301826560","appKey":"vinw"}
Now you have all the tools needed for building an SMS based service. Let your imagination loose!





Wednesday, July 12, 2017

Getting on board Mobitel Developer Hub

July 12, 2017 Posted by Akalanka No comments
Welcome aboard the developer train with Mobitel. Our objective is to give you the boost that you always needed in getting your applications off the ground in line with Inzpire's mission of enabling & empowering the digital economy. Our developer program focuses on multiple facets on the digital services domain ranging from API services to IoT. By registering in the developer portal you will be able to access all the API services provided by Mobitel and other affiliated parties. 

In this article we will see how you can come on board as a developer in few simple steps.




It should be stressed that the bank details should be double checked before clicking the Create Account button since all the settlements for the revenue collected for your application will be transferred to the bank account identified in this registration.

Once completed you will get a confirmation which indicates that your request has been sent for approval and is currently in pending state. The administrator is expected to approve you account within 2 business days. When your account gets approved you will receive an email confirmation. If you need any assistance contact us at inzpire@Mobitel.lk and we will help to get you going.

Congratulations! You are now registered in Inzpire developer platform. 

Once you receive the login credentials in the email you can login to the Inzpire developer selfcare portal at https://developer.mobitel.lk/selfcare.





After logging in you will be redirected to the developer self care portal. This is where you will provision your applications with SMS and Voice capability. For detailed explanation on the developing SMS and voice capable applications refer the articles 'How to use Mobitel's SMS API' and 'Say Hello world with your first voice app' in the next section.

Monday, May 29, 2017

Venturing to the API Economy

May 29, 2017 Posted by Akalanka , No comments



Connecting with Digital Business

Connecting business digitally has never been so easy. With the development of software technologies, integrating diverse aspects of your business has become a cakewalk. The Service Oriented Architecture (SoA) concept has been the fore runner of connecting digital business worldwide. According to the SoA standard a service has to comply with four fundamental properties 
  • It logically represents a business activity with a specified outcome.
  • It is self-contained.
  • It is a black box for its consumers.
  • It may consist of other underlying services.
In a simpler note it suggests that each service should be modularized and that each service should expose an interface for connecting with other similar services. This is where the application programming interfaces (APIs) come to play.


The API economy

APIs do exactly what their name suggests: It provides an interface for developers to program their applications. People who had their first steps in programming with JAVA would be familiar with the term APIs. In that case JAVA APIs provide an interface for applications to communicate with underlying operations abstracted by the JVM. eg: in Android the camera API provides the operations available on the camera (such as take a picture, adjust exposure) as an interface for applications to control the camera. 

Scale up this scenario to a distributed system, you get the APIs that we are going to discuss here. In this case services expose their capabilities/operations as interfaces so that applications can access and consume them. The exact implementation can differ case by case but generally the communication happens over HTTP/S and may utilize a higher layer protocol like SOAP (Simple Object Access Protocol) to formalize the request & response formats. This in contrast to the APIs provided by programming languages such as JAVA where they are more internal part of the Object Oriented Programming paradigm. 

When there is an exchange of value an economic transaction will ensue. When connecting services with applications this becomes the case and monetization of the services given via APIs has now become big business. With Inzpire our objective is to add value to your application via our available services to enable you.

APIs at Inzpire Store

Inzpire digital services store is the one stop shop for all your digital service needs. The API products available here will add value to your product or service in many ways. The telco APIs provided by Mobitel will enable you to engage with the customer more closely and will open new avenues for you to generate more revenue. Other APIs you can expect to be available are IoT APIs where you can control IoT devices with simple API calls without going through the tedious configurations and firmware development associated with traditional IoT services. You can also expect to see advanced APIs in a cognitive computing flavor to do image processing, machine learning and natural language processing.

We will discuss how to consume Mobitel's API services in the next blog post.

Saturday, May 27, 2017

Welcome to Inzpire!

May 27, 2017 Posted by Mobitel Innovation Center No comments


What is inzpire?

Inzpire is a revolutionary concept where the sole objective is enabling empowering and exchanging digital services. We are in an age of connected lifestyles where technology makes a huge impact on how we go about our lives. This has led to the rapid change in how we consume goods and services. It has given rise to a change in the way innovations are done. 
Mobitel as a leader in ICT innovation has come forward to facilitate the next generation of innovators by giving their creations an opportunity to generate value. Inzpire will create the channel for you to reach your customer for your digital service. It will create an avenue for you to monetize your service and take it to the next level.


Following the pattern

The buyer seller pattern has been existent since ancient times to satisfy the need for goods and services. We saw changes engulfing this traditional pattern in the last century with Mega stores and online retailers. What has been true for physical goods should be good enough for intangible 'goods' as well. This is the initial point where the concept for inzpire sparked into reality. The need for a platform to exchange digital 'goods and services' has been a long overdue requirement. Inzpire creates the opportunity for this through its flexible digital services store concept where any service provider can showcase their product or service. This store will take care of charging the customer and will settle the revenue collected back to the service provider.


Digital Services Store




The Digital Services Store is the main highlight of Inzpire. The digital services listed here are listed into 3 main categories based on the relevant customer segment

  • Enterprise
  • Consumer
  • Developer
Enterprise customers will find products and solutions of value to their enterprise regardless of whether its a large enterprise or an SME. This will give the convenience of finding the best solution to cater the customer's enterprise requirement under one banner. Visitors to the enterprise store can be expected to discover a plethora of solutions in the likes of CRMs, automation systems, IoT solutions, marketing tools etc. The consumption of these services are also vastly simplified. Most of the products & services can be purchased and used off the shelf in a pay as you go model. No need for lengthy discussions and product familiarization sessions involving countless hours of staring at presentations. The goal is to keep the effectiveness high and the complexity low.

The consumer marketplace will be filled with apps and content delivery services to keep the general consumer informed and entertained. The engagement with the retail consumer will be high with simple intuitive interfaces with great user experience. Any product listed in the consumer marketplace is expected to meet the high standards of UI & UX in order to maintain good customer ratings. It will a great opportunity for creative and tech savvy individuals to devise innovative services to suit consumer requirements and deliver it.

The developer store will be more focused in and will be for the tech gurus. It will feature platforms, services intended to make the development of your next ground breaking idea a smooth ride. The main highlight of the developer store are the telco APIs provided by Mobitel now opened for developers. This will help energize your application with a telco flavor with minimal effort. The APIs are designed to be as simple as possible backed by best in class Enterprise grade systems. Integrating SMS, USSD, Subscription as a Service and a host of other service will now be a breeze.

Empowering & Enabling

Inzpire is built to empower the value creator and enable the value creation process. The Digital Services Store serves to exchanging the value created in this process. Mobitel has been actively empowering and enabling value creators and turning them to entrepreneurs with programs like 'Kotiyak Vatina Adahasak' - Sri Lanka's first tech reality TV show and Inspire Sri Lanka - a tech innovation competition to serve United Nations Sustainable Development Goals. 
Inzpire's first program with the aim of enabling innovators of tomorrow was kickstarted at Google I/O 2017 Extended held at Stein Studios under the banner 'Codeblooded'. This was a coding competition based on the open source free code camp with the objective of improving the skills and increasing the familiarity of multiple heavily used technologies and frameworks. The winner was given an all expense paid trip to Singapore to visit CommunicAsia held in Marina Bay sands over a period of 3 days. Mobitel is expected to continue this trend to inspire the future leaders of the tech industry with more innovative programs.