WhatsApp API 发送失败和代理 IP 有什么关系？

WhatsApp API 发送失败只有在请求无法正常建立连接、认证失败、DNS 异常或代理链路超时时，才可能直接与代理 IP 有关。接口权限、模板状态、号码质量、请求格式和平台限流等问题，换 IP 通常无效。

WhatsApp API 发送失败，先判断是连接层还是业务层

WhatsApp API 代理连接参数应该怎么检查？

WhatsApp API 的协议、主机和端口应该怎么填写？

透明代理接入通常只需协议、主机、端口、账号和密码。确认应用支持 HTTP、HTTPS 或 SOCKS5，并检查是否把端口、协议或认证字段填错。动态住宅 API 提取可参考动态住宅 API 提取教程。

账号认证失败或返回 407 时怎么排查？

可以按字段逐项核对：协议决定连接方式，主机和端口决定入口，账号密码或白名单决定认证。返回 407 时优先检查认证；连接超时则检查端口、DNS、防火墙，以及客户端是否真正走代理。完整字段说明可参考代理设置帮助。

参数填写无误后，不要直接更换模板或令牌；先用同一请求做直连与代理对照，确认问题发生在网络层还是业务层。

如何用一次对照请求定位 WhatsApp API 发送失败？

1. 保存完整状态码、响应体和请求时间。
2. 在合规网络环境下，用相同参数分别测试直连与代理连接。
3. 只更换代理出口，保持令牌、模板、号码和请求体不变。
4. 保存两次请求的状态码、响应体和时间，按差异定位故障层级。

直连成功、代理失败，优先检查代理协议、认证、DNS、端口和超时；两种连接都返回业务响应时，依据错误字段检查令牌、模板、号码权限或平台限制；没有正常业务响应时，先按连接超时处理。

可复制的对照请求：直连成功、代理失败

下面示例使用占位符，令牌、号码和模板名均已脱敏。两次请求只改变是否经过代理，便于定位连接层问题。

直连请求

先发送不经过代理的基准请求，记录 HTTP 状态码和 Graph API 返回内容：

```bash
curl --request POST "https://graph.facebook.com/v20.0/<PHONE_NUMBER_ID>/messages" \
--header "Authorization: Bearer <ACCESS_TOKEN>" \
--header "Content-Type: application/json" \
--data '{"messaging_product":"whatsapp","to":"<RECIPIENT>","type":"template","template":{"name":"order_update","language":{"code":"en_US"}}}'
```

经过代理请求

保持接口、令牌、收件人和模板参数不变，仅增加 --proxy 参数后再次发送：

```bash
curl --proxy "http://<PROXY_USER>:<PROXY_PASSWORD>@<PROXY_HOST>:<PROXY_PORT>" \
--request POST "https://graph.facebook.com/v20.0/<PHONE_NUMBER_ID>/messages" \
--header "Authorization: Bearer <ACCESS_TOKEN>" \
--header "Content-Type: application/json" \
--data '{"messaging_product":"whatsapp","to":"<RECIPIENT>","type":"template","template":{"name":"order_update","language":{"code":"en_US"}}}'
```

脱敏后的原始结果可以按下面方式记录：

```text
直连：HTTP/2 200
{"messages":[{"id":"wamid.***"}]}

代理：HTTP/1.1 407 Proxy Authentication Required
```

若代理返回 407，说明请求尚未到达 WhatsApp API；响应体由代理IP生成，通常是纯文本、HTML 或空体，并非 Graph API JSON。先检查代理认证。若返回 Graph API 业务错误，记录错误字段并转查令牌、模板或权限。生产日志只保留状态码、错误类型、fbtrace_id（如有）和时间，不要记录完整令牌或收件人号码。

需要轮换出口进行独立请求测试时，可评估动态住宅代理 IP。

需要长期保持同一服务出口时，可评估静态住宅代理 IP。

完成连接层对照后，WhatsApp API 的平台场景和相关问题可参考WhatsApp 代理 IP 指南。

WhatsApp API 发送失败时，如何查官方文档？

先根据错误位置判断处理方向：返回 407 时检查代理认证；模板相关错误对照消息模板要求；权限错误检查令牌和业务资产；出现限流时再查看请求频率和重试边界。平台错误对象的字段解释，可参考 Meta Graph API 错误处理。

遇到平台返回的错误对象时，应以响应中的 code、error_subcode、type 和 fbtrace_id 为准，不要仅凭 HTTP 状态码猜测原因。

FAQ

返回 407 是 WhatsApp API 错误吗？

通常不是。407 表示代理认证失败，应检查账号密码、认证方式和客户端配置。

换代理 IP 能解决模板消息发送失败吗？

如果返回的是模板未审核、权限不足或消息类型不允许，换 IP 无法解决，应先处理接口业务错误。

如何判断是超时还是平台拒绝？

超时通常没有正常的业务响应；平台拒绝一般会返回明确状态码和错误内容。排查时必须保存原始响应。

先保存原始响应，再做直连/代理对照，并结合 HTTP 状态码与 Graph API 错误字段定位故障层级。