service-de-waba-integrate

将 WABA 关联到 Salesforce

此技能的作用

通过指引帮助客户从“我有一个 WABA”完成到“我的 WABA 已关联到 Salesforce”——全程只需按照说明操作。Meta 有意将此操作限制在 business.facebook.com 的人工审批界面中；没有可通过脚本建立合作关系的 Graph 写入端点。用于探测状态的两个 GET 端点（/{waba-id}/subscribed_apps、/{waba-id}/assigned_users）需要具有 whatsapp_business_management 范围的 Meta 访问令牌，而客户必须自行生成该令牌——这比仅仅“检查你的 Partners 选项卡”要求高得多。

因此，此技能完全是渲染操作说明并提示用户确认。不调用 API，不写入 SF 数据库，也不使用 Meta 令牌。

此技能返回成功后，即可继续进行下游插入（service-de-channel-create）：SF 侧的 setupLiveMessageChannelEnhanced 路径不要求我们已证明合作关系确实存在——如果客户说了假话，该路径会返回清晰的 Meta 前置条件错误，而此技能会信任客户的确认。

不要在以下情况下使用此技能

• 你已在之前的运行中确认过合作关系。 编排器的恢复逻辑不会跳过阶段 1（SF 侧没有简单的探测方法），因此此技能始终会运行——但它只会显示文本并提示用户，不会进行往返调用。
• 你要插入的是非 WhatsApp 渠道。 Line、Apple 和 Facebook 不使用 Meta Business Manager 合作关系。对于这些流程，请完全跳过此技能。
• 客户改用 Embedded Signup 弹出窗口。 那是另一种流程（由弹出窗口驱动、在 SF UI 侧进行 OAuth）；此技能专用于无界面的替代流程。

输入（来自调用方）

• {WABA_ID} — WhatsApp Business Account ID。仅用于渲染内容（以便说明中显示正确的 ID，并告知用户“打开你的 WABA”）。
• {SF_BM_ID} — 可选。默认为 10152614792574154（Salesforce 的 Business Manager ID，已由用户于 2026-04-29 确认；参见 IMPLEMENTATION.md §13 journey log）。仅当 Salesforce 针对特定合作伙伴计划提供了不同的 BM ID 时才覆盖此值。

输出（返回给调用方）

成功 — 用户确认合作关系已建立：

{"ok": true, "linked": true, "path": "user-confirmed",
 "note": "partnership confirmed by user; subsequent channel insert will
          surface any server-side issues clearly"}

失败 — 合作关系尚未建立：

{"ok": false, "kind": "partnership-blocked",
 "hint": "customer reported Salesforce is not in the Partners tab;
          most likely causes: (a) WABA ID typo, (b) user lacks admin
          role in the Business Manager, (c) partnership request still
          pending Meta approval. Retry this skill after resolving."}

失败 — 用户拒绝或中途退出：

{"ok": false, "kind": "user-declined",
 "hint": "user cancelled the linking step; re-run the orchestrator
          when the customer is ready to click through Business Suite"}

---

阶段 1：显示操作说明

替换 {WABA_ID} 和 {SF_BM_ID}，并直接以 Markdown 文本形式向用户输出以下内容（不要使用 cat、echo 或任何会折叠输出的 Bash 命令）：

──────────────────────────────────────────────────────────────
**Before we can insert the WhatsApp channel in Salesforce, your
WhatsApp Business Account must be shared with Salesforce on
Meta's side.** Meta gates this step behind business.facebook.com —
there's no API we can call to automate it.

## One-time steps (takes ~2 minutes):

1. Go to https://business.facebook.com
2. In the left nav, open "WhatsApp Accounts" and click your
   WABA (ID: **{WABA_ID}**)
3. Click the "Partners" tab at the top of the WABA page
4. Look at the list:
   - **If "Salesforce" (or "Salesforce.com") is already listed
     with Full control** — you're done, nothing to do.
   - **If NOT listed** (or listed with only partial access):
     
     a. Click "Add partners" → "Share account with partner"
     
     b. Paste this Business Manager ID in "Enter partner
        business ID":
     
     ```
     {SF_BM_ID}
     ```
     
     c. Scroll to the "Full control" section at the bottom
        and toggle ON "Everything":
     
     ```
     [x] Everything — manage all settings, assign users,
         view payment information and send messages
     ```
     
     This is the option Salesforce needs. The Partial
     access toggles above (Phone numbers / Message
     templates / Messages) do NOT cover assigning users
     or managing webhook subscriptions — those require
     the Full control option. Don't try to grant access
     piecemeal through Partial access.
     
     d. Click "Assign"

## Notes:
- Your Meta Business Manager must be business-verified for Meta
  to accept the partnership. If it's not verified, Meta will
  block the "Assign" step with a clear error.
- You need admin role on the Business Manager to assign partners.
  If you're a regular employee, ask an admin on your team.
- Max 2 partners per WABA. If you've already shared with another
  BSP, Salesforce would be the second — which is fine.
──────────────────────────────────────────────────────────────

重要： 请在回复中直接向用户输出此文本，不要通过 Bash/cat/echo 输出。工具结果会被折叠；直接输出的文本会保持可见。

---

阶段 2：请求确认

使用 AskUserQuestion 提示：

Question: Is "Salesforce" now showing in the Partners tab for this WABA?
Header: Partnership
Options:
  1. Yes — already there or just added it
     (Salesforce appears in the Partners tab with Full control)
  2. No — still not showing
     (Partnership not yet in place after attempting to add it)
  3. Skip — abort setup for now
     (Not going to complete this step right now)

不要尝试通过 Meta 验证回答。请信任用户。如果用户回答“是”但实际上并非如此，下游的 service-de-channel-create 会返回 meta-precondition 信封，并清楚指出问题——这比在此处伪造一个探测流程要好，因为该流程需要客户提供 Meta 令牌。

阶段 3：输出信封

根据用户的回答，构造相应的信封，并将其写入 /tmp/linking-waba-result.json，以便调用方技能解析：

用户的回答	要写入的信封
y	{"ok":true, "linked":true, "path":"user-confirmed", "note":"partnership confirmed by user; subsequent channel insert will surface any server-side issues clearly"}
n	{"ok":false, "kind":"partnership-blocked", "hint":"customer reported Salesforce is not in the Partners tab; most likely causes: (a) WABA ID typo, (b) user lacks admin role in the Business Manager, (c) partnership request still pending Meta approval. Retry this skill after resolving."}
s	{"ok":false, "kind":"user-declined", "hint":"user cancelled the linking step; re-run the orchestrator when the customer is ready to click through Business Suite"}

使用以下内容写入信封：

echo '{envelope json}' > /tmp/linking-waba-result.json

然后向用户显示易读的摘要：

• 对于 y：Success — WABA linked — Salesforce confirmed as a partner on WABA {WABA_ID}. Proceed to service-de-channel-create.
• 对于 n：Error: Partnership not yet in place — fix the issue on Meta's side (see instructions above) and re-run. Common fixes: check WABA ID, confirm your Business Manager is business-verified, confirm you have admin role.
• 对于 s：⏸ Linking skipped by user — re-run when ready.

---

示例：客户已与 Salesforce 共享

输入：{WABA_ID}=1558753535400324

阶段 1：技能显示包含 WABA ID 的说明。客户打开 Business Suite → WhatsApp Accounts → 1558753535400324 → Partners。看到列表中有“Salesforce”。

阶段 2：客户回答 y。

阶段 3：输出：

{"ok":true, "linked":true, "path":"user-confirmed",
 "note":"partnership confirmed by user; subsequent channel insert will surface any server-side issues clearly"}

编排器继续执行 service-de-channel-create。

示例：客户需要添加合作关系

相同输入。客户打开 Business Suite，没有在 Partners 中看到 Salesforce，于是点击 Add partners → Share account with partner → 粘贴 10152614792574154 → 向下滚动到“Full control”部分 → 将“Everything”切换为 ON → 点击 Assign。Meta 显示“Partnership request sent”或类似消息。合作关系随后生效（通常立即生效；如果 Meta 需要审核，有时会等待几分钟）。

客户确认 Salesforce 现在已显示后回答 y。

编排器继续执行。

示例：Business Manager 尚未完成企业验证

客户点击 Assign，Meta 拒绝并提示“Your business must be verified to assign partners.”客户在我们的提示中回答 n。

阶段 3：输出：

{"ok":false, "kind":"partnership-blocked",
 "hint":"customer reported Salesforce is not in the Partners tab; most likely causes: (a) WABA ID typo, (b) user lacks admin role in the Business Manager, (c) partnership request still pending Meta approval. Retry this skill after resolving."}

编排器输出一条标注步骤的失败信息，指向此技能；用户另行通过 Meta 完成企业验证，之后再重新运行。

---

注意事项

1. 没有客户的 Meta 令牌，我们就无法探测状态。GET /{waba-id}/subscribed_apps 和 GET /{waba-id}/assigned_users 可以确认 SF 的应用是否已订阅／用户是否已分配，但两者都需要客户在 Meta 应用中生成令牌——为了少显示一条提示，却要额外花 20 分钟，不值得。相信客户亲眼所见即可。

2. **“Partners 中有 Salesforce”≠“SF webhook 订阅已生效”。**订阅是另一项服务器端事件，会在合作关系建立后发生，此时 SF 的 BSP 应用会注意到这一点，并调用其自身的内部设置流程。客户在此技能中的确认针对的是合作关系，而非订阅状态——等到运行 service-de-channel-create 时，订阅应该已经同步完成。如果还没有，插入操作会明确失败，并返回 Meta 前置条件错误，然后我们再重试。

3. SF_BM_ID 是一个固定值。 10152614792574154 是 Salesforce 的 Business Manager ID，所有客户在所有组织中都使用同一个值。已于 2026-04-29 确认（IMPLEMENTATION.md §13）。不要轻易允许调用方覆盖此值——如果有人传入了不同的值，他们很可能误解了该字段的用途。保留覆盖能力以应对边缘情况（例如，未来 SF 为合作伙伴分配专属 BM ID），但不要在文档中重点说明。

4. “Users”选项卡和“Partners”选项卡并不相同。 较早版本的 IMPLEMENTATION.md 草稿采用“添加 SF 管理员用户”的说法（Users 选项卡）；当前规范流程则是“将 SF 添加为 Partner”，并使用上述 BM ID。两种方式最终都会授予 Salesforce 对 WABA 的访问权限，但 Partners 流程更简洁（无需逐个用户维护，权限范围由合作伙伴角色决定）。请使用 Partners 流程。

5. Embedded Signup 是替代方案，而非补充方案。 使用 Embedded Signup 弹出窗口的客户会完全跳过此技能——弹出窗口会通过 Meta 的 OAuth 流程内联处理合作关系授权。此技能适用于无头流程（客户倾向于通过 Business Suite 点击操作，而非使用浏览器弹出窗口）。不要尝试同时运行两种流程。

6. Orchestrator 即使在恢复运行时也会调用此技能。 SF 端没有可检查的状态（订阅落地页不会显示任何状态），因此再次运行时会重新呈现说明并再次提示。这没问题——如果客户之前已经确认过，提示几乎会即时完成，而且此技能不会产生副作用。幂等性是其固有特性。

7. 不使用 sf CLI 命令、SOQL 或 HTTP。 此技能应当是纯文本加一条提示。如果未来版本要探测状态（例如通过环境变量使用客户提供的 Meta token 等），那属于增量增强——不要让它挤占正常流程。仅提供说明的设计正是此功能的特点。

8. 每个 WABA 最多可关联 2 个合作伙伴。 如果客户已与另一个 BSP（Twilio、360dialog 等）共享，Salesforce 将成为第 2 个合作伙伴——没问题。如果他们已有 2 个 BSP，Meta 会阻止分配，客户需要先移除其中一个。这种情况很少见，但 Stage 1 呈现的文本中已对此作出说明，这样客户遇到的是已知错误消息，而不是莫名其妙的失败。

9. 必须授予“Full control / Everything”，不能只启用“Partial access”切换项。 Meta 的合作伙伴共享对话框分为两个部分：“Partial access”（单独的切换项：查看／管理电话号码、查看／管理消息模板、管理电话号码和消息模板、消息）和“Full control”（单个“Everything”切换项）。Salesforce 需要 Full control / Everything，原因如下：

   • 分配用户——SF 会在 WABA 上配置服务账号来操作该账号。只有 Everything 切换项会授予此权限；Partial access 的任何切换项都不包含此权限。
   • Webhook 订阅管理——POST /{waba-id}/subscribed_apps（使 SF 的 BSP 应用能够接收传入消息）需要 whatsapp_business_management scope，该权限对应 Full control，而不是 Partial access 切换项。
   • 信用额度／付款方式可见性——需要此权限才能让 SF 使用客户自己的账单进行消息发送。此权限明确仅包含在“Everything”的说明中（“查看付款信息”）。

   如果客户只授予部分访问权限（例如仅授予“管理电话号码和消息模板”），渠道 可能 会在 SF 端成功添加，但之后激活／发送消息时会因 Meta 权限不足而失败，并出现含义不明的错误。Partial access 适用于非 BSP 集成（仅需发送模板消息的营销工具等），而非 BSP。不要让任何人“优化”呈现的说明以缩小权限范围——这只是在虚假节省，最终会在流程后期导致令人困惑的失败。