调用 SendChatappMessage 返回 Code=OK,表示发送请求成功。手机是否收到消息,需要继续用返回的 MessageId 核对状态报告。
本文以模拟订单 ALI-BSP-4086 的发货通知为例,排查三类问题:请求成功却没有送达证据、收到了回执却关联不到订单、客户回复没有进入客服工作台。示例基于阿里云文档,未执行真实账号联调。
一、先确认发送的是哪个实例、号码和模板
在已有可用业务号码和已审核模板的前提下,核对以下参数:
| 参数 | 填写内容 | 常见错误 |
|---|---|---|
CustSpaceId |
按项目资源形态填写空间或直客实例标识 | 填成 Meta 的 WABA ID |
From |
已注册并绑定 WhatsApp 的业务电话号码 | 填成 Meta 的 Phone Number ID |
TemplateCode |
Chat App 中实际可用的模板编码 | 直接使用模板显示名称 |
Language |
与该模板对应的语言 | 使用尚未通过审核的语言版本 |
TemplateParams |
与模板变量定义对应的键值 | 沿用其他模板的变量名 |
当前接口文档将 CustWabaId 标记为过时,相关场景改用 CustSpaceId。CustSpaceId 的适用条件按账号资源形态核对,不将它作为所有调用场景的通用必填项。
假设已审核的发货模板定义了 order_id 变量,发送参数示例如下:
{
"ChannelType": "whatsapp",
"Type": "template",
"CustSpaceId": "<YOUR_CHATAPP_SPACE_ID>",
"From": "<REGISTERED_BUSINESS_NUMBER>",
"To": "<TEST_RECIPIENT>",
"TemplateCode": "<APPROVED_TEMPLATE_CODE>",
"Language": "<MATCHING_TEMPLATE_LANGUAGE>",
"TemplateParams": {
"order_id": "ALI-BSP-4086"
},
"TaskId": "ALI-BSP-4086"
}
这是供 SDK 或 OpenAPI 调试工具使用的参数集合,不是未经签名即可直接发送的 HTTP 请求体。order_id 是本例模板的变量名,实际项目按已审核模板填写。
参数定义见 SendChatappMessage 接口文档。
二、把 MessageId 保存到每一次发送记录
发送接口的精简返回示例:
{
"Code": "OK",
"RequestId": "<RETURNED_REQUEST_ID>",
"MessageId": "<RETURNED_MESSAGE_ID>"
}
三个字段分别用于判断请求结果、追踪接口调用和关联消息。订单系统至少保留一条这样的记录:
订单号:ALI-BSP-4086
本地发送记录:attempt-01
实例:实际 CustSpaceId
发送号码:实际 From
模板及语言:实际 TemplateCode、Language
业务任务:本次 TaskId
消息标识:返回的 MessageId
请求追踪:返回的 RequestId
调用时间:本次发送时间
一条通知对应一次发送记录;同一订单多次发信,分别保存返回的 MessageId。 订单号不是消息 ID,RequestId 也不用于匹配消息状态。
网络超时、没有及时收到回执与明确发送失败分别记录。未确认前直接重发,可能产生第二条通知;后续排查时要保留两次调用各自的结果。
三、没有回执时,先检查订阅类型和 HTTP 响应
Chat App 将客户来信与企业发信状态分成两类消息:
| 类型 | 说明 | 排查用途 |
|---|---|---|
ChatAppInbound |
客户发给企业的消息 | 检查客户回复和工作台来信 |
ChatAppStatus |
企业发出消息的状态报告 | 检查发货通知是否发送、送达或失败 |
发送通知后等待的是 ChatAppStatus。只配了客户来信的接收地址,不等于已配置发信状态报告。配置入口与接收模式见回执消息配置文档。
以下说明 HTTP 接收模式。单次推送是数组,可能包含多条记录。精简模拟事件如下:
[
{
"MessageId": "<RETURNED_MESSAGE_ID>",
"TaskId": "ALI-BSP-4086",
"From": "<REGISTERED_BUSINESS_NUMBER>",
"To": "<TEST_RECIPIENT>",
"Timestamp": 1795068000000,
"Status": "Delivered",
"StatusDescription": "<ACTUAL_STATUS_DESCRIPTION>"
}
]
接收端遍历数组,逐条保存消息标识、状态、时间和错误信息。Timestamp 使用毫秒,TaskId 是可选字段;本例以发送时主动传入订单号为前提。未传入时,文档规定它默认取 MessageId。
阿里云要求接收端在 3秒内返回 HTTP 200,响应体为:
{
"code": 0,
"msg": "成功"
}
推送失败后会重试,文档列出的重试间隔为1分钟、5分钟,共最多推送3次。因此,排查接收失败时要同时查看:
- 该 URL 是否实际收到 HTTP 请求;
- 返回状态码、响应体及耗时是否符合要求;
- 原始事件是否已可靠保存;
- 重试请求是否触发了重复的业务动作。
将查订单、通知客服等后续业务与 HTTP 接收拆开。先把事件可靠保存,再在规定时间内应答;业务处理失败由内部重试接续。不要把事件只放进进程内存就返回成功,避免服务重启后丢失已确认的记录。
响应格式、字段和重试说明见 ChatAppStatus HTTP 文档。
四、收到回执后,按这三类情况定位
情况一:接口成功,但状态只有 Sent
Sent 表示消息已发送,Delivered 表示已投递到用户设备,Read 表示已读。仅有 Code=OK 或 Sent 时,记录为“尚无送达证据”。
继续按同一 MessageId 查后续状态。出现 Failed 时,保存 ErrorCode 和 ErrorDescription,再按具体错误处理。没有状态报告时,先检查第三节的接收链路,不根据“没看到回执”直接推断消息没有发出。
情况二:回执已入库,订单仍显示未送达
从发送记录取 MessageId,到回执记录中按相同消息 ID 查找。重点检查:
- 关联时是否误用了
RequestId; - 同一订单的第二次发送是否覆盖了第一次消息 ID;
- 是否把默认的
TaskId当成业务订单号; - 是否只处理了数组中的第一条回执;
- 消息是否来自另一实例或另一通道。
用同一组字段记录一次排查:
订单:ALI-BSP-4086
发送记录:attempt-01
发送接口返回:MessageId=msg-demo-01
回执入库:MessageId=msg-demo-01,Status=Delivered
业务查询:使用 RequestId 查状态,未命中
修正:使用发送记录中的 MessageId 关联回执,再复核订单状态
这是模拟故障,用于说明关联键错误的定位方式。修正后复查原始记录,不仅检查页面上的状态文字。
保存原始状态事件时,不因收到重复推送再次执行相同的业务动作;较早的 Sent 事件晚到时,也不把已送达的展示状态回退为“已发送”。这属于业务侧的状态合并规则,不依赖推送严格按顺序到达。
情况三:通知已送达,客户回复却不在工作台
先从测试手机回复“ALI-BSP-4086 的物流信息需要更新”,再查看客户来信的接收链路:
测试手机发出回复
→ ChatAppInbound 接收端收到来信
→ 来信进入目标客服工作台
→ 指定客服回复
→ 测试手机收到答复
发送通知的 ChatAppStatus 正常,只能说明发信状态链路正常。客户回复需要独立检查 ChatAppInbound、工作台接待权限和实际路由。
以 SaleSmartly 对接 Chat App 的项目为例:SaleSmartly 同时提供自有 WhatsApp BSP 通道,但保留 Chat App 的项目仍按 Chat App 的接口和回执配置排查。客服工作台与实际消息通道分别记录,不能根据工作台品牌判断当前使用了哪个 BSP 通道。
客户来信产生新的入站消息记录,不沿用原通知的出站 MessageId。订单关联依靠明确的业务信息、回复引用或人工核对;订单和物流状态仍由企业订单系统维护。
五、送达记录与账单怎样对应?
正式对账时,用实际实例、发送号码、时间范围和适用费用明细核对。Chat App 消息费、平台服务费及套餐抵扣范围以官方计费文档为准。
回执中的 Delivered 不是金额凭证。只有账号级汇总账单时,保留其账号和账期范围,不将整月费用直接计入订单 ALI-BSP-4086 的一条通知。正式账单尚未生成,费用项保留为待核对。
六、把每个故障停在哪一步记录下来
| 已观察到的结果 | 下一步查什么 |
|---|---|
| 发送接口返回错误 | 参数、模板、账号权限及错误信息 |
| Code=OK,但没有状态事件 | ChatAppStatus 配置、HTTP 请求及响应日志 |
| 回执已入库,订单未更新 | MessageId 关联、数组遍历和每次发送记录 |
| 出现 Failed | 同条消息的错误码及描述 |
| 已送达,客户回复未进入工作台 | ChatAppInbound、接待权限和路由 |
| 工作台已回复,手机未收到 | 该次人工回复的发送记录与回执 |
| 消息正常,账单无法对应 | 实际账号、账期、费项和抵扣明细 |
对 ALI-BSP-4086,分别记录请求结果、送达证据、客户回复和对账状态。某一段成功,不提前替其他段标记通过。
整理:SaleSmartly 团队。资料核对日期:2026年11月19日。