whatsapp-cloud-api

WhatsApp Cloud API - 統合ガイド

対象範囲とスナップショット：例では、現在の Meta の契約ではなく、旧バージョンの Graph API を対象としています。使用前に、公式の Meta ドキュメントと実際のアカウントで、サポート対象バージョン、料金、メッセージ／スループット制限、テンプレートの編集規則、利用資格を確認してください。法務関連の表は例示であり、GDPR／LGPD の普遍的な要件ではありません。送信、テンプレートの削除、アカウントの移行、購入、トンネル、デプロイには、ユーザーが許可したスコープが必要です。正確な宛先と内容、および適用される同意／サービスウィンドウを確認してください。トークン、個人のメッセージ本文、API エラー全文をログに記録しないでください。ボイラープレートはローカルデモ用です。本番環境では、永続キューへの登録後に ACK を返す仕組み、認証済みアカウントのルーティング、冪等性／リプレイ保護、オプトアウト確認、ワーカーが必要です。HMAC だけではリプレイを防止できません。

概要

Meta の WhatsApp Business Cloud API との統合です。メッセージ、HMAC-SHA256 ウェブフック、カスタマーサポートの自動化に対応します。Node.js と Python のボイラープレートを用意しています。

このスキルを使用する場面

• ユーザーが「whatsapp」または関連トピックに言及した場合
• ユーザーが「whatsapp business」または関連トピックに言及した場合
• ユーザーが「api whatsapp」または関連トピックに言及した場合
• ユーザーが「chatbot whatsapp」または関連トピックに言及した場合
• ユーザーが「mensagem whatsapp」または関連トピックに言及した場合
• ユーザーが「template whatsapp」または関連トピックに言及した場合

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

• タスクが WhatsApp Cloud API と無関係な場合
• よりシンプルで、より具体的なツールでリクエストに対応できる場合
• ユーザーが分野の専門知識を必要としない汎用的な支援を求めている場合

仕組み

Meta の公式 Cloud API を使用した、WhatsApp Business のプロフェッショナルな統合を実装するスキルです。Node.js／TypeScript と Python に対応しています。

概要

WhatsApp Cloud API は、WhatsApp Business を通じたメッセージの送受信に使用する Meta の公式 API です。2025 年 10 月以降、サポートされる唯一の選択肢です（On-Premises API は廃止されました）。

参考バージョン： Graph API v21.0（使用前にサポート状況を確認してください） ベース URL： https://graph.facebook.com/v21.0/{phone-number-id}/messages 認証： Bearer Token（本番環境では System User Token）

2026 年の料金（メッセージ単位）：

カテゴリ	費用	課金される場面
Marketing	$0.025-$0.1365	キャンペーン、プロモーション
Utility	$0.004-$0.0456	注文確認、更新情報
Authentication	$0.004-$0.0456	OTP、パスワードのリセット
Service	無料	24 時間のウィンドウ内での返信

前提条件：

• Meta Business Suite アカウント（無料）
• WhatsApp 製品を設定した Meta for Developers のアプリ
• 認証済みの電話番号
• System User Token（永続）

ユーザーが Meta Business アカウントを持っていない場合は、ゼロからのセットアップ手順が記載された完全なガイド references/setup-guide.md を参照してください。

---

決定ツリー

次のステップを判断するには、このツリーを使用してください。

O usuario precisa de setup inicial?
├── SIM → Leia references/setup-guide.md
└── NAO → Qual linguagem?
    ├── Node.js/TypeScript
    └── Python
    → O que quer fazer?
       ├── Enviar mensagens → Secao "Tipos de Mensagem" abaixo
       ├── Receber mensagens → Secao "Webhooks" abaixo
       ├── Automatizar atendimento → Secao "Automacao" abaixo
       ├── WhatsApp Flows / Commerce → Secao "Features Avancados" abaixo
       ├── Gerenciar templates → references/template-management.md
       └── Compliance / limites → Secao "Compliance & Quality" abaixo

すぐに使えるボイラープレートでプロジェクトをゼロから始めるには、次のスクリプトを使用してください。

python scripts/setup_project.py --language nodejs --path ./meu-projeto

## Ou

python scripts/setup_project.py --language python --path ./meu-projeto

---

1. 環境変数を設定する

WHATSAPP_TOKEN=seu_access_token_aqui
PHONE_NUMBER_ID=seu_phone_number_id
WABA_ID=seu_whatsapp_business_account_id
APP_SECRET=seu_app_secret
VERIFY_TOKEN=token_customizado_para_webhook

2. シンプルなテキストメッセージを送信する

Node.js/TypeScript：

import axios from 'axios';

const GRAPH_API = 'https://graph.facebook.com/v21.0';

async function sendText(to: string, message: string) {
  const response = await axios.post(
    `${GRAPH_API}/${process.env.PHONE_NUMBER_ID}/messages`,
    {
      messaging_product: 'whatsapp',
      to,
      type: 'text',
      text: { body: message }
    },
    { headers: { Authorization: `Bearer ${process.env.WHATSAPP_TOKEN}` } }
  );
  return response.data; // { messaging_product, contacts, messages: [{ id }] }
}

Python：

import httpx
import os

GRAPH_API = "https://graph.facebook.com/v21.0"

async def send_text(to: str, message: str) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.post(
            f"{GRAPH_API}/{os.environ['PHONE_NUMBER_ID']}/messages",
            json={
                "messaging_product": "whatsapp",
                "to": to,
                "type": "text",
                "text": {"body": message}
            },
            headers={"Authorization": f"Bearer {os.environ['WHATSAPP_TOKEN']}"}
        )
        response.raise_for_status()
        return response.json()  # {"messaging_product", "contacts", "messages": [{"id"}]}

3. テンプレートメッセージを送信する（24 時間のウィンドウ外）

対応時間のウィンドウ外では、承認済みテンプレートを使用し、該当する同意を得てください。使用前に WhatsApp の承認を受ける必要があります。

{
  "messaging_product": "whatsapp",
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "hello_world",
    "language": { "code": "pt_BR" },
    "components": [
      {
        "type": "body",
        "parameters": [
          { "type": "text", "text": "João" }
        ]
      }
    ]
  }
}

4. 配信を確認する

テストスクリプトを使用して検証してください。

python scripts/send_test_message.py --to 5511999999999 --message "Teste de integracao"

---

メッセージの種類

種類	用途	上限
Text	シンプルなテキストメッセージ	4096 chars
Template	会話の開始／24時間のウィンドウ外	1600 chars body
Image	写真と画像	5MB
Document	PDF、スプレッドシート、ドキュメント	100MB
Video	動画	16MB
Audio	音声メッセージ	16MB
Interactive Button	クイック返信ボタン	Max 3 botoes
Interactive List	セクション別の選択肢を含むメニュー	Max 10 opcoes
Location	位置情報の共有	lat/long
Contact	連絡先の共有	vCard format
Reaction	メッセージに絵文字でリアクション	1 emoji

例 - インタラクティブボタン（Node.js）：

async function sendButtons(to: string, body: string, buttons: Array<{id: string, title: string}>) {
  return axios.post(`${GRAPH_API}/${process.env.PHONE_NUMBER_ID}/messages`, {
    messaging_product: 'whatsapp',
    to,
    type: 'interactive',
    interactive: {
      type: 'button',
      body: { text: body },
      action: {
        buttons: buttons.map(b => ({
          type: 'reply',
          reply: { id: b.id, title: b.title }
        }))
      }
    }
  }, { headers: { Authorization: `Bearer ${process.env.WHATSAPP_TOKEN}` } });
}

// Uso:
await sendButtons('5511999999999', 'Como posso ajudar?', [
  { id: 'suporte', title: 'Suporte' },
  { id: 'vendas', title: 'Vendas' },
  { id: 'info', title: 'Informacoes' }
]);

Node.js と Python でのすべての種類の完全な例については、references/message-types.md をご覧ください。

---

Webhook

Webhook を使用すると、メッセージやステータスの更新をリアルタイムで受信できます。

検証（Get）- 必須

Meta Developers で webhook を設定すると、Meta から検証のために GET リクエストが送信されます。

// Node.js (Express)
app.get('/webhook', (req, res) => {
  const mode = req.query['hub.mode'];
  const token = req.query['hub.verify_token'];
  const challenge = req.query['hub.challenge'];

  if (mode === 'subscribe' && token === process.env.VERIFY_TOKEN) {
    res.status(200).send(challenge);
  } else {
    res.sendStatus(403);
  }
});

受信（Post）- Hmac-Sha256 によるセキュリティ

すべての webhook 通知には、ヘッダー X-Hub-Signature-256 に署名が付与されています。処理する前に、必ず検証してください。

import crypto from 'crypto';

function validateSignature(rawBody: Buffer, signature: string): boolean {
  const expectedSig = crypto
    .createHmac('sha256', process.env.APP_SECRET!)
    .update(rawBody)
    .digest('hex');
  if (!/^sha256=[a-f0-9]{64}$/.test(signature)) return false;
  const expected = Buffer.from(`sha256=${expectedSig}`);
  const received = Buffer.from(signature);
  return expected.length === received.length && crypto.timingSafeEqual(expected, received);
}

重要： タイミング攻撃を防ぐため、crypto.timingSafeEqual（Node.js）または hmac.compare_digest（Python）を使用してください。単純な文字列比較は絶対に使用しないでください。

受信イベント

• messages - クライアントからのメッセージ（テキスト、メディア、ボタン、位置情報）
• statuses - ステータスの更新（sent → delivered → read）
• errors - 配信エラー

要件：

• 有効な SSL 証明書を備えた HTTPS エンドポイント
• 5 秒以内に HTTP 200 で応答すること
• 開発環境：ローカルテストには ngrok を使用してください

Node.js と Python の例を含む完全なセットアップについては、references/webhook-setup.md をご覧ください。

---

インタラクティブなメインメニュー

最初のやり取りで選択肢メニューを作成するには、ボタンまたはリストを使用してください。

## Python - Menu Com Lista Interativa

async def send_main_menu(to: str):
    await send_interactive_list(
        to=to,
        header="Bem-vindo!",
        body="Selecione o que precisa:",
        button_text="Ver opcoes",
        sections=[{
            "title": "Atendimento",
            "rows": [
                {"id": "suporte", "title": "Suporte Tecnico", "description": "Ajuda com problemas"},
                {"id": "vendas", "title": "Vendas", "description": "Conhecer nossos produtos"},
                {"id": "financeiro", "title": "Financeiro", "description": "Boletos e pagamentos"},
            ]
        }]
    )

フローのステートマシン

ステートマシンを使って会話を管理します。各クライアントには現在の状態があり、それによって次のメッセージの処理方法が決まります。

INICIO → MENU_PRINCIPAL → SUPORTE → AGUARDANDO_DETALHES → ESCALACAO_HUMANO
                        → VENDAS → CATALOGO → CHECKOUT
                        → FINANCEIRO → SEGUNDA_VIA_BOLETO

24時間のウィンドウ

• ウィンドウ内（クライアントの最後のメッセージから24時間以内）： あらゆる種類のメッセージを無料で送信できます
• ウィンドウ外： template メッセージのみ送信できます（カテゴリーごとに課金）

AI との統合（Claude Api）

WhatsApp と Claude を組み合わせて、インテリジェントな応答を実現します。

1. webhook 経由でメッセージを受信します
2. 会話のコンテキストとともに Claude API に送信します
3. WhatsApp 経由で応答を返します
4. 人間の担当者へのエスカレーションを利用できるようにしておきます

自動化パターンの完全な例については、references/automation-patterns.md をご覧ください。

---

Whatsapp Flows

WhatsApp 内で利用できる、複数画面のインタラクティブなフォームです。クライアントはアプリを離れずに項目を入力できます。screens、components、actions を含む JSON で定義します。

用途：登録、予約、NPS アンケート、商品選択。

コマースとカタログ

WhatsApp カタログには最大500商品を登録できます。単一商品または複数商品のメッセージを送信し、アプリ内でチェックアウトできます。

Template Management Api

テンプレートをプログラムから作成、一覧表示、削除できます。1アカウントあたり最大6000件の翻訳に対応しています。数分で承認されます。

Whatsapp Channels

無制限の登録者に向けた一方向のブロードキャストです。WhatsApp の「アップデート」タブにあります。

Click-To-Whatsapp Ads

WhatsApp の会話を開くボタン付きの Facebook／Instagram 広告です。結果は変動するため、成果は保証されません。

ステータスの追跡

配信状況を追跡します：pending → server → device → read。ステータス更新は webhook で受信します。

高度な機能の詳細については、references/advanced-features.md をご覧ください。 API を使用したテンプレート管理については、references/template-management.md をご覧ください。

---

必須チェックリスト

• メッセージを送信する前に、明示的なオプトインを取得する
• オプトアウトの仕組みを実装する（キーワード「SAIR」または「STOP」）
• タイムスタンプ、方法、目的を含む同意記録を保存する
• WhatsApp のポリシーに準拠したコンテンツにする（スパムや禁止コンテンツを含めない）
• LGPD/GDPR に準拠する（法的根拠を定め、データ主体の権利に対応する）
• メッセージの頻度を適切に保つ（過剰に送信しない）
• 使用前にテンプレートの承認を得る
• ビジネス認証を完了する（上限引き上げの場合）

品質評価

WhatsApp はメッセージの品質を監視し、評価を付与します。

評価	意味	対応
緑	品質が高く、ブロックが少ない	維持 — 上限引き上げの対象です
黄	品質は平均的で、注意が必要	コンテンツと頻度を見直す
赤	品質が低く、停止のリスクがある	直ちに対応：送信量を減らす

良い兆候： 高い返信率、エンゲージメント、ブロックが少ない 悪い兆候： ブロック、スパム報告、低いエンゲージメント

ティアシステム（メッセージ上限）

2025 年 10 月以降、上限は電話番号ごとではなくビジネスポートフォリオごとに設定されます。

ティア	24 時間あたりの会話数	到達方法
初期	250	新規アカウント／未認証
ティア 1	1,000	自動引き上げ：7 日間、上限の 50% 以上を使用
ティア 2	10,000	自動引き上げ：7 日間、上限の 50% 以上を使用
ティア 3	100,000	自動引き上げ：7 日間、上限の 50% 以上を使用
無制限	無制限	自動引き上げ：7 日間、上限の 50% 以上を使用

2026 年の変更： 2K および 10K のティアは廃止されます。ビジネス認証後、上限は直ちに 100K になります。

コンプライアンスの完全なガイドについては、references/compliance.md をご覧ください。

---

トラブルシューティング

問題	考えられる原因	解決策
401 Unauthorized	トークンの期限切れまたは無効	新しい System User Token を生成する
400 Bad Request	ペイロードの形式が不正	JSON を例と照合して確認する
テンプレートが拒否された	コンテンツがポリシーに違反している	内容を見直し、修正して再提出する
webhook が受信されない	URL が無効、または HTTPS ではない	ngrok（開発環境）または SSL 証明書（本番環境）を使用する
Rate limit exceeded	80 msg/s を超過	リトライ機能付きのキューを実装する
品質評価が低い	ブロックや報告が多い	送信量を減らし、コンテンツを改善する
メッセージが配信されない	電話番号が無効、または WhatsApp 未登録	送信前に電話番号を検証する
電話番号が認証されていない	OTP の手続きが未完了	SMS または通話で認証をやり直す

設定を検証するには：

python scripts/validate_config.py

---

参考資料（必要に応じて参照）

ファイル	参照するタイミング
references/setup-guide.md	初期設定 — Meta アカウントの作成、API の設定
references/message-types.md	すべてのメッセージタイプの完全な例
references/webhook-setup.md	HMAC セキュリティを使用した Webhook の設定
references/automation-patterns.md	チャットボット、キュー、ステートマシン、AI 連携
references/compliance.md	LGPD/GDPR、オプトイン、品質評価、ティアシステム
references/api-reference.md	エンドポイント、エラー、レート制限、2026 年の料金
references/advanced-features.md	Flows、Commerce、Channels、Ads、ステータス追跡
references/template-management.md	API を使用したテンプレートの CRUD

スクリプト

スクリプト	機能
scripts/setup_project.py	ボイラープレートを使用してプロジェクトを作成します（Node.js または Python）
scripts/validate_config.py	認証情報と API への接続を検証します
scripts/send_test_message.py	設定を検証するためのテストメッセージを送信します

ボイラープレート

ディレクトリ	内容
assets/boilerplate/nodejs/	TypeScript/Express の完全なプロジェクト
assets/boilerplate/python/	Python/Flask の完全なプロジェクト
assets/examples/	JSON ペイロードの例（テンプレート、Webhook、Flows）

ベストプラクティス

• プロジェクトと要件について、明確で具体的なコンテキストを提示してください
• 本番コードに適用する前に、すべての提案を確認してください
• 包括的な分析のために、他の補完的なスキルと組み合わせてください

よくある落とし穴

• このスキルの専門領域外のタスクに使用する
• 独自のコンテキストを理解せずに推奨事項を適用する
• 正確な分析に必要なプロジェクトのコンテキストを十分に提示しない

関連スキル

• instagram - 分析を強化する補完的なスキル
• social-orchestrator - 分析を強化する補完的なスキル
• telegram - 分析を強化する補完的なスキル

制限事項

• タスクが上記の説明にある範囲に明確に該当する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認を求めてください。