Introduction

Tiara Gateway is a fast, simple, secure and scalable enterprise messaging Gateway that simplifies how organizations connect to their customers via Short Message Service (SMS) and Unstructured Supplementary Service Data (USSD).

Multiple enterprise applications or systems can connect to the gateway and the gateway can reliably route SMS traffic to multiple mobile network operators.

USSD is a global system used by mobile network operators to deliver interactive, session-based communication. Our gateway allows users to send text-based requests from their mobile phones where we reliably route this request to the connected USSD client application. Additionally, we route back the responses from the client application to the end user.

The purpose of this document is to provide documentation of the HTTP Application Programming Interface (API ) that allows 3rd party applications to connect to the Tiara SMS Gateway for the purpose of sending out messages and receiving delivery receipts in addition to receiving USSD requests from end users and forwarding USSD responses to the end user.

Send SMS API

Purpose

The Send SMS API allows applications to send SMS messages to mobile subscribers (mobile users). This API is designed to help organizations communicate with their customers via SMS e.g. an ecommerce app may send a payment confirmation SMS.

The API allows you to send SMS requests from your application (e.g. your e-commerce app) to the messaging gateway. For each request sent from your application, the messaging gateway sends a response back to your application indicating whether the message was submitted to the mobile operator successfully or not.

The API provides a unique message ID for each SMS sent, enabling applications to track whether messages are successfully delivered to users’ mobile devices.

Once a message is delivered to a mobile device, a delivery receipt confirmation can be sent back to the application, ensuring that communication with users is effective and reliable.

Integration Flow

The diagram below shows how an SMS message is relayed from your application to the mobile operator (e.g. Safaricom Kenya or Vodafone Tanzania) through the Tiara messaging gateway. The diagram also illustrates how delivery receipts are sent from the mobile operator to your application through the SMS gateway.

Step 1(a) Send SMS Request

Your application sends an HTTP POST request to the Tiara SMS Gateway. The request is in JSON format. The request structure is specified below.

HTTP Header Parameters

You require the following header details to use the SMS API.

HTTP Body Parameters

The table below specifies the parameters required in the send single sms operation.

Sample HTTP Body

Message Types

You require the following details to use the SMS API.

Step 1(b) Send SMS Response

The SMS Gateway responds with a unique message id in the HTTP Response. The id uniquely identifies the message within the gateway. The same message id is used in the delivery receipt callback described in step 4 below. More information about the HTTP response is specified below.

HTTP Response Parameters

The table below specifies the parameters specified in the send SMS response.

Sample HTTP Payload - SUCCESSFUL Request

Sample JSON response: for HTTP code 200

Sample HTTP Payload - FAILED Request

Sample JSON response for errors.

Step 2 Forward SMS to the Mobile Operator

Tiara SMS Gateway forwards the message to the mobile operator and eventually, the message is forwarded to the mobile phone (mobile subscriber).

NOTE: The request structure is not necessary for developers.

Step 3 SMS delivery receipt from the Mobile Operator

Once the mobile phone receives the sent message, the phone generates a delivery receipt which is sent back to the mobile operator and the mobile operator forwards the same receipt to the Tiara Messaging Gateway.

NOTE: The response structure is not necessary for developers.

Step 4 Forward the delivery receipt via HTTP Callback URL

Upon receiving the delivery receipt from the mobile operator, the Messaging Gateway forwards the delivery receipt to your application via an HTTP callback URL. The delivery receipt callback sent to your application is an HTTP POST request with a JSON body with the parameters specified below.

HTTP Header Parameters

The delivery receipt callback response sent to your application is an HTTP request with the following header parameters set in the request.

HTTP Body Parameters

The table below specifies the parameters sent to your application in the delivery receipt callback request.

Sample HTTP Body

Sample JSON Delivery receipt Payload sent to your application:

Delivery Status Codes

The table below specifies the list of delivery statuses that will be visible on the SMS portal or contained in the callback payload.

Send Batch SMS API

Purpose

Your application can send multiple SMS messages by making an HTTP POST request to the Gateway. The Gateway supports two formats for sending a batch of messages:

1. An array of Objects : Send an array, with each entry as a separate JSON object containing a single phone number.

Choose either format based on your application's needs, and the Gateway will handle the batch accordingly.

Integration Flow

The diagram below shows how batch messages are relayed from your application to the mobile operator through our gateway.

Step 1(a) Send Batch SMS Request

Your application sends an HTTP POST request in JSON format to the Tiara Messaging Gateway to send multiple SMS messages. There are two options for structuring the batch request:

1. An array of Objects: Send an array of JSON objects, with each object containing an individual phone number.

The request is in JSON format. The request structure is specified below.

HTTP Header Parameters

You require the following header details to use the SMS Batch API.

HTTP Body Parameters

The table below specifies the parameters required in the send batch sms operation.

Sample HTTP Body

An array of Objects:

Send an array of JSON objects, with each object containing an individual phone number.

Step 1(b) Send Batch SMS Response

The SMS Gateway responds with a unique message ID in each HTTP response in the response list. These IDs uniquely identify each message within the gateway and will also be used in the delivery receipt callback in Step 4. More details on the HTTP response is specified below.

Sample HTTP Payload - SUCCESSFUL Request

Sample JSON response: for HTTP code 200

Sample HTTP Payload - FAILED Request

Sample JSON response for errors.

Step 2 Forward Batch SMS to the Mobile Operator

Tiara SMS Gateway forwards the batch messages to the mobile operator and eventually, each message is forwarded to the respective mobile phone (mobile subscriber).

NOTE: The request structure is not necessary for developers.

Step 3 SMS delivery receipt from the Mobile Operator

Once the mobile phone receives the sent message, the phone generates a delivery receipt which is sent back to the mobile operator and the mobile operator forwards the delivery receipt to our SMS Gateway.

NOTE: The response structure is not necessary for developers.

Step 4 Forward delivery receipt via HTTP Callback URL

Upon receiving the delivery receipt from the mobile operator, the Messaging Gateway forwards the delivery receipt to your application via a HTTP callback URL. The delivery receipt callback sent to your application is a HTTP POST request.

NOTE: The same parameters used in the Send SMS API to forward the delivery receipt to your application via HTTP Callback URL also apply here.

For more information, refer to section Step 4: Forward the delivery receipt via HTTP Callback URL in the send sms API.

Forward received sms message (MO)

Purpose

When a mobile phone user sends a message to a shortcode, this message is referred to as a Mobile-Originated (MO) message — meaning it originates from the mobile user. The Tiara messaging gateway then forwards this MO message to the client’s application via an HTTP callback URL. This callback URL to your application is provided and configured during the integration process, allowing the client’s application to receive and process incoming messages in real-time.

By using this setup, the client’s application can immediately process incoming messages, enabling real-time responses or further actions based on the content of each MO message. This mechanism is particularly useful for applications that require instant user interaction, such as surveys and customer support interactions.

Below is a use case to illustrate how forwarding MO works:

• Suppose Bake Connect Application wants to conduct a survey to gather feedback from its customers. They use the Tiara messaging gateway to send survey messages to their customers’ mobile phones.
• When customers respond to the survey by texting back to a shortcode, their responses are first received by their mobile operator (Telco such as Safaricom).
• The operator then sends these responses to the Tiara messaging gateway.
• The Tiara messaging gateway then forwards each customer response to Bake Connect’s Application(Client application), where the responses can be processed.

Integration Flow

The diagram below shows how an MO is relayed from the mobile operator through the Tiara messaging gateway to your application.

Step 1 User-initiated message from mobile operator

A user sends an SMS from their mobile phone to a specific shortcode associated with a service. This message, known as a Mobile-Originated (MO) message, is received by the mobile operator, who then forwards the user-initiated message to the messaging gateway for processing.

NOTE: The request structure is not necessary for developers.

Step 2 Forward received message (MO) via HTTP Callback URL

The messaging gateway then forwards the message to your application via a HTTP callback URL. The received message (MO) callback sent to your application is a HTTP POST request with a JSON body with the parameters specified below.

HTTP Header Parameters

HTTP Body Parameters

The table below specifies the parameters sent to your application in the received message (MO) callback request.

Sample HTTP Body

Sample JSON MO Payload sent to your application:

Survey Trigger API

Purpose

The Survey Trigger API allows an external system to connect with the Tiara messaging gateway and automatically initiate a predefined survey to users who interact with an external system.

When a user interacts with the external system, this API triggers a survey to be sent to the user’s mobile phone, enabling immediate and seamless feedback collection.
To enable this, you will need to create a survey on our messaging gateway system which will be triggered to your customers once they interact with your system.

This integration is highly useful in touchpoint NPS (Net Promoter Score), to automatically survey customers and get their reviews after they interact with the client system. The API in addition can send the customer response via email back to the client system.

Use case: Ticketing system for a bank.

• The ticketing system is integrated with the Tiara Messaging Gateway. When a mobile subscriber interacts with the ticketing system, a survey trigger request is sent to the Tiara messaging gateway.
• The messaging gateway, which contains a predefined survey already created in the system, sends it to the mobile operator, who then forwards it to the customer.
• The customer replies to the survey, and their response is sent back through the mobile operator to the messaging gateway. The gateway processes the user's input and forwards it to the client application via HTTP callback URL. Additionally, the messaging gateway sends the customer’s survey response to a specified email address.

Integration Flow

The diagram below shows the flow from when a mobile user interacts with an external system and a survey is triggered to them and they send their responses.

Step 1 Mobile user interacts with a 3rd party system

A mobile user can interact with an external system e.g. the ticketing system in a bank by performing an action on the external 3rd party system.

Step 2 Trigger survey request

The user interaction causes your application to send a trigger survey request to the Tiara messaging gateway. Your application sends an HTTP POST request to the Tiara SMS Gateway. The request is in JSON format. The request structure is specified below.

HTTP Header Parameters

HTTP Body Parameters

The table below specifies the parameters required to send a survey trigger request to the Messaging gateway.

Sample HTTP Body

Step 3 Send an SMS to the mobile operator

Upon receiving the trigger request, the API initiates a predefined survey (created in the messaging gateway system) to the mobile operator.

NOTE: The request structure is not necessary for developers.

Step 4 Forward SMS to the mobile phone user

The mobile operator then forwards the SMS to the mobile subscriber's phone.

NOTE: The request structure is not necessary for developers.

Step 5 Send user response (MO) to mobile operator

The user then responds to the survey. The reply is sent to the mobile operator.

NOTE: The response structure is not necessary for developers.

Step 6 Forward User input (MO) to the messaging gateway

The mobile operator then forwards the user input (MO) to the messaging gateway.

NOTE: The response structure is not necessary for developers.

Step 7 Forward user input to your application

The Tiara messaging gateway then forwards the user input to the client application via a HTTP callback URL. In addition, the trigger API sends the customer’s survey response to an email address specified by the client.

NOTE: The same parameters used in the Forwarding MO API to forward the Mobile Originated (MO) message (user’s response) to the client application via HTTP Callback URL also apply here.

For more information, refer to section Step 2 Forward received message (MO) via HTTP Callback URL in the forwarding MO API.

USSD

Purpose

USSD is a global system used by mobile network operators to deliver interactive, session-based communication. Our gateway allows users to send text-based menu requests from their mobile phones where we reliably route this request to the connected USSD enterprise application allowing organizations to connect to their customers via Unstructured Supplementary Service Data (USSD).

Additionally, we route back the responses (menus) from the enterprise application to the end user. The messaging gateway allows 3rd party applications to connect to the Tiara USSD Gateway for the purpose of receiving USSD requests from end users and forwarding USSD responses to the end user. This is done via an HTTP endpoint that is exposed by the 3rd party USSD app developer.

The mobile subscriber can establish a USSD session by dialing a USSD code. Your application can then respond with the USSD menu to the mobile subscriber through the USSD gateway.

Integration Flow

The diagram below shows how a USSD message is relayed from your application to the mobile subscriber through the sms gateway.

Step 1 Mobile subscriber Dials the USSD code

A mobile subscriber initiates a session by dialing a specific USSD code, such as *123*XXX#. This USSD code is a predefined code that triggers the USSD session, enabling communication between the subscriber’s mobile device and the service provider. Once the USSD code is dialed, a request is sent to the mobile operator.

Step 2 Mobile subscriber Dials the USSD code

Once the mobile operator receives the request, the mobile operator makes an HTTP request to the Tiara USSD Gateway.

NOTE: The request structure is not necessary for developers.

Step 3 Forward request to your USSD application

The USSD gateway validates and processes the request forwarded by the mobile operator (telco). It then determines the appropriate endpoint for your application. The USSD Gateway makes an HTTP POST request to your USSD application via a HTTP URL. This request is URL encoded , containing key information like the sessionId, subscriber details and user input. The request structure for this POST request sent to your application is specified below.

HTTP Header Parameters

The USSD request sent to your application is a HTTP request with the following header parameters set in the request.

HTTP Body Parameters

The table below specifies the parameters in the USSD request sent to your application.

Sample HTTP Body

The request is URL Encoded:

msisdn=2547XXXXXXXX&sessionId=149505148&input=1&serviceCode=*123*12#&countryCode=254&network=Safaricom+KE

Step 4 Forward the USSD Menu response to the messaging gateway

Your application responds with the appropriate USSD menu response, which could include a menu of options or instructions for the subscriber. The response is sent back to the USSD gateway via the HTTP response from the 3rd party USSD app. The response structure with the USSD menu is specified below.

The response should be text starting with either CON or END:

• CON - reply and continue with the session (we expect a reply from the end user).
• END - reply and end the session.

Sample Response Success Continue

     CON Welcome to ABC\n Please enter your name

Sample Response Success End

     END Thank you for registering

NOTE: Session management will be done by the 3rd party USSD application.

Step 5 Forward USSD Menu response to the Mobile Operator

The Tiara USSD Gateway forwards the USSD menu response to the mobile operator.

NOTE: The request structure is not necessary for developers.

Step 6 Forward the USSD Menu response to the Mobile Subscriber

The mobile operator then forwards the menu to the end user (mobile subscriber/phone). The mobile subscriber sees the USSD menu on their screen and can interact with it.

The process continues with each response from the subscriber triggering a new request and the menu response cycle until the session is completed or terminated by the subscriber.