How to use Mobitel's SMS API in Inzpire

 

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 Endpoint: https://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!