Message Template and Callback Formats

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.

      1. Implement the payload formats for the request sent by MoEngage are shared in the Send message template section.
      2. Send the callback information to MoEngage in the format shared in the Message Status Callbacks section.
      3. Whenever inbound messages are sent to MoEngage, from quick reply buttons, follow the format shared in the Inbound Messages section.
      4. 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, APP 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.

Sample Header
--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.

Python

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

Sample cURL

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" : {
      "code" : "ERROR_CODE",
      "message" : "ERROR_DESCRIPTION"
 }

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
200 4xx 5xx

Sample response for a successful request
{
  "status": "success | failure",
  "error" : {
  	"code" : "ERROR_CODE",
  	"message" : "ERROR_DESCRIPTION"
  }
}

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

Python
{
   "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.

Java

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

Previous

Next

Was this article helpful?
2 out of 3 found this helpful

How can we improve this article?