Steps to Onboard with MoEngage
This article describes the standard payload formats that MoEngage uses for sending WhatsApp template messages and standard callback formats for delivering callback information to MoEngage. WhatsApp partners should follow the steps mentioned below to onboard with MoEngage.
-
-
- Implement the payload formats for the request sent by MoEngage are shared in the Send message template section.
- Send the callback information to MoEngage in the format shared in the Message Status Callbacks section.
- Whenever inbound messages are sent to MoEngage, from quick reply buttons, follow the format shared in the Inbound Messages section.
- Share the API Endpoint and request headers to be used by the MoEngage team to complete the testing and onboard customers.
-
Send Message Template
This section details the message payload in the request sent by MoEngage to your API.
API Endpoint/URL
The API Endpoint or API URL of the partner to whom the message is being sent. This would be provided by the Whatsapp partner.
Sample Request Headers
You will have to share the information about the headers to be added to the request, such as the API Key, Workspace ID, Authentication, and so on. For example, if the Authentication to be used is Bearer Authentication, MoEngage will add the same in the Authorization Header in the Request, a sample for which is shown below.
--header 'Authentication: Bearer <client auth token to be used by vendor>' \
Request Body
This is the request sent by MoEngage to your API.
Key | Required | Data Type | Description |
---|---|---|---|
msg_id | Required | String | This is the unique identifier for the message sent from MoEngage. This ID needs to be returned in the delivery callback sent to MoEngage. |
from | Required | String | This is the WhatsApp Business Account (WABA) number of the brand sending the message. |
to | Required | String |
This is the WhatsApp number of the user to whom the message is being sent. The number has to be sent in the E.164 format. |
template | Required | Object |
This object contains information about the template using which the message is being sent. It contains the template name, language, and components such as header, body, and buttons. For more information, refer to Template Object. |
Template Object
WhatsApp templates need to be pre-approved by WhatsApp to be used for sending messages. For more information, refer to WhatsApp Templates.
Key | Required | Data Type | Description |
---|---|---|---|
name | Required | String | This field represents the name of the template. |
language | Required | Object |
This field specifies the language the template may be rendered in. Structure: "language": {"code": "LANGUAGE_CODE"} code represents the code of the language or the locale code to use. For more information, refer to Supported Languages. |
components | Optional | String | This field contains the components of WhatsApp, such as the header, body, and buttons. This field will vary based on the template being used. For more information, refer to Components Object. |
The Template Object described in this section follows the same structure as that of the Template Object available in Meta's WhatsApp Messages References. For more information, refer to Template Object in Messages.
Sample Payload
A Sample Payload for a request sent by MoEngage is shared below. Note that the sample payload will differ based on the template chosen.
{
"msg_id": "MESSAGE_ID", # Unique identifier, to be returned in callback
"from": "WABA NUMBER",
"to": "PHONE_NUMBER", # To number would be in E.164 format
"template": {
"name": "TEMPLATE_NAME",
"language": {
"code": "LANGUAGE_CODE"
},
"components": [
{
"type": "header",
"parameters": [
{
"type": "image",
"image": {
"link": "http(s)://URL"
}
}
]
},
{
"type": "body",
"parameters": [
{
"type": "text",
"text": "TEXT_STRING"
},
{
"type": "currency",
"currency": {
"fallback_value": "VALUE",
"code": "USD",
"amount_1000": "NUMBER"
}
},
{
"type": "date_time",
"date_time": {
"fallback_value": "MONTH DAY, YEAR"
}
}
]
}
]
}
}
Sample cURL Request
curl --location '<api_url provided by the vendor>' \
--header 'Content-Type: application/json' \
--header 'Authentication: Bearer <client auth token to be used by vendor>' \
--data '<payload>'
Expected Response
Key | Required | Data Type | Description |
---|---|---|---|
status | Required | String |
This field represents the status of the request and indicates whether the message was sent successfully or not and should be present only in the case of a 2xx response. Allowed values: success, failure |
error | Required | Object |
This field specifies the error code and error message in the case of failures nd should be present only in the case of a 2xx response. Structure: "error" : { The Error Code and the corresponding error messages that are to be returned (in the error object) to MoEngage in the case of a 2xx failure are detailed in Error Codes. |
message | Optional | String | This field contains the description of errors when there are 4xx and 5xx errors. |
Error Codes
Error Code | When to return this error code? |
---|---|
7000 |
Invalid credentials |
7001 |
Invalid template parameters |
7002 | Invalid phone number |
7003 | When the phone number has not subscribed to receiving WhatsApp messages |
7004 | Other errors |
Sample response for a successful request
{
"status": "success | failure",
"error" : {
"code" : "ERROR_CODE",
"message" : "ERROR_DESCRIPTION"
}
}
Sample response for 4xx errors
{
"message": "ERROR_DESCRIPTON"
}
Sample response for unknown errors
{
"message": "ERROR_DESCRIPTON"
}
Throughput
We support a throughput of 60K to 200K RPM.
Message Status Callbacks
The format to be used for sending the message status in your callback response to MoEngage is described below.
Callback URL
The callback URL will be generated for every partner and would be in the following format:
Authentication
Authentication is not required, and we will accept all valid requests that conform to the format mentioned in the section below.
Format for Callback Response
{
"statuses": [
{
"msg_id": "MESSAGE_ID", # From send message req
"status": "sent | delivered | read | failed",
"timestamp": "TIMESTAMP", # Event timestamp (epoch)
"error": { #Optional in case of failure
"code": "ERROR_CODE",
"description": "ERROR_DESCRIPTION"
}
},
{
#Support multiple status callbacks in a single request
}
]
}
Key | Required | Data Type | Description |
---|---|---|---|
msg_id | Required | String | This field represents the unique identifier for the message sent in the request from MoEngage. |
status | Required | String |
This field represents the status of the message. Allowed Values: sent, delivered, read, and failed |
timestamp | Required | String |
This field represents the timestamp of when the message was attempted to be delivered. The timestamp should be sent as an epoch number. |
error | Optional | Object | This field represents the error encountered when sending the message to the recipient and contains the error's code and description. For more information on the error codes to be sent, refer to Error Codes. |
Inbound Messages
MoEngage supports incoming text messages for the following use cases:
-
-
- When a user sends a STOP message for unsubscribing.
- When a user replies using quick reply buttons to a WhatsApp message sent.
- When a user replies by clicking on a button in the WhatsApp message sent.
-
Format for Inbound Messages
The format to be used for inbound messages to MoEngage is described below.
{
"from": "MOBILE_NUMBER",
"waba_number": "BUSINESS_WABA_NUMBER",
"timestamp": "TIMESTAMP",
"type": "text | button",
"context": {
"msg_id": "MESSAGE_ID"
},
"text": { # Optional if type is button (quick reply button)
"body": "INCOMING_MESSAGE"
},
"button": { # Optional if type is text
"payload": "{'orderid' : '12345', 'reply': 'yes'}",
"text": "Yes, cancel it"
}
}
Key | Required | Data Type | Description |
---|---|---|---|
from | Required | String | This is the WhatsApp number of the user sending the message. The number has to be sent in the E.164 format. |
waba_number | Required | String | This is the brand's WhatsApp Business Account (WABA) number receiving the message. |
timestamp | Required | String |
This field represents the timestamp at which the response was received from the user and should be in the epoch number format. |
msg_id | Required | String | This field represents the unique identifier for the message sent in the request from MoEngage. |
type | Required | String |
This field represents the type of message being sent - whether it is a text message or a reply from a button Allowed Values: text, button |
context | Required | Object |
This object contains the message id of the request from MoEngage for which the message was sent to the user and to which the user is replying. Structure: "context": { "msg_id": "MESSAGE_ID" } the msg_id field is sent in the request originating from MoEngage. For more information, refer to Send Message Template. |
text | Optional | String |
This field contains the incoming text message and is mandatory when the type is text. Structure: "text": { "body": "INCOMING_MESSAGE" } |
button | Optional | String |
This field contains the incoming message from a quick reply button and is mandatory when the type is button. Structure: "button": { "payload": "{'orderid' : '12345', 'reply': 'yes'}", "text": "Yes, cancel it" } |