How to build Voice Apps with Mobitel

Customer engagement is a key focal point in any business. Customer relationship management can decide the fate of any company. The old school voice call is still the primary form of communication for most of our routine activities. This is why we have made it easier for your to integrate voice calling to your applications in few simple steps. Like all our services we have kept it simple and flexible so that it is a friendly tool to the novice and a versatile one for the expert.

If you are familiar with Inzpire SMS API, you will notice that the Voice API follows a similar model for connecting your application to your customer.

The voice API in Inzpire helps you build complex applications for content delivery and IVR based services with the stuff that you are already familiar with. You do not have to know any of the underlying protocols in the telco stacks such as SS7 or SigTran. You do not even have to know SIP, RTP, ICE or any of the protocols in the VOIP world. We have done all the heavy lifting for you so that just plain HTTP will make wonders in few simple steps. For all voice calls for you voice app, we will trigger a callback URL you have shared with us.After that you can call the HTTP based voice API to control the call flow (eg: answer call, hangup call, play voice prompt, get DTMF response from customer etc.)

As in any voice application you will have to have a short code(eg: 243) or long number (eg: 0712755777) for your customer to dial your service. Unlike in SMS API, this number is not shared between applications as it would make the user experience more troublesome. Therefore you need to obtain a short code or long number to use the voice API.

Step 1: Obtain a short code or long number

• Short code- Using a short code for your service would be great if you are building an app for content delivery over voice (eg: an e-book portal). If you want a short code for your service you will have to contact us to check the feasibility and availability of the short code you like. 
• Send an email to inzpire@mobitel.lk with your preferred short code and we will get back to you within 2 business days.
• Only Mobitel customers will be able to dial your voice app
• You can discuss with us to set custom charging for the short code for Mobitel customer. Please note this per minute charge might be subject to TRC regulations. A majority portion of the collected revenue for the short code will be settled to you where the exact revenue share percentage will be finalized upon approval by Mobitel
• A rental will be applicable for the short code
• Long number- This method is useful if you are building an IVR for your customers and you want both Mobitel and non Mobitel customers to reach you. All you have to do is get a Mobitel SIM with a long number with any prepaid or postpaid connection. You can obtain any number that is available currently.
• Get a Mobitel number
• Set all calls forwarding for that SIM to 0710303010
• You can set call forwarding using the call settings menu in your phone or
• Dial *21*0710303010# to activate
• If you want to cancel the call forwarding, dial #21# or disable call forwarding in your phone's settings menu.
• Once the call forwarding is done you can keep or remove the SIM card from the phone as you wish
• There will be no rental or revenue share for this number for using the Voice API
• You will not receive any revenue from this number as only standard call charges will be charged to the customer who dial this number.
• You will be charged the call forwarding fee for all the calls that are received by this number.

Step 2: Create voice app service for callback URL

  
You should have a HTTP web server running at a public location for the Inzpire voice API to handle voice calls. Once a call is received by your short code or long number an HTTP request will be made from the Inzpire voice server to this server. The URL of this service should be entered in the callback URL in the next step when provisioning a voice application. The request will be a HTTP POST with the following parameters.

• callerid: This is the mobile number if the customer who originated the call
• txid: This is a unique transaction ID for this call. The transaction ID will be needed for handling the voice call via the API as you will see in the following steps.
• ivrno: This is the short/long number of your voice application to which this call was received by.

Step 3: Provision your voice application

• Login to the Inzpire developer portal at https://developer.mobitel.lk/selfcare
• Click Voice > Home in the left nav bar. You will be redirected to the voice portal at https://mvoice.mobitel.lk

• Click on 'Create App' and enter
• IVR number - This is the short code/long number which your service will be available on
• App URL - This is the callback URL you setup in the previous step
• Once created, your app will show up on the 'My Apps' page
• You will receive a OTP code to your phone as an SMS
• Enter the OTP and click verify to complete the app registration
• Click on the 'Profile' button on the voice app to upload audio files if needed as shown below. Your audio files should be in .wav format. We will see how you can play these voice prompts to the calling customers via the API in the next steps.

• Received calls will show up in the 'Call log report' tab of your voice portal

Once this step is complete, you should be able to receive a call back request to your application server when a call is dialled to your voice app number. eg: If you chose 243 as the short code, dial 243 with any Mobitel number and your service should receive a HTTP POST with the relevant parameters. To do any real testing you should familiarize yourself with the API which we will do in the following step.

Step 4: Calling the Voice API in Inzpire

In order to call the voice API you have to create an application key in the 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.

• 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 mVoice 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 voice API

The mVoice API in Inzpire has the following services available:

• Play file- This service can be called to play an audio file that was uploaded in Step 3 to the calling party. The HTTP request will return only when the file playback is finished eg: play a welcome message
• Play file async- This service can be called to play an audio file that is already uploaded. But unlike the previous service, the HTTP request terminates immediately and does not wait for the file playback to finish. Once the playback is finished a custom callback URL is triggered to prompt the developer application for the next action. This method can be used if the audio file is very long.
• Play and wait for input - You can call this service to play an audio file and wait for the user to enter a number (DTMF tone) as a response. eg: Play a file to select 1 for Tech support, 2 for marketing and 3 for sales. You will receive the number that the customer entered as the response to this API call.
• Play and wait for input async- Similar to the previous API call, but the request terminates immediately and the user input is sent as a callback to the custom callback URL. Like to the Play file async method, this method is suitable for playing back long audio files.
• Say number- This service is useful if you want to read out a number to the calling customer. eg: 1234 is read out as one thousand two hundred and thirty four. You can set the language as Sinhala , English or Tamil. This will be useful if you want to read out your customer's account balance or anything similar
• Say Digits- This service is useful if you want to read out a number in digits to the calling customer. eg: 1234 is read out as one, two, three, four. You can set the language as Sinhala , English or Tamil
• Hangup- This service can be called to terminate the call
• Hello world - This is a demo service which play a default 'Hello world' prompt to the caller

4.1 API definition - Play file

• URL: 
• API Endpoint: https://apphub.mobitel.lk/mobext/mapi/mvoice/playfile
• 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
• filename: The name of the file that you uploaded in Step 3 to the portal
• txdata: 
• txid: The transaction ID of the voice call received by the callback URL when the call was initially received
• ivrno: the short code/long number of this voice app
• callerid: The mobile number of the customer who originated this call. You will find this parameter in the initial callback when call is received.

4.2 API definition - Play file async

• URL: 
• API Endpoint: https://apphub.mobitel.lk/mobext/mapi/mvoice/playfileasync
• 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
• filename: The name of the file that you uploaded in Step 3 to the portal
• txdata: 
• txid: The transaction ID of the voice call received by the callback URL when the call was initially received
• ivrno: the short code/long number of this voice app
• callerid: The mobile number of the customer who originated this call. You will find this parameter in the initial callback when call is received.
• callbackurl: This is the custom URL to which you will receive a callback when the file playback is complete

4.3 API definition - Play file and wait for input

• URL: 
• API Endpoint: https://apphub.mobitel.lk/mobext/mapi/mvoice/playandwaitforinput
• 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
• filename: The name of the file that you uploaded in Step 3 to the portal
• txdata: 
• txid: The transaction ID of the voice call received by the callback URL when the call was initially received
• ivrno: the short code/long number of this voice app
• callerid: The mobile number of the customer who originated this call. You will find this parameter in the initial callback when call is received.
• timeout: The maximum time this method will wait for the customer to enter a digit
• numdigits: The number of digits the customer is expected to enter

4.5 API definition - Say number

• URL: 
• API Endpoint: https://apphub.mobitel.lk/mobext/mapi/mvoice/saynumber
• 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
• number: The number that you want to readout
• txdata: 
• txid: The transaction ID of the voice call received by the callback URL when the call was initially received
• ivrno: the short code/long number of this voice app
• callerid: The mobile number of the customer who originated this call. You will find this parameter in the initial callback when call is received.
• language:
• en 
• sin
• tam

4.6 API definition - Say Digits

• URL: 
• API Endpoint: https://apphub.mobitel.lk/mobext/mapi/mvoice/saydigits
• 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
• number: The digits that you want to readout
• txdata: 
• txid: The transaction ID of the voice call received by the callback URL when the call was initially received
• ivrno: the short code/long number of this voice app
• callerid: The mobile number of the customer who originated this call. You will find this parameter in the initial callback when call is received.
• language:
• en 
• sin
• tam

4.7 API definition - Hangup

• URL: 
• API Endpoint: https://apphub.mobitel.lk/mobext/mapi/mvoice/hangupcall
• 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
• txid: The transaction ID of the voice call received by the callback URL when the call was initially received
• ivrno: the short code/long number of this voice app
• callerid: The mobile number of the customer who originated this call. You will find this parameter in the initial callback when call is received.

4.7 API definition - Hello world

• URL: 
• API Endpoint: https://apphub.mobitel.lk/mobext/mapi/mvoice/helloworld
• 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
• txid: The transaction ID of the voice call received by the callback URL when the call was initially received
• ivrno: the short code/long number of this voice app
• callerid: The mobile number of the customer who originated this call. You will find this parameter in the initial callback when call is received.

You are now ready to build voice apps with Inzpire!. Visit the API portal here to play with the voice API.