WhatsApp Business 用户名程序化管理

本指南介绍了如何通过 POST /api/v1/check 端点，将 WhatsApp 注册、头像和商业账户的同步检查集成到 CRM 工作流中。

WhatsApp 身份映射的程序化管理涉及使用指定的 POST /api/v1/check 端点来验证注册状态、头像可用性以及商业账户类型。通过提交 E.164 格式的号码并配合相应的 service_type 有效载荷，团队可以在同一个 HTTP 响应中同步接收 JSON 数据。这种账户存在信号有助于丰富 CRM 记录、支持潜在客户列表清理，并为自动化路由工作流提供参考，使运营团队能够在无需依赖异步轮询或 Webhook 的情况下，获得细分联系人所需的背景信息。

程序化 WhatsApp 检查的作用

将 WhatsApp 账户存在信号集成到业务运营中，有助于团队维护更整洁的数据库，并支持更高效的沟通工作流。当组织通过注册表单、潜在客户开发活动或客户支持门户收集电话号码时，这些号码往往缺乏关于其消息平台存在状态的背景信息。 通过在发起外联前对这些号码进行程序化检查，运营团队可以根据活跃的平台注册情况对联系人列表进行细分。此过程通过识别哪些记录关联了 WhatsApp 账户而哪些没有，从而支持潜在客户列表的清理。此外，它还能为自动化路由决策提供参考。这种程序化方法有助于保持数据准确性，并为团队提供有效构建沟通渠道所需的背景信息。

理解 WhatsApp 身份信号

该平台通过单一端点提供三种不同的服务类型，允许开发者根据工作流需求请求特定详细程度的信息。每种服务类型决定了 JSON 响应中返回的字段以及适用的余额扣费标准。

• 注册检查 (ws)： 这是基础检查。它评估提交的 E.164 号码并返回 registered 字段，提供标准 WhatsApp 平台上的账户存在信号。
• 头像检查 (ws_avatar)： 此检查包含基础注册状态，并增加了个人资料丰富数据。它返回一个 avatar 布尔值（指示头像是否可用），并在上游服务提供时返回 avatar_url 字符串。
• 商业账户检查 (ws_business)： 专为 B2B 细分设计，此检查在返回基础注册状态的同时，还会返回一个 business 布尔值。这一特定信号有助于团队识别联系人是否正在使用 WhatsApp Business 账户。 无论选择哪种服务类型，每次检查响应都包含一组标准字段：id、identifier、registered、transaction_id、status、service_type 和 charged_amount_micros。

实现同步 API 工作流

技术集成依赖于简单直接的同步请求契约。由于结果是同步的，它们会在与请求相同的 HTTP 响应中返回。CRM 系统可以将记录保存在内存中，调用 API，并立即将返回的信号应用于工作流。 记录的请求契约要求向 POST /api/v1/check 端点发送请求。请求必须包含两个标头：包含您的身份验证密钥的 X-API-Key，以及 Content-Type: application/json。 JSON 正文必须包含两个字段：

• service_type：字符串值，可选 ws、ws_avatar 或 ws_business。
• identifier：符合 E.164 标准的电话号码。 为支持此集成，平台仪表板提供了全面的管理工具。开发和运营团队可以管理 API 密钥、监控余额、查看检查历史记录并访问产品级报告。仪表板还会显示最近的检查记录、余额支出指标和 7 天趋势，以帮助监控 API 使用情况和工作流容量。

数据完整性与路由的最佳实践

在将程序化检查集成到生产环境时，对数据所代表的含义设定准确的预期至关重要。注册结果报告的是检查时刻可用的 WhatsApp 状态字段。它仅作为账户存在信号。它不会验证在线状态、最后上线时间戳、消息历史记录或联系人许可。 从运营角度来看，该服务采用按次付费的计费模式。为保护数据完整性和预算，任何返回失败或未确定状态的检查都会自动退款。对于正在评估 API 以进行新集成的团队，新账户可以申请 0.10 美元的试用余额，该余额可用于注册、头像和商业账户检查，以便在部署到生产环境前测试同步工作流。

常见问题解答

注册检查和商业账户检查有什么区别？

标准注册检查（使用 ws 服务类型）返回一个账户存在信号，指示提交的 E.164 号码是否在 WhatsApp 上注册。商业账户检查（使用 ws_business 服务类型）返回相同的注册状态，但会增加一个 business 布尔字段，用于指示该账户是否使用 WhatsApp Business。

我需要为 WhatsApp 检查设置 Webhook 吗？

不需要。所有检查都是同步的。结果会在与初始请求相同的 HTTP 响应中返回，无需在您的应用程序中配置 Webhook 或实现异步轮询逻辑。

API 的电话号码格式要求是什么？

所有提交的电话号码必须符合 E.164 国际电话编号计划标准。

注册状态是否意味着我可以向该用户发送消息？

注册结果仅是检查时刻可用的账户存在信号。它不会检查在线状态、最后上线时间、消息历史记录、联系人许可，或该号码是否能成功接收消息。

失败或未确定的检查如何计费？

平台采用按次付费的计费模式。任何导致失败或未确定状态的检查都会自动退还到账户余额中。