whatsapp-cloud-api

WhatsApp Cloud API

使用する場面

以下の場合にこのスキルを有効にします。

• WhatsApp メッセージ機能を構築または変更するとき
• メッセージ（テキスト、メディア、テンプレート、インタラクティブ）を送信するとき
• WhatsApp からの受信 Webhook を処理するとき
• テンプレートメッセージや会話ウィンドウを扱うとき
• 電話番号の形式（E.164）を処理するとき
• WhatsApp API のエラーやステータス更新をデバッグするとき
• メッセージのステータス追跡（送信済み、配信済み、既読）を実装するとき
• WhatsApp Business App と Cloud API の両方で番号を運用するとき（共存）

クイックリファレンス

項目	値
ベース URL	https://graph.facebook.com/v21.0
メッセージ送信	POST /{phone-number-id}/messages
メディアのアップロード	POST /{phone-number-id}/media
認証	Authorization: Bearer {access-token}
必須フィールド	"messaging_product": "whatsapp"
電話番号の形式	E.164：+{country}{number}（例：+18091234567）
レート制限	80 メッセージ／秒（Cloud API）

コア API — メッセージの送信

すべてのメッセージは単一のエンドポイントを使用します。

POST https://graph.facebook.com/v21.0/{phone-number-id}/messages
Authorization: Bearer {access-token}
Content-Type: application/json

レスポンス：

{
  "messaging_product": "whatsapp",
  "contacts": [{ "input": "+16505555555", "wa_id": "16505555555" }],
  "messages": [{ "id": "wamid.HBgL..." }]
}

メッセージの種類

種類	type フィールド	詳細
テキスト	text	プレーンテキスト、最大 4096 文字、URL プレビューに対応
画像	image	JPEG/PNG、最大 5MB、キャプションは任意
動画	video	MP4、最大 16MB、キャプションは任意
音声	audio	AAC/MP3/OGG、最大 16MB
ドキュメント	document	任意の形式、最大 100MB、ファイル名は任意
スタンプ	sticker	WebP、静止画 100KB／アニメーション 500KB
位置情報	location	緯度、経度、名前、住所
連絡先	contacts	構造化された連絡先カード
リアクション	reaction	メッセージへの絵文字リアクション
インタラクティブ	interactive	ボタン、リスト、商品
テンプレート	template	事前承認済みのメッセージテンプレート

仕様とコード例の詳細は、references/MESSAGING.md を参照してください。

Webhook

サーバーは、受信メッセージとステータス更新を通知する POST リクエストを受け取ります。

受信メッセージの構造：

{
  "object": "whatsapp_business_account",
  "entry": [{
    "changes": [{
      "value": {
        "messaging_product": "whatsapp",
        "metadata": { "phone_number_id": "ID", "display_phone_number": "NUM" },
        "contacts": [{ "profile": { "name": "John" }, "wa_id": "16315551234" }],
        "messages": [{
          "from": "16315551234",
          "id": "wamid.ABC...",
          "timestamp": "1683229471",
          "type": "text",
          "text": { "body": "Hello" }
        }]
      },
      "field": "messages"
    }]
  }]
}

ステータス更新の種類： sent → delivered → read | failed

Webhook の検証、ペイロードの解析、すべてのステータスの種類については、references/WEBHOOKS.md を参照してください。

会話ウィンドウ

• 顧客からメッセージが届くと、24 時間のサービスウィンドウが開きます
• ウィンドウ内：任意の種類のメッセージを自由に送信できます（サービスメッセージは無料です）
• ウィンドウ外：テンプレートメッセージのみ送信できます（メッセージごとに課金されます）
• 会話を「閉じる」API エンドポイントはありません。ウィンドウは自動的に期限切れになります
• テンプレートメッセージは、カテゴリ（マーケティング、ユーティリティ、認証）ごとに独自の 24 時間ウィンドウを開きます

ライフサイクル、料金、カテゴリのルールの詳細は、references/CONVERSATIONS.md を参照してください。

共存

1 つの番号をWhatsApp Business App と Cloud API で同時に運用できます。事業者はアプリでのチャットを続けながら、API 経由の連携も行えます。

• 標準の登録ではなく、カスタマイズされた Embedded Signup フロー（featureType: "whatsapp_business_app_onboarding"）でオンボーディングします
• オンボーディング時に、過去のメッセージ（history、最大 180 日分）と連絡先（smb_app_state_sync）が一度だけ同期されます
• 事業者がアプリから送信したメッセージは、smb_message_echoes 経由で Webhook にミラーリングされます
• アプリから送信したメッセージは無料です。共存する番号の上限は 20 msg/sec です
• チャット履歴は保持されます。テンプレートメッセージと 24 時間ウィンドウも引き続き適用されます

オンボーディング、同期、ステータス確認、Webhook ペイロードについては、references/COEXISTENCE.md を参照してください。

よくあるパターン

テキストメッセージを送信する

{
  "messaging_product": "whatsapp",
  "to": "+18091234567",
  "type": "text",
  "text": { "body": "Hello! How can we help you?" }
}

テンプレートメッセージを送信する

{
  "messaging_product": "whatsapp",
  "to": "+18091234567",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": { "code": "en_US" }
  }
}

メッセージを既読にする

{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "wamid.HBgL..."
}

エラー処理

コード	エラー	対応
131030	WhatsApp に登録されていない宛先	送信前に番号を検証します
131047	再エンゲージメントが必要です	まずテンプレートメッセージを送信します
131050	ユーザーがマーケティングメッセージを停止しました	オプトアウトを尊重し、サービス／ユーティリティメッセージのみ送信します
131056	ペアのレート制限に達しました	送信速度を落とし、バックオフを実装します
130429	レート制限を超過しました	メッセージをキューに入れ、最大 80 件／秒にします

エラーの全リファレンスと再試行の戦略については、references/ERROR-CODES.md を参照してください。

ベストプラクティス

1. 常に E.164 形式の電話番号を使用します — +{country}{number}。スペースやハイフンは使用しません
2. Webhook を検証します — GET チャレンジに hub.challenge の値で応答します
3. Webhook POST にはすぐに 200 を返します — 処理は非同期で行います
4. wamid ID を保存します — 返信、リアクション、開封確認に必要です
5. 24 時間のウィンドウが終了した後に再エンゲージするには、テンプレートメッセージを使用します
6. 冪等性に対応します — Webhook は同じイベントを複数回配信する場合があります
7. wa_id と入力値を確認します — API は電話番号を正規化します。wa_id が正規の値です
8. レート制限に注意します — Cloud API は毎秒 80 件です。キューとバックオフを実装します

リファレンス

• メッセージング — すべてのメッセージタイプ
• Webhook — セットアップとペイロード
• テンプレート — 管理と送信
• 会話 — ウィンドウのライフサイクルと料金
• 共存 — 1 つの番号での Business App と Cloud API の利用
• メディア — アップロード、ダウンロード、形式
• インタラクティブ — ボタン、リスト、商品
• 電話番号 — E.164、ID、認証
• エラーコード — よくあるエラーと再試行