メインコンテンツまでスキップ

📱 WhatsApp Cloud API

WhatsApp は Meta の Cloud API を通じて接続されます — これは公式の無料ティアで利用可能な API で、自分のサーバーから WhatsApp メッセージの送受信ができます。サードパーティの BSP（ビジネスソリューションプロバイダー）は不要です。

前提条件​

  1. developers.facebook.com での Meta 開発者アカウント
  2. Meta Business アカウント（Business Manager とも呼ばれます）
  3. WhatsApp 用の電話番号（個人の WhatsApp に登録されていないもの。SIM、仮想番号、固定電話が使用可能）

セットアップ手順​

1. Meta アプリを作成​

  1. developers.facebook.com/apps にアクセス
  2. Create App をクリック
  3. Business タイプを選択
  4. 名前を入力し、Business アカウントを接続

2. WhatsApp プロダクトを追加​

  1. アプリのダッシュボードで Add Products to Your App までスクロール
  2. WhatsApp の Set Up をクリック
  3. Business アカウントを選択

3. 認証情報を取得​

アプリダッシュボードで WhatsApp → API Setup に移動：

認証情報場所
Phone Number ID"From" セクションに記載 — 123456789012345 のような数値 ID
Access Tokenこのページに表示される一時トークン。本番環境では、System Users 経由で永続トークンを生成してください。
App Secretアプリダッシュボード → Settings → Basic → App Secret
Verify Token自分で決める文字列 — 任意のランダム文字列、例：my_secret_verify_token_2024

4. PulseHub でチャネルを追加​

  1. チャネル → チャネルを追加 に移動
  2. WhatsApp を選択
  3. 4 つのフィールドをすべて入力
  4. チャネルを保存 をクリック
  5. チャネルカードに表示された Webhook URL をコピー

5. Meta で Webhook を設定​

  1. Meta アプリで WhatsApp → Configuration に移動
  2. Webhook セクションの横の Edit をクリック
  3. Callback URL： PulseHub の webhook URL を貼り付け
  4. Verify Token： PulseHub に設定したのと同じ文字列を入力
  5. Verify and Save をクリック

Meta が webhook URL に ?hub.mode=subscribe&hub.verify_token=...&hub.challenge=... 付きの GET リクエストを送信します。PulseHub がトークンを検証し、challenge を返します。

  1. Webhook Fields で messages をサブスクライブ

6. テスト​

ビジネス番号に WhatsApp メッセージを送信します。数秒以内に PulseHub の受信トレイに新しい会話として表示されるはずです。

署名検証​

Meta はすべての webhook に X-Hub-Signature-256 ヘッダーを含めます：

X-Hub-Signature-256: sha256=abc123...

PulseHub は App Secret を使用した HMAC-SHA256 で検証します。検証に失敗した場合、webhook は 401 Signature mismatch を返します。

メッセージ送信​

エージェントが受信トレイから返信を送信すると、PulseHub は WhatsApp Cloud API を呼び出します：

POST https://graph.facebook.com/v18.0/{phone_number_id}/messages
Authorization: Bearer {access_token}
{
  "messaging_product": "whatsapp",
  "to": "{recipient_phone}",
  "type": "text",
  "text": {"body": "返信内容をここに"}
}

本番環境へのアクセス​

デフォルトの Meta アプリは Development モードです — テスト番号として追加された番号にのみメッセージを送信できます。本番環境に移行するには：

  1. Meta Business Manager でビジネス認証を完了
  2. WhatsApp のユースケースを Meta のレビューに提出
  3. 承認されると、すべての WhatsApp ユーザーにメッセージを送信できるようになります

よくある問題​

症状考えられる原因
webhook セットアップ中に検証が失敗PulseHub の verify_token が Meta に入力したものと一致しない
ログに署名不一致エラーapp_secret が間違っている — App Settings → Basic からコピーし、API Setup からはコピーしない
メッセージが届かないMeta ダッシュボードで webhook フィールド messages がサブスクライブされていない
送信時に Invalid phone number番号形式は + なしの E.164 である必要がある（例：15551234567）
Development モードアプリエラーdev モードでは認証済みテスト番号のみがメッセージを受信可能