Send Read Receipt Messages
Using the 'Read Receipt API' message, you can send a 'read' receipt, when an incoming message is received on the business webhook. When the 'read' status message is sent, a double blue tick mark is added next to the timestamp of the message sent by the customer on the customer's mobile phone.
The 'messaging_object' in the payload holds the information about the status message and the message ID of the message for which the 'read' status should be sent.
The extra_info part of the payload contains any additional information related to the API requests submitted to send the coupon code message.
Note:
Marking a message as 'read' will also mark earlier messages in the conversation as 'read'.
Prerequisites
- Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
A prerequisite for using Kaleyra WhatsApp APIs is to have an active WhatsApp plan on kaleyra platform. - To set up a WhatsApp account on kaleyra.io, see Manual Signup
and Embedded Signup. - An active WhatsApp for Business API plan that includes:
- A WhatsApp business number.
- An associated profile with the business number.
- A WhatsApp verified and approved profile.
Base URL
https://<api_domain>/v2/<SID>
API Domain and Value
api_domain | Value |
---|---|
IN pod | api.in.kaleyra.io |
SG Pod | api.ap.kaleyra.io |
EU Pod | api.eu.kaleyra.io |
API Request to Send Read Receipt Messages
To send a Read Receipt message, use the https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/messages
endpoint with the following request method:
Request Format
The following is the request format to send a read receipt message.
curl -X POST \
'https://<api_domain>/v2/<sid>/whatsapp/<phone_number>/messages' \
-H 'Content-Type: application/json' \
-H 'api-key: <api-key>' \
-H 'cache-control: no-cache' \
-d '{
"messaging_object": {
"messaging_product": "<messaging_product>",
"status": "<read_status>",
"message_id": "<message_id>"
},
"extra_info": {
"ref": "<ref>
"ref1": "<ref1>",
"ref2": "<ref2>",
"wa_source": "<wa_source>"
}
}'
Sample Request Format
The following is a sample request format to send a read receipt message.
curl -X POST \
'https://api.in.kaleyra.io/v2/xxxxx6913850xxxx/whatsapp/+91xxxxxxx124/messages' \
-H 'Content-Type: application/json' \
-H 'api-key: xxxxx3b8497f58a94e84b671aca43xxxx' \
-H 'cache-control: no-cache' \
-d '{
"messaging_object": {
"messaging_product": "whatsapp",
"status": "read",
"message_id": "AXXXXXXXXXXXXXXXXXXX"
},
"extra_info": {
"ref": "customer1",
"ref1": "marketing",
"ref2": "dictionary",
"wa_source": "api"
}
}'
URL Parameters and Headers
Following is the list of parameters and headers to send the read receipt status message:
Parameter / Headers | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
sid | String | Account SID (Security Identifier). | HXAP16XXXXXX97IN | Yes |
phone_number | String | Phone number of the end customer you want to send a message to. | +91XXXXXXXXXX | Yes (valid phone numbers only) |
Content-Type | String | Indicates the format of the content the API will be processing. | The only allowed value is application/json. | Yes |
api-key | String | API key generated from kaleyra platform account. | Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3 | Yes |
Following is the list of attributes to be used in the payload to send the outgoing message:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
messaging_object | JSON object | Payload is supported only in JSON format. The messaging_object is the payload which contains the message object as defined by Meta which is used to send the WhatsApp message. | See the specific table for details. | Yes |
extra_info | JSON object | This object will contain additional details that a user can send for certain functionalities. | See the specific table for details. | No |
The following table describes the different attributes used for the messaging_object
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
messaging_product | String | Messaging service used for the request. | Only allowed value is whatsapp | Yes |
status | String | Message status | read | Yes |
message_id | String | The message ID of the message for which the status is set. | AXXXXXXXXXXXXXXXXXXX | Yes |
The following table describes the different attributes used for the extra_info
JSON object:
Parameter | Data Type | Description | Example | Mandatory? |
---|---|---|---|---|
ref | String | Include any contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more. Limit: The variable can be 255 characters long only. This parameter will be available in report and callback. | customer1 | No |
ref1 | String | Include the contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more. Limit: The variable can be 255 characters long only. This parameter will be available in report and callback. | marketing | No |
ref2 | String | Include the contextual information in this parameter you want to associate with the request. For Example, Name, Customer ID, and many more. Limit: The variable can be 255 characters long only. This parameter will be available in report and callback. | dictionary | No |
wa_source | String | Indicates the source from where the API has been triggered. Supported values for wa_source are "api", "clevertap", "zoho", "webengage", "shopify", "leadsquared", "responsys", "braze", "hubspot", "salesforce", "zapier", "eloqua", and "moengage". Note: If the customer passes any other value other than above-specified values, then the system will override that as the "API". | api | No |
Sample Success Response
The following success message appears with the status 202 Accepted:
202 Accepted
{
"code":"WA202"
"message":"Request Accepted",
"data":{
"message_id":"AXXXXXXXXXXXXXXXXXXX"
}
"error":{}
}
Failure Responses
Following are the error responses for the API level and the business level validations.
Sample Failure Response
The following are the failure responses:
401 Unauthorized
{
"code": "RBC001",
"message": "Incorrect SID or API key.",
"data": [],
"error": {
"error": "Incorrect SID or API key."
}
}
401 Unauthorized phone number
{
"code": "WA401",
"message": "Phone number is not present or does not belong to the account.",
"data": {},
"error": {
"phone_number": "Phone number is not present or does not belong to the account."
}
}
400 Incorrect payload
{
"code": "WA400",
"message": "Refer to correct payload format",
"data": {},
"error": {
"payload": "Incorrect payload format"
}
}
500 Internal Server Error
{
"code": "WA500",
"message": "Please try again later",
"data": {},
"error": {
"error": "Internal server error"
}
}
400 Low balance
{
"code": "E110",
"message": "Please check your balance, You have a low balance!",
"data": {},
"error": {
"balance": "Please check your balance, You have a low balance!"
}
}
401 Unauthorised Account type
{
"code": "WA-401",
"message": "API is not available for given customer.Please contact support for more info",
"data": {},
"error": {
"account": "API is not available for given customer.Please contact support for more info"
}
}
401 Unauthorized phone number version
{
"code": "WA-401",
"message": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint.",
"data": {},
"error": {
"phone_number": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint."
}
}
Updated about 16 hours ago