Service De Waba Integrate

Linking a WABA to Salesforce

What this skill does

Gets the customer from "I have a WABA" to "my WABA is linked to Salesforce" — entirely by instruction. Meta intentionally gates this behind the human-approval UI at business.facebook.com; there's no Graph write endpoint that scripts the partnership. The two GET endpoints that would let us probe state (/{waba-id}/subscribed_apps, /{waba-id}/assigned_users) need a Meta access token with whatsapp_business_management scope that the customer would have to generate — a bigger ask than just "check your Partners tab."

So the skill is 100% instruction rendering + one confirmation prompt. No API calls. No SF DB writes. No Meta tokens.

After this skill returns success, downstream insertion (service-de-channel-create) can proceed: the SF-side setupLiveMessageChannelEnhanced path doesn't require us to have proven the partnership — it'll fail with a clear Meta-precondition error if the customer lied, and our skill trusts the customer's confirmation.

When NOT to use this skill

• You've already confirmed the partnership on a previous run. The orchestrator's resume logic doesn't short-circuit Stage 1 (no cheap SF-side probe exists), so this skill always runs — but it's just text + a prompt, no round trip.
• You're inserting a non-WhatsApp channel. Line / Apple / Facebook don't use Meta Business Manager partnerships. Skip this skill entirely for those paths.
• The customer is using the Embedded Signup popup instead. That's a different flow (popup-driven, SF-UI-side OAuth); this skill is specifically the headless alternative.

Inputs (from caller)

• {WABA_ID} — WhatsApp Business Account ID. Used only for rendering (so the instructions say "open YOUR WABA" with the right id visible).
• {SF_BM_ID} — optional. Defaults to 10152614792574154 (Salesforce's Business Manager ID, confirmed by user 2026-04-29; see IMPLEMENTATION.md §13 journey log). Override only if Salesforce issues a different BM ID for a specific partner program.

Output (to caller)

Success — user confirmed the partnership is in place:

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

Failure — partnership not yet in place:

{"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."}

Failure — user-declined or dropped:

{"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"}

Stage 1: Render the instructions

Substitute {WABA_ID} and {SF_BM_ID} and output the following directly as markdown text to the user (do NOT use cat, echo, or any Bash command that would collapse the output):

──────────────────────────────────────────────────────────────
**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.
──────────────────────────────────────────────────────────────

CRITICAL: Output this text directly in your response to the user, not via Bash/cat/echo. Tool results get collapsed; direct text output stays visible.

Stage 2: Ask for confirmation

Use AskUserQuestion to prompt:

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)

Do not try to validate the answer with Meta. Trust the user. If they said yes and lied, downstream service-de-channel-create will fail with a meta-precondition envelope that clearly names the issue — that's a cleaner failure than fabricating a probe here that would need a customer Meta token.

Stage 3: Emit the envelope

Based on the user's answer, construct the appropriate envelope and write it to /tmp/linking-waba-result.json so the calling skill can parse it:

Write the envelope using:

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

Then display the human-readable summary to the user:

• For y: Success — WABA linked — Salesforce confirmed as a partner on WABA {WABA_ID}. Proceed to service-de-channel-create.
• For 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.
• For s: ⏸ Linking skipped by user — re-run when ready.

Worked example: customer already has Salesforce shared

Input: {WABA_ID}=1558753535400324

Stage 1: skill renders the instructions with the WABA ID visible. Customer opens Business Suite → WhatsApp Accounts → 1558753535400324 → Partners. Sees "Salesforce" in the list.

Stage 2: customer answers y.

Stage 3: emits:

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

Orchestrator continues to service-de-channel-create.

Worked example: customer needs to add the partnership

Same input. Customer opens Business Suite, doesn't see Salesforce in Partners, clicks Add partners → Share account with partner → pastes 10152614792574154 → scrolls down to the "Full control" section → toggles ON "Everything" → Assign. Meta shows "Partnership request sent" or similar. Partnership lands (usually instant; occasionally pending for a few minutes if Meta needs to review).

Customer answers y after confirming Salesforce now shows up.

Orchestrator continues.

Worked example: Business Manager not business-verified

Customer clicks Assign and Meta rejects with "Your business must be verified to assign partners." Customer answers n in our prompt.

Stage 3: emits:

{"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."}

Orchestrator emits a step-annotated failure pointing at this skill; user pursues business verification through Meta separately and re-runs later.