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

Headers

Header	Value	Description	Required
Authorization	Bearer	The JWT token issued during authentication. Used to authenticate and authorise requests.	YES
Content-Type	application/json	Data interchange format for the request	YES

Request

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

Sample Request

{
  "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"
    }
  }
}

Response

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.

Sample Response

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

Callback URL Payload

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 Callback Payload

{
    "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
}

Callback 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