Chat App 接入 WhatsApp API:请求成功后,如何排查消息回执

简介: SendChatappMessage 返回成功,不代表消息已经送达。本文以模拟订单说明 Chat App 的实例与模板参数、MessageId 关联、ChatAppStatus HTTP 响应和客户来信排查方法,给出请求成功无回执、回执无法关联订单及工作台未收到回复三类故障的检查顺序。

调用 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 查找。重点检查:

  1. 关联时是否误用了 RequestId;
  2. 同一订单的第二次发送是否覆盖了第一次消息 ID;
  3. 是否把默认的 TaskId 当成业务订单号;
  4. 是否只处理了数组中的第一条回执;
  5. 消息是否来自另一实例或另一通道。

用同一组字段记录一次排查:

订单: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日。

目录
相关文章
|
5天前
|
Linux Go 开发工具
手机上跑 DeepSeek 智能体:开源安卓客户端 DSH Go 安装与使用指南
DSH Go 是一款开源安卓客户端,将 DeepSeek Harness 智能体引擎装进手机:免 Root、免 Termux,一键安装即用;支持本机运行(内置 Ubuntu+Node.js)或远程接管电脑会话;具备插话打断、过程折叠、屏幕操控、端到端加密分享等特色功能,真正实现智能体“口袋化”。
6238 14
|
5天前
|
弹性计算 人工智能 API
Codex超详细入门指南(下载·安装·登录·上手,全版本覆盖,2026最新版)
建议收藏本教程,2026 全年各版本更新随时回来查阅。如果你在搭建过程中遇到任何问题,欢迎结合 阿里云工单系统 提交技术支持请求,或在 阿里云开发者社区 搜索 Codex 相关话题交流。 祝你编码愉快,效率翻倍!
2238 8
|
8天前
|
人工智能 前端开发 API
阿里云Qwen4-Max 大模型详解:定位、特征、能力、适用场景与相对Qwen3-Max差异解析
2026年11月11日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问AI平台Token Plan并接入千问办公、Qoder等入口。该版本聚焦知识理解、世界感知、编程与Agentic四项升级,主打复杂编程、专业办公、前端设计与专业软件操作等真实任务。预览期为11月11日10:00至11月25日24:00,仅支持Token Plan调用,到期后模型标识下线;限时2折、新用户再享5折,最低1折可体验。
|
8天前
|
JSON 前端开发 API
阿里云最新Qwen4-Max大模型介绍:模型定位、特征、能力、适用场景解析
2026 年 11 月 11 日,阿里发布第四代旗舰模型Qwen4-Max预览版,首发千问 AI 平台 Token Plan,并同步接入千问办公、Qoder 等入口。该版本聚焦知识理解、世界感知、编程与 Agentic 四项升级,主打复杂编程、专业办公、前端设计与专业软件操作。预览期至 11 月 25 日 24:00,到期后模型标识下线;限时 2 折、新用户再享 5 折,最低 1 折可体验。
|
3天前
|
传感器 安全 区块链
Windows 电脑运行安卓应用教程:开源工具 ApkStart 双击 APK 即装、独立窗口运行
ApkStart 是一款开源Windows工具,让安卓APP像原生软件一样运行:双击APK即安装、生成真实图标、独立窗口启动、开始菜单可搜索。无需传统模拟器,内置QEMU运行时,支持数据互通、ARM兼容与命令行操作。(239字)
|
20天前
|
Linux 开发工具 iOS开发
Codex保姆级教程(下载+安装+登录+使用,含所有版本,2026最新)
Codex是OpenAI推出的开源AI编程智能体,本地运行,可理解整个代码库,支持自然语言指令改代码、执行命令、跑测试、修Bug,兼容Win/macOS/Linux。(239字)
10030 59
|
3天前
|
人工智能 弹性计算 开发工具
零成本玩各大模型!DeepSeek Harness dsh-our-free-model 插件,13 个厂商模型直接用
总结一下:装这个插件,你不用注册、不用绑卡、不用填一个 Key,就能在 DeepSeek Harness 里用上 DeepSeek V4.1 Flash、Kimi K3 这一批前沿模型,而且是白嫖的、还不限量。三步搞定:下载插件,复制包含 `package.json` 的插件目录路径,在「添加插件」里粘贴路径安装并重启。无论是在阿里云 ECS 上通过命令行部署的 Web 版,还是本地的 Electron 桌面端,都能顺利跑通,快速搭建一套零成本的免费模型使用环境。
1015 0
|
6天前
|
Linux API iOS开发
【DSH】DeepSeek Harness新手保姆教程(下载+安装+配置+使用,2026最新实测)
DeepSeek Harness(dsh)是DeepSeek AI开源的智能体框架,秉持“一切皆插件”理念,支持读文件、改代码、跑命令、处理表格、联网搜索等操作。免费开源,兼容Windows/macOS/Linux,提供桌面端与网页端,可灵活安装插件扩展能力。
|
15天前
|
Linux 开发工具 iOS开发
2026最新codex下载安装保姆级使用教程(下载+安装+登录+使用,含所有历史版本)
本文详解OpenAI Codex国内快速上手指南:提供Win/macOS/Linux全平台免安装包、npm/Homebrew等多方式安装、账号/API Key双登录、简体中文切换,覆盖下载、安装、汉化、使用及高频避坑(如微软商店失败、npm超时等),10分钟即可跑通。
3414 9