Get Started

Introduction

The Tingg Engage API is a single global entry point for all transactional alerts into the engage ecosystem. It is the interface provided for all our customers.
This service used to send single SMS requests that are transactional. This means that after an external service performs an action and requires to inform a user via sms, it invokes this API. The category of messages that can be sent out is OTPs, TRX (transactional) or just normal messages. This API can be invoked by internal services within Cellulant or external customers.
This API receives requests to send SMSs or Emails. Before an SMS or email can be sent using this API, the following are the prerequisites that need to be done on the Tingg Engage platform.

Set up a notification template for either SMS or email
Set up an MNO connector that will be used to send SMSs

Payloads

Generate Token

Below is the expected payload used to invoke the get token endpoint.

Api endpoint: https://api-dev.tingg.africa/api/v1/cas/authenticate

{
   "username":"TEST_USER",
   "password":"TEST_PASSWORD"
}

Parameter	Type	Mandatory	Description
Username {username}	String	YES	The username shared to get a token.
Password {password}	String	YES	The password required to login to the platform.

Generate Token Response

Below is the response we get once we invoke the generate token endpoint

{
    "token_type": "bearer",
    "expires_in": 3600,
    "access_token": "eyJraWQiOiJjYXMtcGsiLCJhbGciOiJSUzUxMiJ9.eyJzdWIiOiI3IiwicGFyZW50IjoiR2VvcmdlX0dhdGhlY2EiLCJsZXZlbCI6IkNVU1RPTUVSIiwiaXNzIjoiaHR0cDovL2Nhcy1hcGkuZGV2ZWxvcG1lbnQ6ODA4MC8iLCJ1dHlwZSI6IkFQSSIsImF1ZCI6Ik1lc3NhZ2luZ1BsYXRmb3JtIiwicGhvbmUiOiIyNTQ3MjEwMDIwMCIsIm5hbWUiOiJyZWNvbi1hZG1pbiIsImNsaWVudCI6Ikdlb3JnZV9HYXRoZWNhIiwiZXhwIjoxNjg4NDYxNDE1LCJpYXQiOjE2ODg0NTc4MTUsImN1c3RfaWQiOjEsImp0aSI6IjI1NThjMDc2LTk0M2MtNGVjOS1iYzhiLWQ4MTUxNjlmMTcyYWQ5Yjc4MzE2LWQ0ODUtNDcwYi1hY2VmLWFkYTRmM2FjYjgyMCIsImVtYWlsIjoicmVjb24tYWRtaW5AY2VsbHVsYW50LmNvbSJ9.IjjLJJ8fvsKhuMW4kagi7uPT2vYrajILNDSAmtudWJFO97USs45kXmc32u3PGegMUM50hVfFyCbXIkcSbndPkZvts4-Sv9rWFvQgUKukJLDmMLlGCwIxanPyRFVdphFRT4HCfJgQG1ZTjVlPPqjylxLHeG3QdQBHsoP38yU08oK0JnKQOn6o7LZ_humxz0TKUBrvYtfH9io_syRs6RvwTe3z2Zq1dG97RHCLfZkEYiXRbUD28GOd4PJEiZ3iWD4xeUL9OBnQtk2smCSBIXsbr788nbk4wGsarj_sFZAXqsqgKZGazHr7I3WXvxllKLrkk_xX42wl_-1wOqQPwVkF7Q",
    "refresh_token": "eVZnMVd3OWpTTFF2MEd5Wm04eWFjRlkySjd4NEt0bmovYmQyNlFid3hmdDJIcVQyVnVucGlIV2VBTjhBTjJzZWJ2bHV0SFJWUnBrMzRXZGkzQjdpOVE9PQ=="
}

Parameter	Type	Mandatory	Description
Token Type {token_type}	String	YES	This tells us the type of token to expect.
Expires In {expires_in}	String	YES	This tells us how long the token is valid.
Access Token {access_token}	String	YES	This holds the token to be used.

### Engagement Service API V2 Payload SMS

Below is the payload that is used to invoke the engagement service api for processing a single request.
Please note that to invoke the endpoint provide a bearer token which the token is generated from 2.1 above and the response seen on 2.2

Api endpoint: https://api-dev.tingg.africa/api/v2/engagement

{
  "notificationType": "SMS_TEST",
  "channels": [
    "SMS"
  ],
  "referenceID": "cas-123",
  "callbackUrl": "https://client.callback.url/",
    "smsDto": {
    "smsType": "TRX",
    "msisdn": [
      "254700000000",
      "254700000000"
    ],
    "message": "Test message ${placeholder}",
    "params": {
      "placeholder": "value"
    },
    "extraData": {
      "clientinfo": "additional client info"
    }
  }
}

Parameter	Type	Mandatory	Description
Notification Type {notificationType}	String	YES	The type of notification message to be sent.
Message {message}	String	YES	The default message content for the notification. Will be used if no template exists.
Reference ID {referenceID}	String	YES	Local reference for the message request. Has to be unique per request
CallbackURL {callbackURL}	String	NO	Contains the callback url
MSISDN {msisdn}	List	NO	The recipient address if the message is to be sent via phone number
Email Address {email}	List	NO	The recipient address if the message is to be sent using an email address
Parameters {params}	Object	NO	Message template parameters. Will be used to formulate the final message from the template.
Channels {channels}	Object	YES	This is used to hold the channels you want your message to be explicitly sent with. If one does not specify we will use the default ones configured

Response Payload

Below is the expected payload response structure

{
     "transactionID": "{uuid}",
     "statusCode": 200,
     "message": "Message queued successfully."
}

Parameter	Type	Mandatory	Description
Transaction ID {transactionID}	String	YES	The unique ID assigned to the request on the engagement platform.
Status Code {statusCode}	Integer	YES	The status of the request.
Message {message}	String	YES	A short description on the current request status.

Callback URL Response

The below response payload is sent to the callback URL provided.

Parameter Name	Type	Mandatory	Description
Transaction ID {refId}	String	Yes	Local reference for the message request.
Status Code {status}	Integer	Yes	This represents status of the transaction.
Msisdn {msisdn}	String	Yes	The recipient address if the message is to be sent via phone number.
Status Description {statusDescription}	String	Yes	A description regarding the current state of the transaction.
Timestamp {timestamp}	String	Yes	The time period when the payload was created.
Received Time {receivedDateTime}	String	Yes	This indicates the time the request was received on our systems.
Submit Time {submitDateTime}	String	No	This indicates the time the request was sent to the operator.
Done Time {doneDateTime}	String	No	This indicates the time the message was marked in final status.

Sample Response

{
    "refId": "0103fd2e-e784-469f-8cee-7d87720f2b98_6371f87b-aa3b-4387-850d-c6aa1153286a9",
    "status": 103,
    "msisdn": "254773301164",
    "statusDescription": "Forwarded to operator",
    "timestamp": "2024-04-11T09:34:31.066667",
    "receivedDateTime": "2024-04-11 09:34:30.749",
    "submitDateTime": "2024-04-11 09:34:30.761",
    "doneDateTime": null
}

Status Codes

Status Codes	Description	Final Status
100	SMS pending and being processed within Cellulant’s systems.	false
102	Error during preprocessing of message. Check description to determine what is wrong with the request	true
105	Error during preprocessing of message. Check description to determine what is wrong with the request	true
103	Sms has been forwarded to the mobile network operator. Pending a delivery receipt from the mobile network operator	false
104	Sms processed and delivered successfully.	true
129	Delivery of SMS failed on the mobile network operator side.	true