Engagement Service API v2

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

HeaderValueRequired
AuthorizationBearer <BEARER_TOKEN> Generated during the authenticate requestYES
Content-Typeapplication/jsonYES

Request

ParameterTypeMandatoryDescription
Notification Type
{notificationType}
StringYESThe type of notification message to be sent.
Message
{message}
StringYESThe default message content for the notification. Will be used if no template exists.
Reference ID
{referenceID}
StringYESLocal reference for the message request. Has to be unique per request
CallbackURL
{callbackURL}
StringNOContains the callback url
MSISDN
{msisdn}
ListNOThe recipient address if the message is to be sent via phone number
Email Address
{email}
ListNOThe recipient address if the message is to be sent using an email address
Parameters
{params}
ObjectNOMessage template parameters. Will be used to formulate the final message from the template.
Channels
{channels}
ObjectYESThis 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

ParameterTypeMandatoryDescription
Transaction ID
{transactionID}
StringYESThe unique ID assigned to the request on the engagement platform.
Status Code
{statusCode}
IntegerYESThe status of the request.
Message
{message}
StringYESA 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 NameTypeMandatoryDescription
Transaction ID {refId}StringYesLocal reference for the message request.
Status Code {status}IntegerYesThis represents status of the transaction.
Msisdn {msisdn}StringYesThe recipient address if the message is to be sent via phone number.
Status Description {statusDescription}StringYesA description regarding the current state of the transaction.
Timestamp {timestamp}StringYesThe time period when the payload was created.
Received Time
{receivedDateTime}
StringYesThis indicates the time the request was received on our systems.
Submit Time
{submitDateTime}
StringNoThis indicates the time the request was sent to the operator.
Done Time
{doneDateTime}
StringNoThis 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 CodesDescriptionFinal Status
100SMS pending and being processed within Cellulant’s systems.false
102Error during preprocessing of message. Check description to determine what is wrong with the requesttrue
105Error during preprocessing of message. Check description to determine what is wrong with the requesttrue
103Sms has been forwarded to the mobile network operator. Pending a delivery receipt from the mobile network operatorfalse
104Sms processed and delivered successfully.true
129Delivery of SMS failed on the mobile network operator side.true
Language
Click Try It! to start a request and see the response here!