洽客服软消息发送失败
美洽出现“软消息发送失败”常见原因包括渠道限制（如WhatsApp模板、微信服务通知时效）、鉴权或账号问题、消息格式/附件违规、网络或队列堵塞以及平台限流或运营商拦截。排查顺序：先查看美洽平台返回的错误码与回调日志，用最小化文本复现问题，确认模板、用户订阅/时效、Token与通道状态，再逐项排除网络、队列与附件等因素。如果短时间内无法定位，导出相关请求/回调日志和时间戳提交美洽技术支持会更高效。下面把原因、日志位置、典型错误码与逐步排查方法讲清楚，方便你自己动手定位和修复。
先把“软消息”到底指什么说清楚
如果你第一次接触这个名词，先别慌：*软消息*在客服体系里通常是指由企业或客服主动推送给用户的非实时对话消息，比如活动通知、订单提醒、人工客服发起的问候等。不同渠道对“主动消息”的定义和限制不一样——这往往是失败的第一大类原因。
常见渠道的关键限制（简单版）
- WhatsApp：企业主动发消息通常需要使用已审批的模板（template），模板必须预先审核通过，且发送次数、速率受限。
- 微信公众平台/服务号：服务通知有时效和模板限制，超过时限或未使用模板会发送失败。
- Facebook/Instagram：同样有消息窗（24小时）和商用模板约束，隐私或内容政策也会拦截。
- 短信/SMS：运营商或地域法规可能拦截含敏感词或广告性质的内容，号码格式和签名也很重要。
把问题拆成能检查的几块（费曼法：把复杂变简单）
遇到发送失败，不要乱试。把流程分成五个“检查点”，逐个过一遍：
- 1. 平台返回与回调日志：这是最直接的线索，先看错误码和错误信息。
- 2. 渠道约束与模板：确认目标渠道是否允许当前类型的主动消息，模板是否通过，用户是否在允许接收时效内。
- 3. 鉴权与账号：API Key、Token、连接凭证是否过期或被撤销，账号是否被限制。
- 4. 网络与队列：检查网关、外呼队列、消息队列（如Redis、RabbitMQ）是否积压或抖动。
- 5. 内容合规与附件：消息体是否超过长度、是否包含被禁止的词、图片或文件是否过大或格式不支持。
具体排查步骤（实操清单）
- 收集基本信息：发生失败的准确时间点、业务方消息ID、用户标识（手机号或用户id）、目标渠道、错误码与错误信息、是否重试、是否仅个别用户受影响还是批量。
- 查看美洽后台与回调：在美洽控制台或API返回里找到该消息条目的请求体、应答、及平台对外部通道的回执（如果有）。记录下所有时间戳。
- 用最小化测试复现：发送一条最简单的纯文本消息（无图片、无链接、最短模板）到同一用户或一个测试用户，观察是否成功。
- 验证鉴权：检查AppKey/AppSecret、Token是否在有效期内，若是OAuth则尝试刷新Token并重试。
- 核对模板和时效：比如WhatsApp模板名和参数是否完全匹配，微信服务通知是否在可发送的时间窗内，用户是否对该模板或服务授予接收权限。
- 检查号码和格式：国际号码是否加了国际区号、是否去掉了特殊字符，手机号是否被运营商封锁。
- 查看队列与重试策略：若队列积压，可能出现延迟或直接丢弃；检查是否存在死信队列并查看原因。
- 检查附件和编码：图片格式（jpg/png）、大小、Base64/多部分上传是否正确，内容是否含非法字符或过多emoji导致编码问题。
- 网络与证书：若外部通道调用使用HTTPS，确认证书未过期、TLS版本兼容、没有被防火墙拦截。
- 必要时联系运营商或通道方回执：外部运营商的二次回执可能包含更详细的拦截原因（如垃圾短信、模板未批准等）。
常见错误码表（示例）
不同平台错误码不一样，但有一些通用的含义。下面这张表把常见情况和可采取的动作列出来，方便对照。
| 错误类型 | 可能返回的提示/码 | 应对措施 |
| 鉴权失败 | 401 / token_expired / invalid_credentials | 检查并刷新Token，确认AppKey/Secret无误，查看是否被停用 |
| 模板未通过或不匹配 | template_not_approved / 400_template_mismatch | 在美洽或渠道后台确认模板状态，修正参数与格式，重新提交审批 |
| 超出时效/订阅限制 | time_window_error / user_opted_out | 确认用户是否在接收时效内或是否取消订阅，调整消息类型或征得用户同意 |
| 内容违规或被拦截 | content_block / 403_forbidden | 审查文字与链接，去掉敏感词或营销元素，重新提交 |
| 队列或网关异常 | rate_limit_exceeded / gateway_timeout (504) | 做退避重试，检查队列消费速率与异常堆积，扩容或优化并发 |
常见场景和对应快速解决办法
- 批量消息部分失败：先看失败条数与成功条数差异，若是速率限制造成，降低并发或按批次发送；若是内容问题，多数渠道会对某些用户批量拦截，检查是否包含敏感内容。
- 单个用户始终失败：检查该用户的订阅状态、账号是否拉黑或被运营商拦截，尝试更换测试号码或渠道验证。
- 带附件的消息失败：先用纯文本测试是否成功，若成功则说明附件问题。检查文件大小限制、格式和上传参数。
- 发送成功但用户未收到：查看通道侧的投递回执（delivery receipt），如果通道显示已投递，则可能是用户设备或网络问题；如果通道显示失败，查看运营商回执。
监控与防御性设计建议（防止再犯）
- 建立异常告警：当消息失败率短时间内上升时自动告警，并把关键日志打包发给责任人。
- 全链路日志并可查询：保存请求体、返回体、回调与时间戳，方便事后定位。
- 重试与死信策略：对可重试的错误（如超时、临时网关错误）做指数退避重试，最终落入死信队列并人工处理。
- 模板与内容管理：把所有渠道模板集中管理，并记录每个模板的审批状态与示例参数。
- 预发与灰度：重要活动先在小范围灰度推送，避免批量失败造成影响。
联系美洽技术支持时要准备的材料
这样能显著提升响应效率：
- 发生问题的精确时间点（最好到毫秒）
- 美洽消息ID或业务方的消息ID
- 目标用户标识（脱敏手机号或用户ID）
- 请求体与平台返回体（JSON）以及回调日志
- 重试次数与是否为批量任务
- 如果有，运营商或通道的回执
小贴士：常被忽视但常见的坑
- 手机号码未加国家码导致国际通道拒绝。
- 模板参数多了空格或换行，导致模板匹配失败。
- 包含短链接或敏感词自动触发风控。
- 同时对同一用户多通道并发下发，导致重复拦截或速率冲突。
- Emoji或特殊字符在某些通道被视为非法字符。
举个小例子帮你记住流程（像教别人一样）
想象你是快递员，用户没收到包裹。你会先看签收回执（回调日志），再确认地址是否正确（手机号/渠道），查看路上是否堵车（队列与限流），最后确认包裹是否被退回（运营商拦截）。按这个顺序查，往往两步之内就能定位问题。
如果你按照上面清单逐项核查过，还是没头绪，别着急——把收集到的请求/返回/回调与时间线整理好发给美洽支持，同时在你那边先把可复现的最简请求保存好，技术同事会更快定位。好了，这些是我自己排过问题后归纳下来的经验，写得有点琐碎，算是边做边记，可能还有遗漏，但应该能帮你先把最常见的坑清掉。