回调配置
消息状态回调
回调地址
回调请求方式
回调内容
参数列表
| 参数名 |
类型 |
必传 |
描述 |
| event |
string |
是 |
回调事件名称，这里为 "message_status_update" |
| channel_id |
int |
是 |
INCS 的消息通道ID |
| business_phone |
string |
是 |
whatsapp business phone number |
| message_id |
string |
是 |
WABA message ID |
| message_status |
string |
是 |
消息状态：sent, failed, delivered, read |
| error |
object|null |
是 |
错误信息，没有错误时为 null，有错误时为 object |
| error.title |
string |
否 |
错误描述 |
| error.code |
int |
否 |
WABA 定义的错误码 |
| received_at |
timestamp |
是 |
消息状态变更时间 |
回调示例
{
"event": "message_status_update",
"channel_id": 30058,
"business_phone": "6281519236680",
"message_id": "wamid.HBgNNjI4OTY1MjQ1NjU0OBUCABEYEkYxNTY4NkNBRUY...",
"message_status": "failed",
"error": {
"code": 131049,
"title": "This message was not delivered to maintain healthy ecosystem engagement."
},
"received_at": 1754466101
},
模板更新回调
回调地址
回调请求方式
回调内容
参数列表
| 参数名 |
类型 |
必传 |
描述 |
| event |
string |
是 |
回调事件名称 |
| channel_id |
int |
是 |
INCS 消息通道 ID，对应创建该模板使用的通道 |
| business_phone |
string |
是 |
whatsapp business phone number |
| template_id |
string |
是 |
模板ID |
| new_value |
string |
是 |
对应的新值 |
| reason |
string |
是 |
变更说明 |
| received_at |
timestamp |
是 |
变更时间 |
回调事件
| 事件名 |
描述 |
| template_status_update |
模板状态变更通知 |
| template_category_update |
模板类别变更通知 |
| template_quality_update |
模板质量评分变更通知 |
回调示例
// 状态更新
{
"event": "template_status_update",
"channel_id": 30058,
"business_phone": "6281519236680",
"template_id": "1287380349540668",
"template_name": "tmp_test",
"new_value": "APPROVED",
"reason": "",
"received_at": 1754466101
}
// 类别更新
{
"event": "template_category_update",
"channel_id": 30058,
"business_phone": "6281519236680",
"template_id": "1287380349540668",
"template_name": "tmp_test",
"new_value": "MARKETING",
"reason": "",
"received_at": 1754466101
}
// 质量评分更新
{
"event": "template_quality_update",
"channel_id": 30058,
"business_phone": "6281519236680",
"template_id": "1287380349540668",
"template_name": "tmp_test",
"new_value": "YELLOW",
"reason": "",
"received_at": 1754466101
}
新消息回调 -- WhatsApp
回调地址
回调请求方式
回调内容
参数说明
| 参数名 |
类型 |
必传 |
描述 |
| event |
string |
是 |
回调事件名称，这里为 "new_message" |
| channel_id |
int |
是 |
INCS 消息通道 ID |
| business_phone |
string |
是 |
whatsapp business phone number |
| message |
object |
是 |
WhatsApp 消息内容，不同的消息内容会有所差别 |
Message Object
| Name |
Description |
contacts*array of objects*
|
Array of contact objects with information for the customer who sent a message to the business. Contact objects have the following properties:
-
wa_id — String. The customer's WhatsApp ID. A business can respond to a customer using this ID. This ID may not match the customer's phone number, which is returned by the API as input when sending a message to the customer.
-
profile — Object. A customer profile object. Profile objects have the following properties:
name — String. The customer's name.
|
messaging_product*string*
|
Product used to send the message. Value is always whatsapp.
|
messages*array of objects*
|
Information about a message received by the business that is subscribed to the webhook.
|
metadata*object*
|
A metadata object describing the business subscribed to the webhook. Metadata objects have the following properties:
display_phone_number — String. The phone number that is displayed for a business.phone_number_id — String. ID for the phone number. A business can respond to a message using this ID.
|
Message.Messages Objects
| Name |
Description |
audio*object*
|
When the messages type is set to audio, including voice messages, this object is included in the messages object:
id — String. ID for the audio file.mime_type — String. Mime type of the audio file.
|
button*object*
|
When the messages type field is set to button, this object is included in the messages object:
payload – String. The payload for a button set up by the business that a customer clicked as part of an interactive message.text — String. Button text.
|
context*object*
|
Context object. Only included when a user replies or interacts with one of your messages. Context objects can have the following properties:
forwarded — Boolean. Set to true if the message received by the business has been forwarded.frequently_forwarded — Boolean. Set to true if the message received by the business has been forwarded more than 5 times.from — String. The WhatsApp ID for the customer who replied to an inbound message.id — String. The message ID for the sent message for an inbound reply.-
referred_product — Object. Referred product object describing the product the user is requesting information about. You must parse this value if you support Product Enquiry Messages Referred product objects have the following properties:
catalog_id — String. Unique identifier of the Meta catalog linked to the WhatsApp Business Account.product_retailer_id — String. Unique identifier of the product in a catalog.
|
document*object*
|
A document object. When messages type is set to document, this object is included in the messages object. Document objects can have the following properties:
caption — String. Caption for the document, if provided.filename — String. Name for the file on the sender's device.sha256 — String. SHA 256 hash.mime_type — String. Mime type of the document file.id — String. ID for the document.
|
errors*array of objects*
|
An array of error objects describing the error. Error objects have the following properties.
code — Integer. Error code. Example: 130429.title — String. Error code title. Example: Rate limit hit.message — String. Error code message. This value is the same as the title value. For example: Rate limit hit. Note that the message property in API error response payloads pre-pends this value with the a # symbol and the error code in parenthesis. For example: (#130429) Rate limit hit.-
error_data — Object. An error data object with the following properties:
details — String. Describes the error. Example: Message failed to send because there were too many messages sent from this phone number in a short period of time.
|
from*string*
|
The customer's WhatsApp ID. A business can respond to a customer using this ID. This ID may not match the customer's phone number, which is returned by the API as input when sending a message to the customer.
|
id*string*
|
The ID for the message that was received by the business.
|
identity*object*
|
An identity object. See messages system identity. Identity objects can have the following properties:
acknowledged — State of acknowledgment for the messages system customer_identity_changed.created_timestamp — String. The time when the WhatsApp Business Management API detected the customer may have changed their profile information.hash — String. The ID for the messages system customer_identity_changed.
|
image*object*
|
When messages type is set to image, this object is included in the messages object.
caption — String. Caption for the image, if provided.sha256 — String. Image hash.id — String. ID for the image.mime_type — String. Mime type for the image.
|
interactive*object*
|
When a customer has interacted with your message, this object is included in the messages object. Interactive objects have the following properties:
-
type — Object with the following properties:
-
button_reply – Sent when a customer clicks a button. Object with the following properties:
id — String. Unique ID of a button.title — String. Title of a button.
-
list_reply — Sent when a customer selects an item from a list. Object with the following properties:
id — String. Unique ID of the selected list item.title — String. Title of the selected list item.description — String. Description of the selected row.
|
order*object*
|
Included in the messages object when a customer has placed an order. Order objects have the following properties:
catalog_id — String. ID for the catalog the ordered item belongs to.text — String. Text message from the user sent along with the order.-
product_items — Array of product item objects containing the following fields:
product_retailer_id — String. Unique identifier of the product in a catalog.quantity — String. Number of items.item_price — String. Price of each item.currency — String. Price currency.
|
referral*object*
|
Referral object. When a customer clicks an ad that redirects to WhatsApp, this object is included in the messages object. Referral objects have the following properties:
source_url – String. The Meta URL that leads to the ad or post clicked by the customer. Opening this url takes you to the ad viewed by your customer.source_type – String. The type of the ad’s source; ad or post.source_id – String. Meta ID for an ad or a post.headline – String. Headline used in the ad or post.body – String. Body for the ad or post.media_type – String. Media present in the ad or post; image or video.image_url – String. URL of the image, when media_type is an image.video_url – String. URL of the video, when media_type is a video.thumbnail_url – String. URL for the thumbnail, when media_type is a video.ctwa_clid – String. Click ID generated by Meta for ads that click to WhatsApp.
The referral object can be included in the following types of message: text, location, contact, image, video, document, voice, and sticker. Click-to-WhatsApp ads are only supported in the Android and iOS apps. If the customer is using the Web browser or their computer to click on an ad, then the resulting webhook will contain a referral object without some of the above properties.
|
sticker*object*
|
When messages type is set to sticker, this object is included in the messages object. Sticker objects have the following properties:
mime_type – String. image/webp.sha256 – String. Hash for the sticker.id – String. ID for the sticker.animated – Boolean. Set to true if the sticker is animated; false otherwise.
|
system*object*
|
When messages type is set to system, a customer has updated their phone number or profile information, this object is included in the messages object. System objects have the following properties:
body – String. Describes the change to the customer's identity or phone number.identity – String. Hash for the identity fetched from server.new_wa_id – String. New WhatsApp ID for the customer when their phone number is updated. Available on webhook versions v11.0 and earlier.wa_id – String. New WhatsApp ID for the customer when their phone number is updated. Available on webhook versions v12.0 and later.-
type – String. Type of system update. Will be one of the following:
customer_changed_number – A customer changed their phone number.customer_identity_changed – A customer changed their profile information.
customer – String. The WhatsApp ID for the customer prior to the update.group_id - String. If set, corresponds to which thread the system message was sent in. If you share multiple groups with this user, you will receive multiple webhooks.
|
text*object*
|
When messages type is set to text, this object is included. Text objects have the following properties:
body — String. The text of the message.
|
timestamp*string*
|
Unix timestamp indicating when the WhatsApp server received the message from the customer.
|
type*string*
|
The type of message that has been received by the business that has subscribed to Webhooks. Possible value can be one of the following: audio button document text image interactive order sticker system – for customer number change messages unknown video
|
video*object*
|
When messages type is set to video, this object is included in messages object. Video objects have the following properties:
caption – String. The caption for the video, if provided.sha256 – String. The hash for the video.id – String. The ID for the video.mime_type – String. The mime type for the video file.
|
回调示例
text 纯文本
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [ // 发信人信息
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQUY1Qjc4MUQzNjM3OTk1QUVENQA=",
"timestamp": "1756109460",
"text": {
"body": "hello"
},
"type": "text"
}
]
}
}
reaction 引用回复
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"context": { // 引用的消息
"from": "6281519236680",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgARGBI5RkEyNjU2NEUwMDhBRDMxNTEA"
},
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQTY5OUZERjU5MDZBQzUyN0Y0MgA=",
"timestamp": "1756113398",
"text": {
"body": "OK"
},
"type": "text"
}
]
}
}
image 图片
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQUZCMzlCREIwMDdCMkYzRjZBQgA=",
"timestamp": "1756111162",
"type": "image",
"image": {
"mime_type": "image\/jpeg",
"sha256": "X+rJ8sVYdTYG9nD3JOGjJAb4GE3qw89S8kQNQ2fRj1w=",
"id": "2173590463051074",
"link": "https:\/\/static.incsapp.com\/chat\/images\/2173590463051074.jpg"
}
}
]
}
}
sticker 贴纸
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQUM4MzBCOUIzNTk4RTI1MUE5OQA=",
"timestamp": "1756111078",
"type": "sticker",
"sticker": {
"mime_type": "image\/webp",
"sha256": "1RgjeZcCQQjyzYnvcvInvzes\/n9ThHJ4Ndr3dzGUeP0=",
"id": "782472500814983",
"animated": false,
"link": "https:\/\/static.incsapp.com\/chat\/images\/782472500814983.webp"
}
}
]
}
}
video 视频
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQTA3Qzg2MTAyQTgxRDBCQkQ0RgA=",
"timestamp": "1756111347",
"type": "video",
"video": {
"caption": "beautiful\uff1f", // 用户添加的描述
"mime_type": "video\/mp4",
"sha256": "8m71YIxOHqc3HYGthZiquLeeE0N1Cv0MeTc25ahf4sU=",
"id": "1277927410543839",
"link": "https:\/\/static.incsapp.com\/chat\/videos\/1277927410543839.mp4"
}
}
]
}
}
audio 语音
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQUFBQzc3RUVCQTRCNDMxOTNBMgA=",
"timestamp": "1756112512",
"type": "audio",
"audio": {
"mime_type": "audio\/ogg; codecs=opus",
"sha256": "pp0SvItSzmvP6mRp1mR\/4tn9ydbnv72YWiZ9XxaxTZg=",
"id": "1082985930630339",
"voice": true,
"link": "https:\/\/static.incsapp.com\/chat\/audios\/1082985930630339.ogg"
}
}
]
}
}
document 文档
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQTg3MUUyRjA4RDA3RTdFQzUyNwA=",
"timestamp": "1756112790",
"type": "document",
"document": {
"filename": "email_template_en.xls",
"mime_type": "application\/vnd.ms-excel",
"sha256": "0WWrm0sDQYStNhqArO7uRiViw40SbSP+QALrNGyi4pE=",
"id": "797337589311657",
"link": "https:\/\/static.incsapp.com\/chat\/files\/797337589311657.xls"
}
}
]
}
}
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQTdCQzYyMEM0NjcxQkYzN0VFOQA=",
"timestamp": "1756112662",
"type": "contacts",
"contacts": [
{
"name": {
"first_name": "Lessie Laytoya",
"formatted_name": "Lessie Laytoya"
},
"phones": [
{
"phone": "+85268415026",
"wa_id": "85268415026",
"type": "CELL"
}
]
}
]
}
]
}
}
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"context": { // 选项关联的某条消息
"from": "6281519236680",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgARGBJGNDY4NjdEN0I3QkZCMzg5QjMA"
},
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQUM5MzJGN0EwRThCNTgyRTVFNAA=",
"timestamp": "1756112962",
"type": "button",
"button": {
"payload": "\u8fd8\u6709\u5176\u4ed6\u95ee\u9898",
"text": "\u8fd8\u6709\u5176\u4ed6\u95ee\u9898"
}
}
]
}
}
location 位置
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQTczMTRCMzNDNjgwMzExNkUyNgA=",
"timestamp": "1756113235",
"location": {
"latitude": 22.570337295532,
"longitude": 113.87411499023,
"name": "\u534e\u4e30\u91d1\u878d\u6e2f" // 选填
},
"type": "location"
}
]
}
}
order 订单
- A WhatsApp user orders one or more products via a catalog, single-, or multi-product message.
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"profile": {
"name": "Sheena Nelson"
},
"wa_id": "16505551234"
}
],
"messages": [
{
"from": "16505551234",
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
"timestamp": "1750096325",
"type": "order",
"order": {
"catalog_id": "194836987003835",
"text": "Love these!",
"product_items": [
{
"product_retailer_id": "di9ozbzfi4",
"quantity": 2,
"item_price": 30,
"currency": "USD"
},
{
"product_retailer_id": "nqryix03ez",
"quantity": 1,
"item_price": 25,
"currency": "USD"
}
]
}
}
]
}
}
Interactive 交互式消息
- A WhatsApp user taps a row in an interactive list message.
- A WhatsApp user taps a button in an interactive reply button message.
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "15550783881",
"phone_number_id": "106540352242922"
},
"contacts": [
{
"profile": {
"name": "Sheena Nelson"
},
"wa_id": "16505551234"
}
],
"messages": [
{
"context": {
"from": "15550783881",
"id": "wamid.HBgLMTQxMjU1NTA4MjkVAgASGBQzQUNCNjk5RDUwNUZGMUZEM0VBRAA="
},
"from": "16505551234",
"id": "wamid.HBgLMTY1MDM4Nzk0MzkVAgASGBQzQUFERjg0NDEzNDdFODU3MUMxMAA=",
"timestamp": "1749854575",
"type": "interactive",
"interactive": {
"type": "list_reply",
"list_reply": {
"id": "priority_express",
"title": "Priority Mail Express",
"description": "Next Day to 2 Days"
}
}
}
]
}
}
Unsupported 不支持的消息类型
{
"event": "new_message",
"business_phone": "6281519236680",
"message": {
"messaging_product": "whatsapp",
"metadata": {
"display_phone_number": "6281519236680",
"phone_number_id": "302702419599374"
},
"contacts": [
{
"profile": {
"name": "Lessie Laytoya"
},
"wa_id": "85268415026"
}
],
"messages": [
{
"from": "85268415026",
"id": "wamid.HBgLODUyNjg0MTUwMjYVAgASGBQzQUQ1NzI3MTZFMDlBNEE0RkU4RQA=",
"timestamp": "1756113604",
"errors": [
{
"code": 131051,
"title": "Message type unknown",
"message": "Message type unknown",
"error_data": {
"details": "Message type is currently not supported."
}
}
],
"type": "unsupported"
}
]
}
}
新消息回调 -- RCS
回调地址
回调请求方式
回调内容
参数说明
| 参数名 |
类型 |
必传 |
描述 |
| event |
string |
是 |
回调事件名称，这里为 "new_message" |
| channel_id |
int |
是 |
INCS 的消息通道ID |
| message |
object |
是 |
RCS 消息内容，不同的消息内容会有所差别 |
回调示例
{
"event": "new_message",
"channel_id": 30058,
"business_phone": "",
"message": {
"senderPhoneNumber": "+6281519140000",
"messageId": "da220bf7-e15b-4b2b-90af-1860eb335872",
"sendTime": "2026-02-02T08:11:41.193204Z",
"agentId": "infinity_links_indo_test_promo_tqzwtuox_agent@rbm.goog",
"suggestionResponse": {
"postbackData": "shop_url",
"text": "Buy Now at INCS",
"type": "ACTION"
}
}
}
message 内容示例
1. Text Message
{
"senderPhoneNumber": "+628XXXXXXXXX",
"messageId": "5312df2b-54e3-457d-8654-49a4f3ba1a19",
"sendTime": "2024-04-20T10:11:02.589915Z",
"text": "Hiii",
"agentId": "test_vhbgamhn_agent@rbm.goog"
}
2. File Message
{
"senderPhoneNumber": "+628XXXXXXXXX",
"messageId": "5312df2b-54e3-457d-8654-49a4f3ba1a19",
"sendTime": "2024-04-20T10:58:29.951141Z",
"userFile": {
"thumbnail": {
"mimeType": "image/jpeg",
"fileSizeBytes": 8001,
"fileUri": "https://rcs-user-content-ap.storage.googleapis.com/baf60d40-f197-497f-83f8-5a52fd081262/54b9a1aae33ff62d14ea58db59f43ff04cf62d2329041b110b724b7447a7"
},
"payload": {
"mimeType": "image/jpeg",
"fileSizeBytes": 144594,
"fileName": "1000002217.jpg",
"fileUri": "https://rcs-user-content-ap.storage.googleapis.com/f7cdd990-83ea-4b8d-ba89-73eacf8d7d8a/d63d8f295248fc67cc1716658c169bba70f98b0513798c3c60f56f52734f"
}
},
"agentId": "test_vhbgamhn_agent@rbm.goog"
}
3. Response to suggestion – REPLY
{
"senderPhoneNumber": "+628XXXXXXXXX",
"messageId": "5312df2b-54e3-457d-8654-49a4f3ba1a19",
"sendTime": "2024-04-05T13:15:40.152413Z",
"agentId": "test_vhbgamhn_agent@rbm.goog",
"suggestionResponse": {
"postbackData": "user_reply_what_is_rcs",
"text": "what is RCS?",
"trackdata": {
"suggestionType": "reply",
"msgType": "richcard",
"cardIndex": 0,
"suggestionIndex": 1,
"msgId": "019cc232-229a-7353-b860-87709fa4d7d4",
"msgDate": "2026-03-06T08:09:51.895Z",
"template": "2217703609111640005"
},
"type": "REPLY"
}
}
4. Response to suggestion – ACTION
{
"senderPhoneNumber": "+628XXXXXXXXX",
"messageId": "5312df2b-54e3-457d-8654-49a4f3ba1a19",
"sendTime": "2024-04-05T13:16:42.183829Z",
"agentId": "test_vhbgamhn_agent@rbm.goog",
"suggestionResponse": {
"postbackData": "user_action_open_url",
"text": "visit our website",
"trackdata": {
"suggestionType": "url_action",
"msgType": "richcard",
"cardIndex": 0,
"suggestionIndex": 0,
"msgId": "019cc232-229a-7353-b860-87709fa4d7d4",
"msgDate": "2026-03-06T08:09:51.895Z",
"template": "2217703609111640005"
},
"type": "ACTION"
}
}
5. Location message
{
"senderPhoneNumber": "+62XXXXXXXXXX",
"messageId": "b0d0ea18-c809-4206-9ca2-5baf02707fe0",
"sendTime": "2025-07-29T06:08:36.741050Z",
"agentId": "test_dev_vhbgamhn_agent@rbm.goog",
"location": {
"longitude": 78.3861501,
"latitude": 17.4370557
}
}
INCS 消息回调
回调说明
- INCS 定义的消息格式
- 使用INCS工作台接收和回复消息时，可以设置该回调
回调请求方式
回调内容
1. 消息创建（message_created）
参数说明
| 参数名 |
类型 |
必传 |
描述 |
| event |
string |
是 |
此处为 "message_created"，发送和接收消息时触发该回调 |
| message |
object |
是 |
INCS 定义的消息格式 |
message 结构说明
| 参数名 |
类型 |
必传 |
描述 |
| id |
bigint |
是 |
INCS 消息id |
| auth_id |
int |
是 |
INCS 消息通道id |
| conversation_id |
int |
是 |
INCS 会话id |
| session_type |
int |
是 |
INCS 会话类型：1单聊，2群聊 |
| sender |
string |
是 |
INCS 发信人，若是whatsapp用户则为手机号，若是客服则为客服账号 |
| receiver |
string |
是 |
INCS 收信人，若是whatsapp用户则为手机号，若是客服则为客服账号 |
| type |
int |
是 |
INCS 定义的消息类型，见下述 |
| custom_type |
int |
是 |
INCS 定义的自定义消息类型，type为110时有值 |
| custom_id |
bigint |
是 |
INCS 定义的自定义消息关联id |
| channel_msg_id |
string |
是 |
消息通道回传的id |
| channel_status |
int |
是 |
发出去的消息状态：0 created, 1 sent, 2 failed, 3 delivered, 4 read |
| content |
string |
是 |
信息体json |
| error |
string |
是 |
错误信息 |
| source |
int |
是 |
消息发送方式：0 INCS，1 API |
| created_at |
datetime string |
是 |
消息创建时间，ISO 8601 格式 |
| updated_at |
datetime string |
是 |
消息更新时间，ISO 8601 格式 |
消息类型（type）
| 枚举值 |
描述 |
| 101 |
文本消息 |
| 102 |
图片消息 |
| 103 |
音频消息 |
| 104 |
视频消息 |
| 105 |
文件消息 |
| 110 |
自定义消息 |
自定义消息类型（custom_type）
| 枚举值 |
描述 |
| 11002 |
whatsapp 模板消息 |
| 11006 |
whatsapp 回复按钮 |
| 11008 |
viber otp |
| 11009 |
rcs 模板消息 |
| 11010 |
rcs 建议回复 |
message 内容示例
1.1. 101 文本消息
{
"event": "message_created",
"message": {
"id": 260400000076,
"auth_id": 30058,
"conversation_id": 979,
"session_type": 1,
"sender": "6281519140327",
"receiver": "incs_1",
"type": 101,
"custom_type": 0,
"custom_id": 0,
"channel_msg_id": "wamid.HBgNNjI4MTUxOTE0MDMyNxUCABIYIEFDQTgwMEZCMUFERjZDQzhDNUVDQzM0Qzg2Qjg0QkI0AA==",
"channel_status": 0,
"content": {
"content": "Hi"
},
"error": "",
"source": 0,
"created_at": "2026-04-07T12:02:55.000000Z",
"updated_at": "2026-04-07T12:02:55.000000Z"
}
}
1.2. 102 图片消息
{
"event": "message_created",
"message": {
"id": 260400000079,
"auth_id": 30058,
"conversation_id": 979,
"session_type": 1,
"sender": "incs_1",
"receiver": "6281519140327",
"type": 102,
"custom_type": 0,
"custom_id": 0,
"channel_msg_id": "wamid.HBgNNjI4MTUxOTE0MDMyNxUCABEYEjI2NjgxQjgwMzkyRTQxMzQyMAA=",
"channel_status": 1,
"content": {
"sourcePath": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/images/69d4fca3eede4.png",
"sourcePicture": {
"uuid": "rc-upload-1775565512163-6",
"type": "image/png",
"size": 806876,
"width": 864,
"height": 864,
"url": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/images/69d4fca3eede4.png"
},
"bigPicture": {
"uuid": "rc-upload-1775565512163-6",
"type": "image/png",
"size": 806876,
"width": 864,
"height": 864,
"url": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/images/69d4fca3eede4.png"
},
"snapshotPicture": {
"uuid": "rc-upload-1775565512163-6",
"type": "image/png",
"size": 806876,
"width": 864,
"height": 864,
"url": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/images/69d4fca3eede4.png"
}
},
"error": "",
"source": 0,
"created_at": "2026-04-07T12:46:29.000000Z",
"updated_at": "2026-04-07T12:46:30.000000Z"
}
}
1.3. 103 音频消息
{
"event": "message_created",
"message": {
"id": 260400000081,
"auth_id": 30058,
"conversation_id": 980,
"session_type": 1,
"sender": "6281519140327",
"receiver": "incs_1",
"type": 103,
"custom_type": 0,
"custom_id": 0,
"channel_msg_id": "wamid.HBgNNjI4MTUxOTE0MDMyNxUCABIYIEFDMzM1Nzc3RjRDQjkxODc1MzAzMUZFMDlDQTU1QjM4AA==",
"channel_status": 0,
"content": {
"uuid": "2067977394126791",
"soundPath": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/audios/2067977394126791.ogg",
"sourceUrl": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/audios/2067977394126791.ogg",
"dataSize": 3040,
"duration": 1,
"soundType": "audio/ogg; codecs=opus"
},
"error": "",
"source": 0,
"created_at": "2026-04-07T12:54:11.000000Z",
"updated_at": "2026-04-07T12:54:11.000000Z"
}
}
1.4. 104 视频消息
{
"event": "message_created",
"message": {
"id": 260400000082,
"auth_id": 30058,
"conversation_id": 980,
"session_type": 1,
"sender": "incs_1",
"receiver": "6281519140327",
"type": 104,
"custom_type": 0,
"custom_id": 0,
"channel_msg_id": "wamid.HBgNNjI4MTUxOTE0MDMyNxUCABEYEjJDQUE4NjU5RkQyRThEM0ZGRQA=",
"channel_status": 1,
"content": {
"videoUUID": "rc-upload-1775565512163-13",
"videoUrl": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/videos/69d4fecef09fa.mp4",
"videoType": "video/mp4",
"videoSize": 2828720,
"duration": 39,
"snapshotPath": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/videos/69d4fecef09fa.mp4?x-oss-process=video/snapshot,t_0,f_jpg,ar_auto",
"snapshotUUID": "rc-upload-1775565512163-13",
"snapshotSize": 147949,
"snapshotUrl": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/videos/69d4fecef09fa.mp4?x-oss-process=video/snapshot,t_0,f_jpg,ar_auto",
"snapshotWidth": 392,
"snapshotHeight": 850,
"snapshotType": "image/png"
},
"error": "",
"source": 0,
"created_at": "2026-04-07T12:55:46.000000Z",
"updated_at": "2026-04-07T12:55:47.000000Z"
}
}
1.5. 105 文件消息
{
"event": "message_created",
"message": {
"id": 260400000080,
"auth_id": 30058,
"conversation_id": 979,
"session_type": 1,
"sender": "incs_1",
"receiver": "6281519140327",
"type": 105,
"custom_type": 0,
"custom_id": 0,
"channel_msg_id": "",
"channel_status": 0,
"content": {
"filePath": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/files/69d4fdd3bb80e.xlsx",
"uuid": "rc-upload-1775565512163-8",
"sourceUrl": "https://incs-test.oss-ap-southeast-1.aliyuncs.com/chat/files/69d4fdd3bb80e.xlsx",
"fileName": "Rcs-user.xlsx",
"fileSize": 9095,
"fileType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
},
"error": "",
"source": 0,
"created_at": "2026-04-07T12:51:32.000000Z",
"updated_at": "2026-04-07T12:51:32.000000Z"
}
}
1.6.1 110 自定义消息-whatsapp模板消息
{
"event": "message_created",
"message": {
"id": 260400000085,
"auth_id": 30058,
"conversation_id": 972,
"session_type": 1,
"sender": "incs_1",
"receiver": "6281519140327",
"type": 110,
"custom_type": 11002,
"custom_id": 15775,
"channel_msg_id": "wamid.HBgLODUyNjg0MTUwMjYVAgARGBIzRUMxQzAxQzMwMTNFRkVBN0UA",
"channel_status": 1,
"content": {
"data": {
"id": 15775,
"enterprise_id": 100006,
"auth_id": 30058,
"account_id": "269238056283774",
"template_id": "2773590159650487",
"namespace_id": "",
"name": "11qwer",
"language": "en",
"category": "AUTHENTICATION",
"correct_category": "",
"has_params": 1,
"status": "APPROVED",
"quality": "",
"components": [
{
"type": "BODY",
"text": "*123456* is your verification code. For your security, do not share this code.",
"add_security_recommendation": true,
"example": {
"body_text": [
[
"123456"
]
]
}
},
{
"type": "FOOTER",
"text": "Expires in 5 minutes.",
"code_expiration_minutes": 5
},
{
"type": "BUTTONS",
"buttons": [
{
"type": "URL",
"text": "Copy code",
"url": "https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code_expiration_minutes=5&code=otp{{1}}",
"example": [
"https://www.whatsapp.com/otp/code/?otp_type=COPY_CODE&code_expiration_minutes=5&code=otp123456"
]
}
]
}
],
"error": "",
"created_at": "2026-03-11 16:27:33",
"updated_at": "2026-03-11 16:27:41",
"deleted_at": null,
"status_updated_at": "2026-03-11 16:27:41",
"quality_updated_at": null,
"category_updated_at": null,
"custom_type": 11002,
"raw_params": [
{
"type": "body",
"parameters": [
{
"type": "text",
"text": 123456
}
]
},
{
"type": "button",
"sub_type": "url",
"index": "0",
"parameters": [
{
"type": "text",
"text": 123456
}
]
}
]
}
},
"error": "",
"source": 1,
"created_at": "2026-04-07T13:09:39.000000Z",
"updated_at": "2026-04-07T13:09:40.000000Z"
}
}
1.6.2 110 自定义消息 - whatsapp 回复按钮
{
"event": "message_created",
"message": {
"id": 260400000086,
"auth_id": 30058,
"conversation_id": 981,
"session_type": 1,
"sender": "6281519140327",
"receiver": "incs_1",
"type": 110,
"custom_type": 11006,
"custom_id": 260400000084,
"channel_msg_id": "wamid.HBgNNjI4MTUxOTE0MDMyNxUCABIYIEFDNTRDNTVERTE2M0QxNjhGQjQ4RTE4Q0YyMUE1QjE3AA==",
"channel_status": 0,
"content": {
"data": {
"custom_type": 11006,
"replying_to": "Thank you for subscribing",
"text": "1111"
}
},
"error": "",
"source": 0,
"created_at": "2026-04-07T13:11:29.000000Z",
"updated_at": "2026-04-07T13:11:29.000000Z"
}
}
2. 消息状态更新（message_status_updated）
参数说明
| 参数名 |
类型 |
必传 |
描述 |
| event |
string |
是 |
此处为 "message_status_updated"，发送后触发该回调 |
| message_id |
bigint |
是 |
INCS 消息ID |
| message_status |
int |
是 |
INCS 消息状态：1 sent, 2 failed, 3 delivered, 4 read |
| error |
string |
是 |
当消息状态为2时的错误信息描述 |
| updated_at |
datetime string |
是 |
消息更新时间，ISO 8601 格式 |
回调示例
{
"event": "message_status_updated",
"message_id": 260400000084,
"message_status": 4,
"error": "",
"updated_at": "2026-04-07T13:11:27.000000Z"
}