whatsapp-management

WhatsApp 管理（通过 Nexor）

Nexor 是处理所有 WhatsApp 事务的统一入口。客户不会直接调用 Meta 或底层提供商——即使是连接号码，也会使用 Nexor 生成的托管设置链接。 以下每个工具都会根据 API key 自动限定租户范围； 切勿接受或传递用户提供的 client_id。

创建模板或解读健康状态载荷前，请先阅读 references/whatsapp-reference.md——其中包含长期适用的 Meta 规则（模板格式、类别、 质量评级、24 小时窗口），这些规则很少变化，却很容易出错。

按任务分类的工具

任务	工具
查看号码	list_whatsapp_numbers
连接号码	connect_whatsapp_number → 返回一个托管设置链接，供客户打开
修复故障号码	reconcile_whatsapp_number；如果需要重新进行 Meta 授权，则再次调用 connect_whatsapp_number
分配给 Agent	assign_whatsapp_to_workflow
停用／移除号码	deactivate_whatsapp_number（可恢复）；disconnect_whatsapp_number（管理员操作，不可恢复）
重命名（内部标签）	rename_whatsapp_number
企业资料	get_whatsapp_business_profile、set_whatsapp_display_name、set_whatsapp_profile_photo
健康状态与风险	get_whatsapp_health
响应时机（防抖）	get_whatsapp_response_timing、set_whatsapp_response_timing
“我的模板是否已获批准／需要多久？”	get_whatsapp_template_approval_status
模板 — 查看	list_whatsapp_templates、get_whatsapp_template、check_whatsapp_template_approvals、sync_whatsapp_templates
模板 — 创建	review_whatsapp_template_drafts → create_whatsapp_templates_batch（首选）；create_whatsapp_template（单个）
模板 — 管理	set_whatsapp_template_purpose、delete_whatsapp_template
发送频率池	get_template_pool、set_template_pool、set_opening_templates
发送消息	send_message

连接号码

1. connect_whatsapp_number → 返回一个托管设置链接。将链接提供给客户， 并告知他们打开链接；授权（Meta 登录、选择专用／共存模式）需要在那里完成， 无法在聊天中完成。
2. Nexor 会在流程完成后自动记录号码，并注册其入站 webhook。使用 list_whatsapp_numbers 确认。
3. 使用 assign_whatsapp_to_workflow 将号码绑定到 Agent——这样入站 消息才能到达该 Agent。
4. 每个客户端的号码上限为（默认 10 个）；达到上限时，connect_whatsapp_number 会返回 WHATSAPP_LIMIT_REACHED。

无需编写 OTP／验证流程——配置完全通过托管链接完成。如果已连接的号码之后出现故障， 请先运行 reconcile_whatsapp_number；只有在需要新的 Meta 授权时，才发送另一个设置链接。

健康状态与风险

“我的 WhatsApp 是否有风险／为什么无法发送／我的限额是多少” → 针对该号码调用 get_whatsapp_health。风险不由单个字段决定——请结合以下信息判断（详情见参考文档）：

• quality_rating：GREEN（正常）· YELLOW（需关注）· RED（有被 Meta 限制的风险）。
• messaging_health.can_send_message：AVAILABLE · LIMITED · BLOCKED，包含按实体 （WABA／phone）划分的错误和建议的修复措施。
• messaging_limit：每日等级和上限。
• route_verification：提供商路由是否有效，或是否需要重新连接／重新同步——如果显示需要重新连接，请运行 reconcile_whatsapp_number。

一次健康状态查询会触发多个 Meta 调用，因此结果会短暂缓存——不要循环轮询。 请用通俗语言概述状态，并建议具体的下一步操作。

模板

创建模板是 WhatsApp 任务中价值最高的一项。模板绝不能是通用的： 它必须属于某个特定的 Agent，并体现该 Agent 的角色设定、产品、目标和 语言。 阅读 references/whatsapp-reference.md，了解长期适用的 Meta 规则，以及 按 Agent 目标整理的入门模板库。请完整遵循以下流程——不要跳过步骤 直接起草。

1. 确定目标 Agent——绝不能跳过

模板必须契合真实 Agent 的沟通节奏；不要创建没有归属的模板。

• 如果对话已经指定了某个 Agent，就使用该 Agent。
• 否则，询问是哪一个 Agent，并通过 list_workflows 列出选项。
• 如果用户只说要“预约确认模板”，却没有指明 Agent，那么缺少的就是 Agent——先确定 Agent，再起草。

2. 起草前了解 Agent 的背景

调用 get_workflow(workflow_id) 并阅读其 goal_type、基础提示词／角色设定、 产品／公司、语言和已连接的渠道。这些信息能让文案贴合上下文——匹配 Agent 的语气，写出产品名称，并使用其语言，不要凭空创造通用语气。注意该 Agent 是否会预约会议（goal_type 为 appointment，或销售漏斗中包含预约阶段）：这决定了是否可以使用会议变量以及确认／提醒类入门模板。

3. 提出贴合上下文的入门模板

提供 2–4 个根据 Agent 目标量身定制的草稿，取自 references/whatsapp-reference.md 中的入门模板库，并使用 Agent 的真实产品、公司、 角色设定和语言进行调整。优先选择符合目标的模板：

• 预约／预订／确认类 Agent → 预约确认模板 （UTILITY、{{fecha}} / {{hora}} / {{link_reunion}}、确认和改期 快捷回复按钮）、提醒模板，以及爽约后的重新激活模板。
• 销售／资格筛选／信息类 Agent → 问候开场模板、跟进模板，以及 重新激活模板。

优先使用 Nexor 的标准变量，以便在发送时自动解析——{{nombre}}、 {{agente}}/{{ejecutivo}}、{{empresa}}、{{producto}}，以及会议相关变量 {{fecha}}、{{hora}}、{{asesor}}、{{link_reunion}}——如果 Agent 自带的 潜在客户元数据字段有用，也可以添加。其他名称仍可使用，但会回退到大模型 解析。

4. 严格按照控制台表单的要求构建按钮和变量

聊天界面与控制台模板构建器功能完全一致——请使用聊天界面。

• 按钮：QUICK_REPLY、URL（需要 url）、PHONE_NUMBER（需要 phone）。 总数最多为 10 个，URL 按钮不超过 2 个，电话按钮不超过 1 个；URL 按钮的变量必须位于 URL 末尾；不要将快捷回复按钮与 URL／电话按钮交错排列；标签不超过 25 个字符。
• 变量：格式为 {{...}}，不得出现在正文开头／结尾，也不得彼此相邻； 每个变量都必须在 variables 中提供真实示例。页脚不允许包含变量。TEXT 标题最多可包含一个变量，并且必须提供对应示例。

5. 预检 → 确认 → 提交

1. review_whatsapp_template_drafts——只读预检。操作者会在 WhatsApp 预览中（审核卡片）看到每个草稿的渲染结果及其有效性和问题。展示返回的 normalized_templates、错误和警告；修改后重复预检，直到 all_valid=true（此时会获得 review_id）。
2. 对这些确切的草稿取得明确确认。
3. 使用这些确切的草稿、review_id 和 confirm=true 调用 create_whatsapp_templates_batch。绝不要伪造确认。（如果批量／审核流程过于繁琐，可使用 create_whatsapp_template 这个单模板快捷方式。）

6. 将已批准的模板接入该 Agent 的工作节奏

这一步会让模板真正对所选 Agent 生效——创建模板后，如果没有用途且未加入该 Agent 的模板池，就不会发挥作用。提交后，针对步骤 1 中的 workflow_id：

• 如果之前没有传入 internal_type（greeting / follow_up / reminder / reactivation），请使用 set_whatsapp_template_purpose 设置每个模板的用途。
• 使用 get_template_pool 查看当前模板池，然后使用 set_template_pool 添加后续跟进 / 提醒 / 重新激活模板（整体替换状态——请发送完整的目标列表）。
• 使用 set_opening_templates 设置首次联系的开场模板。
• 使用 get_template_pool 读取更新后的模板池，并报告现在每个 Agent 使用哪些模板。

7. 报告审核结果和接入情况

Meta 的审核是异步的——请轮询 check_whatsapp_template_approvals，直到每个模板的状态变为 APPROVED 或 REJECTED。结束时说明 Agent、模板、模板用途和模板池接入情况，让用户了解完整信息。

• Meta 不支持原地编辑。如需修复被 REJECTED 的模板，请使用新名称修改并重新提交（可先预览，再选择使用 delete_whatsapp_template 删除旧模板）。

“我的模板通过审核了吗？” / “审核需要多久？”

在 Nexor 中，单独说“模板”始终指 WhatsApp 模板，因此任何未明确限定的模板问题（是否通过审核？需要多久？列表？编辑？）都应按 WhatsApp 模板处理。模板也只有在 WhatsApp 号码完全连接后才会存在——没有连接号码，模板就没有意义。

这是最常见的模板问题——请使用一个工具，根据数据作答，绝不猜测所需时间。

1. 调用 get_whatsapp_template_approval_status（该工具会先从 Meta 刷新状态，因此返回的是最新信息）。如果返回 no_whatsapp: true，说明尚未连接 WhatsApp 号码——请告知客户先连接号码（connect_whatsapp_number），不要说他们没有模板。否则，该工具返回的是摘要而非完整数据：按状态统计的 counts、all_approved / none、每个 pending[] 模板及其 pending_hours（实际等待了多久）、longest_pending_hours、some_pending_over_24h、每个 rejected[] 模板及其 Meta reason，以及 review_window。
2. 根据这些事实，用客户的语言作答：
   • all_approved: true → “N 个模板已全部通过审核 ✅。”
   • 有待审核模板 → “N 个模板中有 X 个已通过审核，Y 个仍在 Meta 审核中。”说明标准审核时长，绝不可编造预计时间：*审核是异步的，由 Meta 决定——通常需要几分钟到大约一小时，偶尔会延长到 24–48 小时。*如需提供具体情况，可引用 pending_hours 中的实际等待时长（例如：“等待时间最长的模板已待审约 3 小时”）。
   • some_pending_over_24h: true → 说明审核时间比通常更长；如果某个模板等待超过约 48 小时，解决方法是使用新名称修改后重新提交（Meta 不支持原地编辑）。
   • 存在 rejected[] → 列出模板名称及其 reason，并表示可以使用新名称修改模板。
   • none: true → 目前还没有模板；可以主动提出帮忙起草。
3. 不要承诺确切的审核时间，也不要在短时间内反复轮询——每次询问只调用一次。审核时间确实由 Meta 决定且会有所不同。

发送消息

send_message 可通过 whatsapp 向潜在客户发送消息（也支持 email/sms/call）。在 24 小时客户服务窗口内，可以发送自由文本；超出窗口后，必须传入已批准的 template_id——这是重新开启对话或首次联系的方式。

响应时间

get_whatsapp_response_timing / set_whatsapp_response_timing 用于控制入站消息的防抖时间（缓冲窗口，约 5-60 秒）：Nexor 等待多久后，将潜在客户连续快速发送的多条消息合并为一条回复。时间越长，回复越自然，但速度会稍慢。

防护措施

• 绝不要传入 client_id——租户信息会根据密钥推导得出。
• 破坏性操作（disconnect_whatsapp_number、delete_whatsapp_template）需要预览/确认或管理员授权；请先与客户确认，并复述将要更改的内容。
• 图片（set_whatsapp_profile_photo、IMAGE/VIDEO 模板标头）需要公开的 https URL——无法通过这些工具上传本地文件。
• 模板写入和资料变更会提交给 Meta 审核；请说明审核状态为待处理，不要暗示变更会立即生效。

相关技能

• automation-architecture — 配置 Agent 的工作流、状态、节奏和转接，供 WhatsApp 接入。