Skip to content

SMB_zh

Jump to bottom
GiuFLim edited this page Apr 17, 2026 · 16 revisions

SMB

您可以配置嵌入式注册，以允许业务客户使用现有的 WhatsApp Business 应用账户和电话号码接入。选择此选项后成功接入的客户将能够使用您的应用向其客户大规模发送消息，同时仍可通过 WhatsApp Business 应用一对一发送消息，且两个应用之间的消息记录保持同步。

  1. 个人号的历史联系人数据同步 smb_app_state_sync
  2. 个人号与联系人之间的历史聊天记录同步 history
  3. 个人号通过WhatsApp设备发送的消息，消息镜像同步 smb_message_echoes

smb_app_state_sync

描述业务客户的 WhatsApp Business 应用中的一个或多个 WhatsApp 联系人。

触发事件：

  • 解决方案提供方同步某业务客户的 WhatsApp 联系人，该业务客户已通过 WhatsApp Business 应用电话号码完成接入
  • 由解决方案提供方接入、使用 WhatsApp Business 应用电话号码的业务客户添加、编辑或移除 WhatsApp 联系人

响应参数

参数名 类型 说明
field String 事件固定值：smb_app_state_sync
value Object 事件主体
business_phone String 业务客户公司电话号码
messaging_product String 消息产品类型，固定值 whatsapp
metadata Metadata Object 号码元信息
state_sync array[State Sync Object] 联系人同步列表
wabaId String 业务客户的 WhatsApp Business 业务账户编号
  • Metadata Object参数：
参数名 类型 说明
display_phone_number String 展示的商家号码
phone_number_id String 业务电话号码 ID
  • State Sync Object参数：
参数名 类型 说明
type String 同步对象类型，当前为 contact
contact Contact Object 联系人信息
action String 联系人动作：add（新增/编辑），remove（移除）
metadata State Metadata Object 同步事件元信息
  • Contact Object参数：
参数名 类型 说明
full_name String 联系人全名
phone_number String 联系人手机号；匿名化场景可能缺失
user_id String 用户 BSUID
parent_user_id String 用户父 BSUID；未启用父 BSUID 时省略
username String 匿名化场景下的用户账号；非匿名化时可能省略
  • State Metadata Object参数：
参数名 类型 说明
timestamp String Unix 时间戳，表示联系人变更发生时间

webhook

{
    "field": "smb_app_state_sync",
    "value": {
        "business_phone": "xxx",
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "xxx",
            "phone_number_id": "xxx"
        },
        "state_sync": [
            {
                "type": "contact",
                "contact": {
                    "full_name": "xxx",
                    "phone_number": "628786xxx78"
                },
                "action": "add",
                "metadata": {
                    "timestamp": "1756977333478"
                }
            },
            {
                "type": "contact",
                "contact": {
                    "full_name": "xxx",
                    "username": "@testusername",
                    "user_id": "US.13491208655302741918",
                    "parent_user_id": "US.ENT.506847293015824"
                },
                "action": "add",
                "metadata": {
                    "timestamp": "1756977333478"
                }
            },
            {
                "type": "contact",
                "contact": {
                    "full_name": "\u202a+852xxx3859\u202c",
                    "phone_number": "85238xxx859",
                    "user_id": "US.13491208655302741918"
                },
                "action": "add",
                "metadata": {
                    "timestamp": "1756977333478"
                }
            },
            {
                "type": "contact",
                "contact": {
                    "full_name": "\u202a+551xxx65\u202c",
                    "phone_number": "551xxxx2065",
                    "user_id": "US.13491208655302741918",
                    "parent_user_id": "US.ENT.506847293015824"
                },
                "action": "add",
                "metadata": {
                    "timestamp": "1756977333478"
                }
            }
        ],
        "wabaId": "xxx"
    }
}

history

描述已选择与解决方案提供方共享聊天记录的商家的 WhatsApp Business 应用聊天记录，或商家拒绝共享聊天记录的决定。

触发事件

  • 解决方案提供方同步某业务客户的 WhatsApp Business 应用聊天记录，该业务客户已通过 WhatsApp Business 应用电话号码完成接入，且已同意共享其聊天记录
  • 解决方案提供方同步某业务客户的 WhatsApp Business 应用聊天记录，该业务客户已通过 WhatsApp Business 应用电话号码完成接入，但拒绝共享其聊天记录

聊天记录内容

如果在解决方案提供方请求商家聊天记录时，商家已批准共享聊天记录，则会触发一系列历史记录 Webhook，其中描述自商家接入云端 API 后 180 天内发送或接收的所有消息。

  • 群聊中的消息不会包含在内
  • 媒体消息将不包含素材编号；但是，将单独发送包含媒体消息素材编号的其他历史记录 Webhook，但仅限于接入后 14 天内发送的媒体消息

请注意，为提高效率，单个 Webhook 可能描述上千条消息，因此我们建议您先获取其内容，然后异步处理内容。

  • 已共享消息记录 如果商家选择与您共享其消息记录，则会触发一系列历史记录 Webhook，其中描述在指定时间段内向 WhatsApp 用户发送或从 WhatsApp 用户接收的每一条消息。
  • 未共享消息记录 如果商家选择不与您共享其消息记录，系统会触发包含错误代码 2593109 的 history Webhook。案例如下

阶段和块

Webhook 分为三个历史阶段，其中第 0 天表示商家接入云端 API 的时间：

  • 阶段 0：第 0 天到第 1 天
  • 第 1 阶段：第 1 天到第 90 天
  • 第 2 阶段：第 90 天到第 180 天

对于每个阶段，聊天记录 Webhook 可能会拆分成多个独立的块发送，具体取决于对话中消息的总数。

  • 您可以使用 chunk_order 参数值按顺序排列这些块，因为它们可能并非按顺序送达。
  • 您可以使用 phase 参数值来监控阶段进度。值 2 表示当前阶段已完成。
  • 您可以使用 progress 参数值来监控整体进度。值 100 表示同步已完成。

如果某个阶段没有可用的聊天记录，则不会发送相应的 Webhook。

响应参数

参数名 类型 说明
field String 事件固定值：history
value Object 事件主体
business_phone String 业务客户公司电话号码
messaging_product String 消息产品类型，固定值 whatsapp
metadata Metadata Object 号码元信息
history array[History Object] 历史同步块列表
messages array[Message Object] 媒体占位补偿场景下的消息列表
wabaId String 业务客户 WABA ID
  • Metadata Object参数：
参数名 类型 说明
display_phone_number String 展示的商家号码
phone_number_id String 业务电话号码 ID
  • History Object参数：
参数名 类型 说明
metadata History Metadata Object 历史块元数据
threads array[Thread Object] 会话线程列表
errors array[Error Object] 历史同步失败信息（例如商家拒绝共享历史）
  • History Metadata Object参数：
参数名 类型 说明
phase Integer 同步阶段：0（第0-1天）、1（第1-90天）、2（第90-180天）
chunk_order Integer 阶段内分块顺序号
progress Integer 总体同步进度百分比（0-100）
  • Thread Object参数：
参数名 类型 说明
id String 联系人手机号；匿名化场景可能缺失
messages array[Message Object] 该对话下的消息列表
context array[Context Object] 上下文对象
  • Thread Message Object参数：
参数名 类型 说明
id String WhatsApp 消息 ID
timestamp String Unix 时间戳
type String 消息类型
1. text 文本
2. image 图片
3. video 视频
4. voice 语音
5. audio 音频
6. document 文件
7. location 位置
8. sticker 贴图表情
9. interactive 互动消息
10.context 引用消息
11.reaction 心情消息
12. button 按钮
from String 发送方号码；匿名化场景可能缺失
text/image/interactive/errors Object/array 与 type 对应的消息体
history_context History Context Object 历史上下文信息（方向与状态）
context Context Object 引用消息上下文（存在时返回）
from_user_id String 发送方 BSUID
from_parent_user_id String 发送方父 BSUID
  • Thread Context Object 参数:
参数名 类型 说明
wa_id String 联系人手机号；匿名化场景可能缺失
user_id String 用户 BSUID
parent_user_id String 用户父 BSUID
username String 匿名化账号
  • History Context Object参数：
参数名 类型 说明
status String 消息状态：DELIVERED、ERROR、PENDING、PLAYED、READ、SENT
from_me boolean 是否由商家侧发送
  • Error Object参数：
参数名 类型 说明
code Integer 错误码
title String 错误标题
message String 错误信息
error_data Object 错误扩展信息（details）
  • 消息类型
  1. 文本消息参数：
参数名 类型 说明
text Object 参照响应示例 文本消息内容，type=text时有值
  • text object参数：
参数名 类型 说明
body String 消息文本
  1. 图片消息参数：
参数名 类型 说明
image JsonObject 参照响应示例 图片消息内容，type=image时有值
  • image object参数：
参数名 类型 说明
id String 媒体存储的id，可用于获取媒体链接，Webhook 中的影音内容编号会在 7 天后过期。
caption String 图片的描述
mime_type String 媒体文件的MiME类型
sha256 String 媒体文件的校验签名
  1. 视频消息参数：
参数名 类型 说明
video JsonObject 参照响应示例 视频消息内容，type=video时有值
  • video object参数：
参数名 类型 说明
id String 媒体存储的id，可用于获取媒体链接，Webhook 中的影音内容编号会在 7 天后过期。
caption String 视频的描述
mime_type String 媒体文件的MiME类型
sha256 String 媒体文件的校验签名
  1. 语音消息参数：
参数名 类型 说明
voice JsonObject 参照响应示例 语音消息内容，type=voice时有值
  • voice object参数：
参数名 类型 说明
id String 媒体存储的id，可用于获取媒体链接，Webhook 中的影音内容编号会在 7 天后过期。
mime_type String 媒体文件的MiME类型
sha256 String 媒体文件的校验签名
  1. 音频消息参数：
参数名 类型 说明
audio JsonObject 参照响应示例 音频消息内容，type=audio时有值
  • audio object参数：
参数名 类型 说明
id String 媒体存储的id，可用于获取媒体链接，Webhook 中的影音内容编号会在 7 天后过期。
mime_type String 媒体文件的MiME类型
sha256 String 媒体文件的校验签名
link String 媒体文件的url,有效期48小时
  1. 文档消息参数：
参数名 类型 说明
document JsonObject 参照响应示例 文档消息内容，type=document时有值
  • document object参数：
参数名 类型 说明
id String 媒体存储的id，可用于获取媒体链接，Webhook 中的影音内容编号会在 7 天后过期。
mime_type String 媒体文件的MiME类型
sha256 String 媒体文件的校验签名
filename String 文档文件名称
  1. 位置消息参数：
参数名 类型 说明
location JsonObject 参照响应示例 位置消息内容，type=location时有值
  • location object参数：
参数名 类型 说明
longitude String 位置的经度信息
latitude String 位置的维度信息
name String 位置的名称
address String 位置的详细地址信息
  1. 贴图表情消息参数：
参数名 类型 说明
sticker JsonObject 参照响应示例 贴图表情消息内容，type=sticker时有值
  • sticker object参数：
参数名 类型 说明
id String 媒体存储的id，可用于获取媒体链接
link String 媒体文件的url,有效期48小时
  1. 互动消息参数：
参数名 类型 说明
interactive Object 参照响应示例1
参照响应示例2
type=interactive时有值
  • interactive object参数：
参数名 类型 说明
type String button_reply (按钮回复)
list_reply（列表回复）
nfm_reply（表单提交）
button_reply Object 当用户点击按钮时发送，具有该属性的对象。
list_reply Object 当用户从列表中选择一个项目时发送，具有该属性的对象。
nfm_reply Object 当用户表单提交，具有该属性的对象。
call_permission_reply Object 当用户点击通话权限申请反馈，具有该属性的对象。
  • button_reply 或者 list_reply object参数：
参数名 类型 说明
id String 按钮id
title String 标题
description String 选项描述，list_reply才有
  • nfm_reply object参数：
参数名 类型 说明
name String 固定为 flow
body String 消息提交后的文案
response_json String flow的json数据. The structure is either defined in flow JSON ([see Complete action]
  • call_permission_reply object参数：
参数名 类型 说明
expiration_timestamp Long 通话权限过期时间戳
response String accept/reject 接受/拒绝
response_source String user_action/automatic 用户反馈/系统反馈
  1. 引用消息参数：
参数名 类型 说明
context Object 商品消息响应示例
引用消息响应示例
仅在用户回复或与您的消息之一互动时存在
  • context object参数：
参数名 类型 说明
from String 被引用消息来源号码
id String 消息id
meta_message_id String meta消息id(不一定存在)
forwarded Boolean 如果商家收到的该消息已被转发，则设置为true
frequently_forwarded Boolean 如果商家收到的该消息已被转发超过5次，则设置为true。
referred_product Object 引用回复商品消息时含有该对象
  • referred_product object参数：
参数名 类型 说明
catalog_id String 目录id
product_retailer_id String 目录中产品的唯一标识符
  1. reaction消息参数：
参数名 类型 必选 示例值 说明
reaction Object 否 参照请求示例 心情消息内容，type=reaction必填
  • reaction object参数：
参数名 类型 必选 示例值 说明
meta_message_id String 是 - meta消息id
message_id String 是 - 消息回复id,例如:wamid.HBgNODYxMzE2MzczMTQ2NxUCABIYEkVCQkE4NjdGRUE5RDgyQzg0RAA=
emoji String 是 - 表情 例如:"❤️"
  1. button object 参数:
参数名 类型 说明
text String 按钮预设文本
payload String 不可见特殊字符串

webhook

{
    "field": "history",
    "value": {
        "business_phone": "xxx",
        "history": [
            {
                "metadata": {
                    "phase": 0,
                    "chunk_order": 1,
                    "progress": 100
                },
                "threads": [
                    {
                        "id": "447xxx736",
                        "messages": [
                            {
                                "from": "447xxx736",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgMNDQ3NzEwMTczNzM2FQIAEhgSRDExQTYyMjc0RjVDNTlBOENBAA==",
                                "timestamp": "1756977261",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "pending"
                                }
                            },
                            {
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgMNDQ3NzEwMTczNzM2FQIAEhgSMDMyNTU5RTlGQjY5NEIxQUI2AA==",
                                "timestamp": "1756956364",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "pending"
                                }
                            },
                            {
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgMNDQ3NzEwMTczNzM2FQIAEhgSQTE4QTg0MTU2MkQ1QzlDQThEAA==",
                                "timestamp": "1756889400",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "pending"
                                }
                            },
                            {
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgMNDQ3NzEwMTczNzM2FQIAEhgSNDY2MUE2RjdGQTYzMTAyMDI4AA==",
                                "timestamp": "1756709184",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "pending"
                                }
                            },
                            {
                                "from": "447xxx736",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgMNDQ3NzEwMTczNzM2FQIAEhgSRjk1QkJFREU4OURBMzlFMEFBAA==",
                                "timestamp": "1756709077",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "pending"
                                }
                            },
                            {
                                "from": "447xxx736",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgMNDQ3NzEwMTczNzM2FQIAEhgSNTQyMzRDNUZCMTNFNkQyM0Q1AA==",
                                "timestamp": "1754298556",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "pending"
                                }
                            },
                            {
                                "from": "447xxx736",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgMNDQ3NzEwMTczNzM2FQIAEhgSMjczNzMyM0ZEOUVFQkZDREE4AA==",
                                "timestamp": "1754298423",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "pending"
                                }
                            }
                        ]
                    },
                    {
                        "messages": [
                            {
                                "from": "86133xxx446",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDNBNkIwNDdFRDNCRTNGODQyM0JDAA==",
                                "timestamp": "1756958075",
                                "text": {
                                    "body": "364"
                                },
                                "type": "text",
                                "history_context": {
                                    "status": "pending"
                                }
                            },
                            {
                                "from": "551xxx066",
                                "from_user_id": "US.13491208655302741918",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABEYEjlDQkQyMDgyNDRDM0VDQ0RGMgA=",
                                "timestamp": "1756718044",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "read",
                                    "from_me": true
                                }
                            },
                            {
                                "from": "551xxx066",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABEYFjNFQjBBMEMwMDc3MDY2MTE3OTZBM0EA",
                                "timestamp": "1756717440",
                                "text": {
                                    "body": "1234567890"
                                },
                                "type": "text",
                                "history_context": {
                                    "status": "read",
                                    "from_me": true
                                }
                            },
                            {
                                "from": "8613xxx446",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDNBRTM4NDU0RDZFNDVERENFM0Y4AA==",
                                "timestamp": "1756717325",
                                "text": {
                                    "body": "3q"
                                },
                                "type": "text",
                                "history_context": {
                                    "status": "pending"
                                }
                            },
                            {
                                "from": "5512xxx66",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABEYFDNBOUMyQURGMDk3Q0I1RTBFNzBDAA==",
                                "timestamp": "1756716515",
                                "text": {
                                    "body": "Hello hi"
                                },
                                "type": "text",
                                "history_context": {
                                    "status": "read",
                                    "from_me": true
                                }
                            },
                            {
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABIYFDNBMThEOUZEQjFBOTkwMUE3MzhDAA==",
                                "timestamp": "1756714179",
                                "text": {
                                    "body": "Happy beginning"
                                },
                                "type": "text",
                                "history_context": {
                                    "status": "pending"
                                }
                            },
                            {
                                "from": "5512xxx066",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABEYEjI1NUNFQTRBNkIwMkE4QkY3RQA=",
                                "timestamp": "1756710767",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "read",
                                    "from_me": true
                                }
                            },
                            {
                                "from": "5512xxx066",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABEYFDNBQjAwNzI3QkVCOTFEOTUyMTVDAA==",
                                "timestamp": "1756709332",
                                "text": {
                                    "body": "苍龙"
                                },
                                "type": "text",
                                "history_context": {
                                    "status": "read",
                                    "from_me": true
                                }
                            },
                            {
                                "from": "5512xxx066",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABEYFDNBREI5MjY5RTgwNkQ1QTI2RThFAA==",
                                "timestamp": "1752719536",
                                "text": {
                                    "body": "123456789"
                                },
                                "type": "text",
                                "history_context": {
                                    "status": "delivered",
                                    "from_me": true
                                }
                            }
                        ]
                    },
                    {
                        "id": "628xxx678",
                        "messages": [
                            {
                                "from": "5512xxx066",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABEYIEI2RDgyNUVENTcxMTExMjUyRUJDOUQ1NURFNjgzRjgxAA==",
                                "timestamp": "1755764541",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "pending",
                                    "from_me": true
                                }
                            }
                        ]
                    },
                    {
                        "id": "5512xxx065",
                        "messages": [
                            {
                                "from": "5512xxx066",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABEYFDNBRTMxMTdBOTRFQTFERkEwNTE0AA==",
                                "timestamp": "1752853979",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "delivered",
                                    "from_me": true
                                }
                            }
                        ]
                    },
                    {
                        "id": "852xxx859",
                        "messages": [
                            {
                                "from": "852xxx859",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgLODUyMzg1MzM4NTkVAgASGBIxNjQ4MUZFODZEMzhEMTcwRDkA",
                                "timestamp": "1752719539",
                                "text": {
                                    "body": "simon123"
                                },
                                "type": "text",
                                "history_context": {
                                    "status": "pending"
                                }
                            }
                        ]
                    }
                ]
            }
        ],
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "xxx",
            "phone_number_id": "xxx"
        },
        "wabaId": "xxx"
    }
}
{
    "field": "history",
    "value": {
        "business_phone": "xxx",
        "history": [
            {
                "metadata": {
                    "phase": 1,
                    "chunk_order": 1,
                    "progress": 100
                },
                "threads": [
                    {
                        "id": "6287xxx678",
                        "messages": [
                            {
                                "from": "5512xxx066",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABEYIEJDM0RGMzQyMUU1NkE4Q0FEMEExNEU5OTU3NEIzRURCAA==",
                                "timestamp": "1755764476",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "pending",
                                    "from_me": true
                                }
                            },
                            {
                                "from": "5512xxx066",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABEYIDNCQUQ4RDZFNzFCM0JGRTk2NEQ2NDgyQkNGN0MwRkIwAA==",
                                "timestamp": "1755754947",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "pending",
                                    "from_me": true
                                }
                            },
                            {
                                "context": {
                                    "from": "6287xxx678",
                                    "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABIYEjBCMEExMjExMDY1MzQ3NkM0MgA="
                                },
                                "from": "5512xxx066",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABEYFDNBNDAyRjg2MzE0ODQ0QTY5MDA5AA==",
                                "timestamp": "1755748593",
                                "type": "interactive",
                                "interactive": {
                                    "type": "call_permission_reply",
                                    "call_permission_reply": {
                                        "response": "accept",
                                        "expiration_timestamp": 1756353390,
                                        "response_source": "user_action"
                                    }
                                },
                                "history_context": {
                                    "status": "delivered",
                                    "from_me": true
                                }
                            },
                            {
                                "from": "6287xxx678",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNNjI4Nzg2ODU3MjY3OBUCABIYEjBCMEExMjExMDY1MzQ3NkM0MgA=",
                                "timestamp": "1755748586",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "pending"
                                }
                            },
                            {
                                "from": "5512xxx066",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABEYFDNBQkU4NERGN0EwQTBERTVEQzc5AA==",
                                "timestamp": "1755748580",
                                "text": {
                                    "body": "1"
                                },
                                "type": "text",
                                "history_context": {
                                    "status": "delivered",
                                    "from_me": true
                                }
                            }
                        ]
                    },
                    {
                        "id": "5512xxx065",
                        "messages": [
                            {
                                "from": "5512xxx065",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NRUCABIYEjM2MTkzQ0MzRDMwMUI1NTJCNAA=",
                                "timestamp": "1752830864",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "pending"
                                }
                            },
                            {
                                "from": "551xxx066",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABEYFDNBQjk2RjdGNkVEMzBGMjZGRDcyAA==",
                                "timestamp": "1752809278",
                                "text": {
                                    "body": "Hello"
                                },
                                "type": "text",
                                "history_context": {
                                    "status": "delivered",
                                    "from_me": true
                                }
                            }
                        ]
                    },
                    {
                        "id": "852xxx59",
                        "messages": [
                            {
                                "from": "8523xxx59",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgLODUyMzg1MzM4NTkVAgASGBJBMEU5NDlBQkE1NTJENjZGRDQA",
                                "timestamp": "1752719505",
                                "errors": [
                                    {
                                        "code": 131051,
                                        "title": "Message type unknown",
                                        "message": "Message type unknown",
                                        "error_data": {
                                            "details": "Unsupported message received"
                                        }
                                    }
                                ],
                                "type": "errors",
                                "history_context": {
                                    "status": "pending"
                                }
                            },
                            {
                                "from": "551xxx066",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgNNTUxMjkyMDAyMjA2NhUCABEYFDNBNTVEQ0RBOTMwNDI5REYyRDIyAA==",
                                "timestamp": "1752719502",
                                "text": {
                                    "body": "123456"
                                },
                                "type": "text",
                                "history_context": {
                                    "status": "delivered",
                                    "from_me": true
                                }
                            }
                        ]
                    }
                ]
            }
        ],
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "xxx",
            "phone_number_id": "xxx"
        },
        "wabaId": "xxx"
    }
}
{
    "field": "history",
    "value": {
        "business_phone": "xxx",
        "history": [
            {
                "metadata": {
                    "phase": 2,
                    "chunk_order": 1,
                    "progress": 100
                }
            }
        ],
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "xxx",
            "phone_number_id": "xxx"
        },
        "wabaId": "xxx"
    }
}

以下 Webhook 示例描述了两个消息对话：(1) 一个包含发送给 WhatsApp 用户的文本消息和视频消息以及 WhatsApp 用户回复的对话；(2) 一个包含发送给另一个 WhatsApp 用户的文本消息（感谢该用户下单）的对话。 请注意，第一条对话中的媒体消息内容未加以描述，而是触发第二个 Webhook，描述该媒体消息的内容。

{
    "field": "history",
    "value": {
        "business_phone": "15557522905",
        "history": [
            {
                "metadata": {
                    "phase": 0,
                    "chunk_order": 1,
                    "progress": 55
                },
                "threads": [
                    {
                        "id": "16505551234",
                        "messages": [
                            {
                                "from": "xxx",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA",
                                "timestamp": "1739230955",
                                "type": "text",
                                "text": {
                                    "body": "Here's the info you requested!"
                                },
                                "history_context": {
                                    "status": "READ"
                                }
                            },
                            {
                                "from": "xxx",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.QyNUEHBgLMTY0NjcwNDM1OTUVAgARGBI1Rj3NEYxMzAzMzQ5MkEA",
                                "timestamp": "1739230970",
                                "type": "media_placeholder",
                                "history_context": {
                                    "status": "PLAYED"
                                }
                            },
                            {
                                "from": "xxx",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.N0FCNjMAHBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0",
                                "timestamp": "1739230970",
                                "type": "text",
                                "text": {
                                    "body": "Thanks!"
                                },
                                "history_context": {
                                    "status": "READ"
                                }
                            }
                        ]
                    },
                    {
                        "id": "12125557890",
                        "messages": [
                            {
                                "from": "xxx",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.BIyNDlBOEI5N0FCNjMAHBgLMTY0NjcwNDM1OTUVAgARGQUQ4NDc0",
                                "timestamp": "1739230970",
                                "type": "text",
                                "text": {
                                    "body": "Thanks for your order! As a thank you, use code THANKS30 to get 30% of your next order."
                                },
                                "history_context": {
                                    "status": "DELIVERED"
                                }
                            }
                        ]
                    }
                ]
            }
        ],
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "xxx",
            "phone_number_id": "xxx"
        },
        "wabaId": "xxx"
    }
}

用于区分消息方向：

字段 方向 说明
messages[] 入站（用户 → 商家） 用户发送给商家的消息
message_echoes[] 出站（商家 → 用户） 商家通过 WA Business App 发送的消息

以下 Webhook 示例描述了messages[]和message_echoes[] 共存情况 。

{
    "field": "history",
    "value": {
        "business_phone": "15557522905",
        "history": [
            {
                "metadata": {
                    "phase": 0,
                    "chunk_order": 1,
                    "progress": 55
                },
                "threads": [
                    {
                        "id": "16505551234",
                        "messages": [
                            {
                                "from": "xxx",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.HBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0N0FCNjMA",
                                "timestamp": "1739230955",
                                "type": "text",
                                "text": {
                                    "body": "Here's the info you requested!"
                                },
                                "history_context": {
                                    "status": "READ"
                                }
                            },
                            {
                                "from": "xxx",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.QyNUEHBgLMTY0NjcwNDM1OTUVAgARGBI1Rj3NEYxMzAzMzQ5MkEA",
                                "timestamp": "1739230970",
                                "type": "media_placeholder",
                                "history_context": {
                                    "status": "PLAYED"
                                }
                            },
                            {
                                "from": "xxx",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.N0FCNjMAHBgLMTY0NjcwNDM1OTUVAgARGBIyNDlBOEI5QUQ4NDc0",
                                "timestamp": "1739230970",
                                "type": "text",
                                "text": {
                                    "body": "Thanks!"
                                },
                                "history_context": {
                                    "status": "READ"
                                }
                            }
                        ],
                        "message_echoes": [
                            {
                                "from": "xxx",
                                "to": "xxx",
                                "id": "wamid.HBgNODYxODk1NTQxMDc4NBUCABEYIEE1NzE3NTA2QTc1NTlFMTBCQUFDNDU3NThFRUU3QzQ5AA==",
                                "timestamp": "1775134736",
                                "type": "text",
                                "text": {
                                    "body": "Here's the info you requested!"
                                }
                            }
                        ]
                    },
                    {
                        "id": "12125557890",
                        "messages": [
                            {
                                "from": "xxx",
                                "from_user_id": "US.13491208655302741918",
                                "from_parent_user_id": "US.ENT.506847293015824",
                                "id": "wamid.BIyNDlBOEI5N0FCNjMAHBgLMTY0NjcwNDM1OTUVAgARGQUQ4NDc0",
                                "timestamp": "1739230970",
                                "type": "text",
                                "text": {
                                    "body": "Thanks for your order! As a thank you, use code THANKS30 to get 30% of your next order."
                                },
                                "history_context": {
                                    "status": "DELIVERED"
                                }
                            }
                        ]
                    }
                ]
            }
        ],
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "xxx",
            "phone_number_id": "xxx"
        },
        "wabaId": "xxx"
    }
}

以下 Webhook 示例描述了媒体消息的内容(用户发送给商家)。

{
    "field": "history",
    "value": {
        "business_phone": "xxx",
        "messages": [
            {
                "from": "xxx",
                "from_user_id": "US.13491208655302741918",
                "from_parent_user_id": "US.ENT.506847293015824",
                "id": "wamid.QyNUEHBgLMTY0NjcwNDM1OTUVAgARGBI1Rj3NEYxMzAzMzQ5MkEA",
                "image": {
                    "caption": "Black Prince echeveria",
                    "id": "24230790383178626",
                    "mime_type": "image/jpeg",
                    "sha256": "3f9d94d399fa61c191bc1d4ca71375a035cd9b9f5b1128e1f0963a415c16b0cc"
                },
                "timestamp": "1738796547",
                "type": "image"
            }
        ],
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "xxx",
            "phone_number_id": "xxx"
        },
        "wabaId": "xxx"
    }
}

以下 Webhook 示例描述了媒体消息的内容(商家发送给用户)。

{
    "field": "history",
    "value": {
        "business_phone": "xxx",
        "message_echoes": [
            {
                "from": "xxx",
                "to": "xxx",
                "id": "wamid.HBgNODYxODk1NTQxMDc4NBUCABEYIEE1NzE3NTA2QTc1NTlFMTBCQUFDNDU3NThFRUU3QzQ5AA==",
                "timestamp": "1775134736",
                "type": "image",
                "image": {
                    "mime_type": "image/jpeg",
                    "sha256": "KGwn+TefxWcXlTzpvwAFZSKs0SBnUVabAhSw5H9Z4ao=",
                    "id": "1432671975257295"
                }
            }
        ],
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "xxx",
            "phone_number_id": "xxx"
        },
        "wabaId": "xxx"
    }
}

聊天记录共享已被拒绝

{
    "field": "history",
    "value": {
        "business_phone": "xxx",
        "history": [
            {
                "errors": [
                    {
                        "code": 2593109,
                        "title": "History sync is turned off by the business from the WhatsApp Business App",
                        "message": "History sync is turned off by the business from the WhatsApp Business App",
                        "error_data": {
                            "details": "History sharing is turned off by the business."
                        }
                    }
                ]
            }
        ],
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "xxx",
            "phone_number_id": "xxx"
        },
        "wabaId": "xxx"
    }
}

smb_message_echoes

描述业务客户通过 WhatsApp Business 应用或支持的配套设备向 WhatsApp 用户发送的消息。

触发事件

  • 业务客户使用 WhatsApp Business 应用或支持的配套设备向 WhatsApp 用户发送消息。

响应参数

参数名 类型 说明
field String 事件固定值：smb_message_echoes
value Object 事件主体
business_phone String 业务客户公司电话号码
messaging_product String 消息产品类型，固定值 whatsapp
metadata Metadata Object 号码元信息
message_echoes array[Message Echo Object] 商家设备侧消息镜像列表
contacts array[Contact Object] 联系人数据
wabaId String 业务客户 WABA ID
  • Metadata Object参数：
参数名 类型 说明
display_phone_number String 展示的商家号码
phone_number_id String 业务电话号码 ID
  • Message Echo Object参数：
参数名 类型 说明
from String 商家发送方号码
to String 接收方号码；匿名化场景可能缺失
to_user_id String 用户 BSUID
to_parent_user_id String 用户父 BSUID
id String WhatsApp 消息 ID
timestamp String Unix 时间戳
type String 消息类型，如 text、interactive、image , revoke,edit 等
text/image/interactive Object 与 type 对应的消息体
  • Contact object参数：
参数名 类型 说明
profile Object 配置文件对象
wa_id String 接收方号码；匿名化场景可能缺失
user_id String 用户 BSUID
parent_user_id String 用户父 BSUID
  • profile object参数：
参数名 类型 说明
name String 值将设为 WhatsApp 用户的显示名。
username String 如果用户已启用匿名化功能，将设置为 WhatsApp 用户的匿名账户。 
{
  "field": "smb_message_echoes",
  "value": {
    "business_phone": "xxx",
    "message_echoes": [
      {
        "from": "xxx",
        "to": "8613xxx446",
        "to_user_id": "uUS.13491208655302741918",
        "to_parent_user_id": "US.11815799212886844830",
        "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYFDNBQ0Q5Qjg3OUZBQkZERTQ4NDIxAA==",
        "timestamp": "1756977414",
        "text": {
          "body": "Testing test"
        },
        "type": "text"
      }
    ],
    "contacts": [
      {
        "profile": {
          "name": "Jay",
          "username": "@realsheenanelson"
        },
        "wa_id": "852xxxx705",
        "user_id": "uUS.13491208655302741918",
        "parent_user_id": "US.11815799212886844830"
      }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
      "display_phone_number": "xxx",
      "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
  }
}

商户号删除消息

{
  "field": "smb_message_echoes",
  "value": {
    "business_phone": "xxx",
    "contacts": [
      {
        "user_id": "CN.1163458429160977",
        "wa_id": "xxx"
      }
    ],
    "message_echoes": [
      {
        "from": "xxx",
        "to": "xxx",
        "id": "wamid.HBgNODYxNTgwNjA0NjI1NBUCABEYFDJBMTM5ODk5MzhDMTA4NzNCMDlBAA==",
        "timestamp": "1776306632",
        "type": "revoke",
        "revoke": {
          "original_message_id": "wamid.HBgNODYxNTgwNjA0NjI1NBUCABEYFDJBQUMyRERCQzcxNDg5QzYzQzhGAA=="
        }
      }
    ],
    "messaging_product": "whatsapp",
    "metadata": {
      "display_phone_number": "xxx",
      "phone_number_id": "xxx"
    },
    "wabaId": "xxx"
  }
}

商户号重新编辑后的消息

{
    "field": "smb_message_echoes",
    "value": {
        "business_phone": "xxx",
        "contacts": [
            {
                "user_id": "CN.1163458429160977",
                "wa_id": "xxx"
            }
        ],
        "message_echoes": [
            {
                "from": "xxx",
                "to": "xxx",
                "id": "wamid.HBgNODYxNTgwNjA0NjI1NBUCABEYFDJBQjMyN0JBNTVCRTI5QUU1NURBAA==",
                "timestamp": "1776307126",
                "type": "edit",
                "edit": {
                    "original_message_id": "wamid.HBgNODYxNTgwNjA0NjI1NBUCABEYFDJBODQzOEREMjI5MDk1RjFGRThFAA==",
                    "message": {
                        "type": "text",
                        "text": {
                            "body": "Happy beginning"
                        }
                    }
                }
            }
        ],
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "xxx",
            "phone_number_id": "xxx"
        },
        "wabaId": "xxx"
    }
}

商户号发送的原消息(编辑后的消息如上)

{
    "field": "smb_message_echoes",
    "value": {
        "business_phone": "xxx",
        "contacts": [
            {
                "user_id": "CN.1163458429160977",
                "wa_id": "xxx"
            }
        ],
        "message_echoes": [
            {
                "from": "xxx",
                "to": "xxx",
                "id": "wamid.HBgNODYxNTgwNjA0NjI1NBUCABEYFDJBODQzOEREMjI5MDk1RjFGRThFAA==",
                "timestamp": "1776307114",
                "text": {
                    "body": "Happy"
                },
                "type": "text"
            }
        ],
        "messaging_product": "whatsapp",
        "metadata": {
            "display_phone_number": "xxx",
            "phone_number_id": "xxx"
        },
        "wabaId": "xxx"
    }
}

商户号app消息>>用户 送达回执delivered 结构含义请参数状态回执webhook

{
    "app_id": "6761",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "statuses": [
        {
            "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYFDNBQ0Q5Qjg3OUZBQkZERTQ4NDIxAA==",
            "meta_message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYFDNBQ0Q5Qjg3OUZBQkZERTQ4NDIxAA==",
            "recipient_id": "8613xxx446",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "delivered",
            "timestamp": "1756977415"
        }
    ],
    "wabaId": "xxx"
}

商户号app消息>>用户 已读回执read 结构含义请参数状态回执webhook

{
    "app_id": "6761",
    "business_phone": "xxx",
    "channel": 2,
    "merchant_phone": "xxx",
    "messaging_product": "whatsapp",
    "metadata": {
        "display_phone_number": "xxx",
        "phone_number_id": "xxx"
    },
    "statuses": [
        {
            "id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYFDNBQ0Q5Qjg3OUZBQkZERTQ4NDIxAA==",
            "meta_message_id": "wamid.HBgNODYxMzMyMDIzNzQ0NhUCABEYFDNBQ0Q5Qjg3OUZBQkZERTQ4NDIxAA==",
            "recipient_id": "861xxx446",
            "recipient_user_id": "US.13491208655302741918",
            "parent_recipient_user_id": "US.ENT.506847293015824",
            "status": "read",
            "timestamp": "1756978757"
        }
    ],
    "wabaId": "xxx"
}

附加说明：错误码 131051

如果在历史同步过程中遇到错误码 131051，这是预期行为，表示历史同步 payload 中存在不支持的消息类型。

建议：

  • 对该错误进行容错处理（记录日志并跳过），而不是作为失败处理。

总结建议

  • 基于 wamid 去重：在所有 webhook payload 中使用 wamid 作为唯一标识。
  • 不要依赖 webhook 顺序：使用时间戳排序。
  • 媒体匹配：通过 wamid 关联媒体与消息。
  • 联系人幂等处理：使用手机号去重。
  • 处理 131051 错误：记录并跳过不支持的消息类型。

问题和解答

1. history webhook 中 messages[] 和 message_echoes[] 是否可能同时出现

答案：可以同时出现。

两者的区别基于消息方向（direction），而不是是否为多媒体内容。

定义：

  • messages[]：入站消息（消费者 → 商家）
  • message_echoes[]：出站消息（商家 → 消费者，通过 WhatsApp Business App 发送）

关键点：

  • 无论是多媒体还是非多媒体，任意 history webhook payload 中都可能同时包含这两个字段。
  • 如果会话中既有入站消息也有出站消息，同一个 history chunk 中可能同时包含 messages[] 和 message_echoes[]。
  • 多媒体消息在这两个字段中都会以 media_placeholder 的形式出现，真实媒体内容会通过独立的 media webhook 发送。

建议：

  • 在解析 history webhook 时，同时处理 messages[] 和 message_echoes[]。
  • 通过字段名称判断消息方向。
  • 使用 wamid 将 media_placeholder 与后续媒体 webhook 进行关联。

2. smb_message_echoes、history、smb_app_state_sync 的推送顺序

没有保证的推送顺序。

关键点：

  • smb_message_echoes、history、smb_app_state_sync 三类 webhook 是独立处理和投递的。

  • 不同 webhook 类型之间的到达顺序是非确定性的。

  • 在 history webhook 内部，可以通过以下字段还原顺序：

    • phase（阶段）
    • chunk_order（分片顺序）

建议：

  • 使用 timestamp 和 wamid 进行全局时间排序。
  • 在 history 内部使用 phase + chunk_order 重建顺序。

Sequence Diagram

image

简介

短信

语音

云呼叫中心（NXLink）

云呼叫中心（AI自动外呼）

Flash Call

短链

邮件验证码

DID号码

通用

号码检测

WhatsApp

Viber

Zalo ZNS

Super Message API

隐私号(旧)

PNS

坐席（旧版）

NXLINK(HKG)

NXLINK(IDN)

NXLINK(CHL)

AI Agent

RCS

Clone this wiki locally