service-de-waba-integrate

WABA を Salesforce にリンクする

このスキルの機能

お客様が「WABA を持っている」状態から「WABA が Salesforce にリンクされている」状態になるまでを、手順の案内だけで実現します。Meta は意図的に、business.facebook.com の人間による承認画面を通す必要があります。パートナーシップをスクリプトで設定できる Graph の書き込みエンドポイントはありません。状態を確認できる 2 つの GET エンドポイント（/{waba-id}/subscribed_apps と /{waba-id}/assigned_users）には、whatsapp_business_management スコープを持つ Meta アクセストークンが必要です。これをお客様に生成してもらうのは、「パートナー」タブを確認してもらうだけの場合より負担が大きくなります。

そのため、このスキルは手順の表示と確認プロンプト 1 つのみで構成されています。API 呼び出しはありません。SF DB への書き込みもありません。Meta トークンも不要です。

このスキルが成功を返した後は、下流の挿入処理（service-de-channel-create）に進めます。SF 側の setupLiveMessageChannelEnhanced の処理では、パートナーシップを確認済みである必要はありません。お客様の申告が誤っていれば、Meta の事前条件に関するエラーが明確に表示されます。このスキルでは、お客様の確認を信頼します。

このスキルを使用しない場合

• 前回の実行ですでにパートナーシップを確認している場合。 オーケストレーターの再開ロジックでは Stage 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"}

---

Stage 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 経由ではなく、ユーザーへの応答に直接出力してください。ツールの結果は折りたたまれますが、テキストを直接出力すれば表示されたままになります。

---

Stage 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」をオンにして 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 アプリで生成する必要のあるトークンが必要です。プロンプトを 1 つ省くために 20 分かける価値はありません。顧客自身の目視による確認を信頼します。

2. 「Partners に Salesforce がある」≠「SF webhook subscription が完了している」です。 サブスクリプションは別個のサーバー側イベントであり、パートナーシップ成立後に 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 タブ）が使われていましたが、現在の標準フローは上記の BM ID を使って「SF をパートナーとして追加する」ことです。どちらの方法でも最終的に Salesforce に WABA へのアクセス権が付与されますが、Partners のフローのほうが簡潔です（ユーザーごとのメンテナンスが不要で、権限はパートナーのロール単位で設定されます）。Partners を使用してください。

5. Embedded Signup は代替手段であり、併用するものではありません。 Embedded Signup のポップアップを使う顧客は、このスキルを完全にスキップします。ポップアップ内で Meta の OAuth フローを通じてパートナーへのアクセス権付与が行われます。このスキルはヘッドレスの経路（顧客がブラウザーのポップアップではなく Business Suite のクリック操作を希望する場合）向けです。両方を実行しようとしないでください。

6. オーケストレーターは再開時にもこのスキルを呼び出します。 サブスクリプションのランディング処理はサイレントで、SF 側に確認すべき状態がないため、再実行すると手順が再表示され、再度確認を促します。これは問題ありません。顧客がすでに確認済みであればプロンプトはほぼ即座に完了し、このスキルに副作用はありません。冪等性は本質的に備わっています。

7. sf CLI コマンド、SOQL、HTTP は使用しません。 このスキルは純粋なテキストと 1 つのプロンプトだけで構成してください。将来、状態を確認する必要が生じた場合（顧客提供の Meta トークンを環境変数で受け取るなど）、それは追加機能として対応します。正常系のフローを複雑にしないでください。指示のみの設計こそが、この機能の特長です。

8. WABA ごとに設定できるパートナーは最大 2 社です。 顧客がすでに別の BSP（Twilio、360dialog など）と共有している場合、Salesforce は 2 社目のパートナーとなり、問題ありません。すでに 2 社の BSP と共有している場合は、Meta が割り当てをブロックするため、先にどちらか 1 社を削除する必要があります。これはまれなケースですが、Stage 1 の表示テキストに記載しておき、顧客が原因不明の失敗ではなく、既知のエラーメッセージを確認できるようにしてください。

9. 必要なのは「Full control / Everything」であり、「Partial access」の切り替え項目だけでは不十分です。 Meta のパートナー共有ダイアログには、2 つのセクションがあります。「Partial access」（個別の切り替え項目：電話番号の表示／管理、メッセージテンプレートの表示／管理、電話番号とメッセージテンプレートの管理、メッセージ）と、「Full control」（「Everything」という単一の切り替え項目）です。Salesforce に Full control / Everything が必要な理由は次のとおりです。

   • ユーザーの割り当て — SF は WABA を運用するため、WABA 上にサービスアカウントをプロビジョニングします。これを許可するのは「Everything」の切り替え項目だけで、「Partial access」の切り替え項目では許可されません。
   • Webhook サブスクリプションの管理 — POST /{waba-id}/subscribed_apps（SF の BSP アプリが受信メッセージを受け取れるようにする処理）には whatsapp_business_management スコープが必要です。このスコープは「Partial access」の切り替え項目ではなく、「Full control」に対応します。
   • クレジットライン／支払い方法の表示 — SF が顧客自身の請求を通じてメッセージを送信できるようにするために必要です。「Everything」の説明（「支払い情報を表示」）にのみ明記されています。

   顧客が「Partial access」だけ（たとえば「電話番号とメッセージテンプレートの管理」だけ）を許可した場合、SF 側ではチャネルを挿入できることがありますが、その後の有効化や送信は権限不足を示す不明瞭な Meta エラーで失敗する可能性があります。「Partial access」は BSP 以外の連携（テンプレートメッセージの送信だけを必要とするマーケティングツールなど）向けであり、BSP 向けではありません。権限を狭めるように表示手順を「最適化」しようとしないでください。目先の節約に見えても、後のフローで分かりにくい失敗を招きます。