概要

MetaホスティングによるクラウドAPIを使用することで、中規模ビジネスと大規模ビジネスは、多数の顧客とやり取りすることができます。ビジネスは、このAPIを利用して何千人という顧客をエージェントやボットにリンクさせ、プログラムでも手動でもやり取りできるシステムを構築できます。また、このAPIを、CRMなどの多くのバックエンドシステムやマーケティングプラットフォームと統合することもできます。

HTTPプロトコル

クラウドAPIはグラフAPI上に構築されているので、リクエストはHTTPプロトコルとURLパラメーター、ヘッダー、リクエスト本文の組み合わせで表現されます。以下は、UNIXベースのコマンドラインからクラウドAPIを呼び出す一般的な例です。

curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505555555",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Here'\''s the info you requested! https://www.meta.com/quest/quest-3/"
  }
}'

グラフAPIを使い慣れていない場合は、MetaのグラフAPI関連のドキュメントで基礎を学んでください。グラフAPIとクラウドAPIの主な違いは、一般的に使われるアクセストークンのタイプ、リソースのアクセス許可、リクエスト構文、Webhooks構文です。これらの違いについては、クラウドAPI関連の一連のドキュメントの該当するセクションで説明しています。

リソース

APIを使用する際にインタラクションする主なリソースを紹介します。

ビジネスポートフォリオ

APIを使用するには、ビジネスポートフォリオが必要です。ポートフォリオがない場合は、開始プロセスの一環でポートフォリオの作成が求められます。ビジネスポートフォリオは、WhatsApp Businessアカウント(WABA)とビジネス電話番号のコンテナとして機能します。

ビジネスポートフォリオについて詳しく知りたい方は、ヘルプセンター記事のMeta Business Suiteのビジネスポートフォリオについてをご覧ください。

WhatsApp Businessアカウント

WhatsApp Businessアカウント(WABA)は、WhatsApp Businessプラットフォーム上のビジネスを表しており、主に特定のビジネスに関するメタデータで構成されています。WhatsApp Business電話番号やWhatsAppメッセージテンプレートなど、他のほとんどのWhatsAppリソースはWABAと関連付けられています。

WABAは、Metaのスタートガイドドキュメントの手順に従って作成できます。WABAおよびその制限について詳しく知りたい場合は、WhatsApp Businessアカウントをご覧ください。

WhatsApp Business電話番号

WhatsApp Business電話番号は実際の電話番号を表しており、クラウドAPIで使うために登録すると、WhatsAppユーザーとAPIを介してメッセージを送受信するために使用できます。

ビジネス電話番号は、主に番号自体と運営するビジネスに関するメタデータで構成されています。このメタデータは、ユーザーがビジネス電話番号とやり取りする際に、WhatsAppクライアントに表示されることがあります。

ビジネス電話番号は、Metaスタートガイドドキュメントの手順に従って作成できます。ビジネス電話番号とその用途には制限や制約があります。詳しくは、ビジネス電話番号ドキュメントをご覧ください。

WhatsAppメッセージテンプレート

WhatsAppメッセージテンプレート(以下、テンプレート)は、APIでさまざまなテンプレートコンポーネントを使って構築できる、カスタマイズ可能なテンプレートです。作成すると自動的に審査され、承認されるとテンプレートメッセージに利用できるようになります。

APIを介して送信できるメッセージには、フリーフォームメッセージとテンプレートメッセージという2つの基本的なタイプがあります。この2つのうち、テンプレートメッセージでは承認済みのWhatsAppメッセージテンプレートの使用が必須であるため、最も強く制限されています。しかし、テンプレートは使用する前に審査と承認を受ける必要があるため、テンプレートメッセージは受信者から否定的なフィードバックを受ける可能性が低くなります。否定的なフィードバックを受けると、顧客にメッセージを送る機能全体に悪影響が及ぶ可能性があります。

テンプレートについて詳しくは、テンプレートドキュメントを参照してください。

Webhooks

Webhooksとは、HTTPプロトコルを使ってサーバー上の公開エンドポイントに送信されるJSONペイロードのことです。クラウドAPIでは、WhatsAppユーザーからビジネス電話番号に送られるすべてのメッセージのコンテンツはWebhooksとして送信され、発信メッセージの配信状況のアップデートはすべてWebhooks経由で報告されるので、Webhooksにかなり依存していることになります。

Metaでは、Glitchで複製してテストに使えるWebhookアプリのサンプルをご用意しています。このアプリでは、Webhooksのペイロードがコンソールに直接ダンプされるので、コンテンツを確認できます。最終的には、何らかの時点で、自社のビジネスロジックに従ってWebhooksを要約する独自のエンドポイントを自社サーバー上に構築する必要がある点に留意してください。

Webhooksとその要約方法について詳しくは、Meta Webhooksをご覧ください。また、MetaのWhatsApp Businessアカウント用Webhooksドキュメントも参照してください。

テスト用リソース

スタートガイドドキュメントの手順の初回実行後には、テスト用WABAとテスト用ビジネス電話番号が自動的に作成されます。

テスト用WABAとテスト用電話番号はメッセージ制限をほぼ回避し、支払い方式を登録しなくてもテンプレートメッセージを送信できるので、テストプロセスで役に立ちます。

次の場合には、ビジネスポートフォリオとそのテスト用リソースを削除できます。

アプリに関連付けられたビジネスポートフォリオの管理者である場合
ビジネスポートフォリオに関連付けられたアプリがほかにない場合
ビジネスポートフォリオが他のWABAと関連付けられていない場合
WABAが他のビジネス電話番号と関連付けられていない場合

以下は、ビジネスポートフォリオとそのテスト用リソースを削除する手順です。

[アプリダッシュボード] > [WhatsApp] > [設定]パネルにアクセスします。
[テストアカウント]セクションを見つけます。
[削除]ボタンをクリックします。

認証と承認

アクセストークン

APIでは、次の3種類のトークンを使用できます。

システムユーザーアクセストークン
ビジネス連携システムユーザーアクセストークン
ユーザーアクセストークン

使用するトークンのタイプを判断する際には、アクセストークンを参考にしてください。トークンは、クエリ文字列パラメーターではなく、リクエストヘッダー経由で渡す必要がある点にご注意ください。

アクセス許可

APIは、次のグラフAPIのアクセス許可に依存しています。アプリが必要とするアクセス許可の正確な組み合わせは、アプリがどのエンドポイントにアクセスするかによって異なります。

business_management — ビジネスポートフォリオとインタラクションする場合に必要。
whatsapp_business_management — WABAとその分析、またはそのテンプレートやビジネス電話番号とインタラクションする場合に必要。
whatsapp_business_messaging — WhatsAppユーザーとのメッセージのやり取りをする場合に必要。

これらのアクセス許可は通常、Meta Business Suiteでアクセストークンを生成する際に付与されます。アクセストークンドキュメントのトークン生成セクションをご覧ください。

バージョン管理

バージョン管理は、グラフAPIのバージョン管理プロトコルを使用します。つまり、すべてのエンドポイントリクエストにバージョン番号を含めることができ、各バージョンは約2年間の利用期間が過ぎると廃止され呼び出せなくなります。

スループット

登録されたビジネスの電話番号それぞれに対して、クラウドAPIはデフォルトでは最大80メッセージ毎秒(mps)をサポートし、自動アップグレードによって最大1,000 mpsまでサポートします。

スループットには、受信メッセージと送信メッセージ、そしてすべてのメッセージタイプが含まれます。ビジネスの電話番号には、スループットに関わらず、WhatsApp Businessアカウントのビジネスユースケースのレート制限およびテンプレートメッセージの制限が課されます。

現在のスループットレベルで許可されている以上のメッセージを送信しようとすると、許可されるレベル内に再び戻るまで、APIはエラーコード 130429を返します。また、スループットレベルは、さまざまなWhatsAppユーザーの電話番号を含むメッセージキャンペーンを対象としています。同じWhatsAppユーザー番号に対してあまりにも多くのメッセージを送信しようとすると、ペアレート制限エラーが発生する可能性があります。

より高いスループット

Metaが設定した利用資格を満たしている場合、追加負担なしで自動的にビジネス電話番号を1,000 mpsにアップグレードします。より高いスループットで、追加料金が発生したり価格に影響したりすることはありません。

アップグレードプロセス自体は最大で1分かかります。この間、Metaのプラットフォームでその番号を使用することはできなくなります。APIリクエストで使用すると、APIはエラーコード 131057を返します。ビジネスの電話番号が一度アップグレードされると、それ以降のスループットの増加は、ダウンタイムなしで自動的にアップグレードされるようになります。

利用資格

ビジネス電話番号は、連続する24時間に無制限のユニークカスタマーと会話を始められなければなりません。
クラウドAPIで使用できるように、ビジネスの電話番号は登録されていなければなりません。番号がオンプレミスAPIで使用するために登録されている場合は、最初にその番号をクラウドAPIに移行する必要があります。
ビジネスの電話番号は、Medium以上の品質評価を受けている必要があります。

Webhooks

使用するWebhooksサーバーは、送信メッセージのキャパシティの3倍と、予想される受信メッセージトラフィックのキャパシティ(1倍)に耐えられる必要があります。例えば、送信が1,000mpsで予想される返信率が30%である場合、サーバーは最大3000のメッセージステータスWebhooksと、300の受信メッセージWebhooksを処理できなければなりません。

複数のWebhooks配信が同時に行われるため、次の遅延標準で同時リクエストを処理できるよう、Webhooksサーバーを設定して負荷テストするようおすすめします。

遅延の平均が250ミリ秒(ms)を超えない。
1秒を超える遅延は1%未満。

失敗したWebhooksは、指数バックオフを使って、最大7日間再配信が試行されます。

メディアメッセージ

より高スループットをフルに活用するには、自社のサーバーでアセットをホスティングしてメディアアセットURLを使うのではなく、Metaのサーバーにメディアアセットをアップロードし、返されるメディアIDをメディアメッセージで使うことをおすすめします。自社のサーバーでアセットをホスティングすることを希望する(または必要とする)場合、メディアキャッシュを使うことをおすすめします。

スループットレベルの取得

WhatsApp Business電話番号エンドポイントを使って、電話番号の現在のスループットレベルを取得します。

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

移行

オンプレミスAPIからクラウドAPIへの複数のシャードを実行しているマルチコネクトがあるビジネス電話番号の移行を行う場合、自動的にアップグレードされ、スループットがさらに高くなります。

レート制限

WhatsApp BusinessマネジメントAPIのレート制限をご覧ください。

こうしたレート制限に加えて、テンプレートメッセージやビジネス電話番号のテストなど、個々のリソースにも次のような細かな制限があります。

テストメッセージレート制限: 認証待ちのWABAに適用。
品質評価とメッセージ制限: 認証済みのWABAに適用。
容量レート制限: 全アカウントに適用。
ビジネス電話レート制限: 全アカウントに適用され、ビジネス電話番号ごとのスループットを制限。

利用できる指標

クラウドAPIユーザーは、送信メッセージ数や配信メッセージ数などの指標を見ることができます。詳しくは、アカウントの指標の取得をご覧ください。

スケール調整

Metaのインフラストラクチャ内でクラウドAPIは、レート制限(メッセージ量とWABAの数)内でワークロードを処理するため自動的にスケーリングされて調整されます。

データのプライバシーおよびセキュリティ

詳しくは、プライバシーとセキュリティの概要をご覧ください。

暗号化

クラウドAPIを使うことにより、すべてのWhatsAppメッセージは引き続きシグナルプロトコル暗号化により保護されます。それにより、メッセージはデバイスを離れる前にセキュリティ確保されます。つまり、WABAとやり取りするメッセージは、各ビジネスが選択する送信先にセキュリティ保護された状態で送信されます。

クラウドAPIは、業界標準の暗号化技術を使って、伝送時と保管時のデータを保護しています。APIは、メッセージの送信にグラフAPI、イベントの受信にWebhooksを使っており、そのいずれもTLSによって保護されている業界標準のHTTPSを通じて行われます。詳しくは、暗号化の概要に関するMetaのホワイトペーパーをご覧ください。

詳しくは、暗号化概要に関するホワイトペーパーをご覧ください。

ペアレート制限

ビジネス電話番号から同じWhatsAppユーザー電話番号に送信するメッセージ数には、6秒間に1メッセージ(0.17メッセージ/秒)までという制限があります。これは、ほぼ1分あたり10メッセージ、または1時間あたり600メッセージに相当します。この上限を超えると、再度上限を下回るようになるまで、APIからエラーコード131056が返されます。

必要なら、6秒間に45通のメッセージをバースト送信することができます。バースト送信する場合、基本的にペアレート制限に反して前借りすることになるため、その後、同じ数の「非バースト」メッセージをユーザーに送るのに通常ならかかるはずの時間が経過するまで、同じユーザーにメッセージを送信することはできません。例えば、ユーザーに「非バースト」メッセージを20件送るには2分近くかかるので、20通のバーストメッセージを送ると、ユーザーに別のメッセージを送れるようになるまで2分近く待たなければなりません。

バーストメッセージ後の待ち時間の計算処理を回避するため、バースト送信後にメッセージ送信リクエストが失敗した場合は、まずX = 0として4^X秒後に再試行し、リクエストが成功するまで、失敗するごとにXを1ずつ増やしていくことをおすすめします。

ツール

WhatsAppマネージャ

WhatsAppマネージャは、WABA、ビジネス電話番号、テンプレートなどのWhatsAppのリソースを手動で管理するためにMetaから提供されているウェブアプリです。これを利用すれば、それらのリソースに関するインサイトや品質評価、あるいは制限について知ることができます。WhatsAppマネージャが提供する機能の大半は、少数の例外を除き、APIでも利用可能です。

WhatsAppマネージャには、以下の複数の方法でアクセスできます。どちらの方法も、スタートガイドドキュメントで示されている手順を実行済みであることを前提としています。

Meta Business Suiteを利用する場合

Meta Business Suiteにログインします。
ビジネスポートフォリオが複数ある場合は、左側のドロップダウンメニューを使って、WhatsAppマネージャに読み込ませたいWABAを所有しているアカウントかそのWABAにアクセスできるアカウントを選択します。
左側のメニューで、[アカウント] > [WhatsAppアカウント]に移動します。
WABAを選択します。
[サマリ]タブで、[WhatsAppマネージャ]ボタンをクリックします。

アプリダッシュボードを利用する場合

[マイアプリ]に移動します。
WhatsAppマネージャに読み込ませたいWABAに関連付けられているアプリを選択します。
左側のメニューで、[WhatsApp] > [クイックスタート]に移動します。
[WhatsApp Business]セクションの[アカウント情報]タイルをクリックします。

URLを利用する場合

以下のURLから[WhatsAppマネージャの概要]に直接移動できます。そこには、所定のビジネスポートフォリオが所有する(または共有を受けている) WABAがすべて表示されます。

https://business.facebook.com/wa/manage/home/

デフォルトで、この概要に、直近で作成したWABA、または直近でアクセス権が付与されたWABAが読み込まれます。また、左側のドロップダウンメニューを使ってアクセスしたいWABAが入っているビジネスポートフォリオを選択することもできます。しかし、そうすると概要から離れてしまうため、左側のメニューを使って[アカウント] > [WhatsAppアカウント] > (対象のWABAを選択) > [設定] > [WhatsAppマネージャ] (ボタン)と移動する必要があります。

あるいは、ビジネスポートフォリオが複数ある場合は、次のようにアカウントのIDをURLの末尾に付加して、ブックマークとして登録すると、簡単にアクセスできるようになります。

https://business.facebook.com/wa/manage/home/?business_id=<META_BUSINESS_ACCOUNT_ID>

Postman

WhatsApp Businessプラットフォームワークスペースには、よくある問い合わせを収めたクラウドAPI Postmanコレクションが用意されています。

WhatsApp Businessプラットフォーム | クラウドAPI | Business管理API