WhatsApp Business Platform > Business Management API

概要

ビジネス管理APIを使うと、WhatsApp Businessアカウントやメッセージテンプレートなど、WhatsApp関連のビジネスアセットを作成および管理することができます。このAPIはマーケティングAPI上に構築されており、そのエンドポイントの一部を利用するため、このドキュメントには該当するマーケティングAPIドキュメントへのリンクが含まれている場合があります。

要件

Metaビジネスアカウント。
お使いのMetaビジネスアカウントに関連付けられたWhatsApp Businessアカウント。
お使いのMetaビジネスアカウントに関連付けられたビジネスアプリ。
ビジネス連携システムユーザーアクセストークン、システムユーザーアクセントークン、またはユーザーアクセストークン。
whatsapp_business_managementアクセス許可。
Metaビジネスアカウントをターゲットとするエンドポイントにアプリがアクセスする場合、business_managementアクセス許可が必要になります。
クラウドAPIのエンドポイントにアプリがアクセスする場合、whatsapp_business_messagingアクセス許可が必要になります。

アクセストークン

プラットフォームでは以下のアクセストークンのタイプがサポートされています。使用するタイプは、アプリケーションの利用者によって、またソリューションプロバイダーであるかどうかによって異なります。

ダイレクト開発者である場合、あなたやあなたのビジネスだけがデータにアクセスします。システムユーザーアクセストークンを使用してください。
技術提供者である場合、ビジネス連携システムユーザーアクセストークンを使用してください。
ソリューションパートナーである場合、システムユーザーアクセストークンを使って新しくオンボーディングされた顧客とクレジットラインを共有し、それ以外のすべてに関してはビジネス連携システムユーザーアクセストークンを使用します。

システムユーザーアクセストークン

システムユーザーアクセストークンは、あなた、あなたのビジネスや組織、またはあなたのビジネスや組織に属する人を表します。これらのトークンの主な利点は、期限切れになることがなく、ビジネス内でユーザーのインプットを必要としない自動化サービスを表示できることです。

システムユーザーアクセストークンは、ソリューションパートナーがオンボーディングされた顧客とクレジットラインを共有するために使用できる唯一のトークンタイプです。

システムユーザーアクセストークンを生成するには、まずシステムユーザーを作成する必要があります。ほとんどのエンドポイントは、トークンで特定されたユーザーがクエリ対象のリソースにアクセスできるかどうかをチェックします。ユーザーがリソースにアクセスできない場合、エラーコード200が返され、リクエストが却下されます。

システムユーザーは、社員または管理者のいずれかです。

社員システムユーザー

社員システムユーザーには、当該のMetaビジネスが所有しているまたは共有を受けている個々のWhatsApp Businessアカウントへのアクセス権を付与する必要があります。所有しているWhatsApp Businessアカウントにのみアプリがアクセスする必要がある場合は、社員システムユーザーのアクセス権で十分です。

作成したら、そのシステムユーザーがアクセスする必要がある各WhatsApp Businessアカウントへのフルまたは部分的なアクセス許可を付与する必要があります。

管理者システムユーザー

デフォルトでは、管理者システムユーザーは、あなたやあなたのビジネスが所有している、または共有を受けているすべてのWhatsApp Businessアカウントとアセットにフルアクセスできます。

管理者システムユーザーは、アプリがあなたのビジネスに新しく共有されたWhatsApp Businessアカウントにアクセスする必要がある場合に便利です。社員システムユーザーを使用している場合は、共有を受けた各WhatsApp Businessアカウントへのアクセス許可を手動で付与する必要があります。

WhatsApp Businessアカウントごとに部分的なアクセス許可を付与することによって、管理者システムユーザーのデフォルトアクセスを上書きすることができます。

システムユーザーの作成

システムユーザーを作成する手順は、次のとおりです。

Meta Business Suiteにサインインします。
左上のドロップダウンメニューでビジネスアカウントを見つけ、設定(歯車)アイコンをクリックします。
[ビジネス設定]をクリックします。
[ユーザー] > [システムユーザー]の順に移動します。
[追加]ボタンをクリックして、[管理者]または[社員]システムユーザーを作成します。

システムユーザーアクセストークンの生成

システムユーザーの作成後にシステムユーザーアクセストークンを生成する手順は、次のとおりです。

Meta Business Suiteにサインインします。
左上のドロップダウンメニューでビジネスアカウントを見つけ、設定(歯車)アイコンをクリックします。
[ビジネス設定]をクリックします。
[ユーザー] > [システムユーザー]の順に移動します。
システムユーザーのリストから該当するシステムユーザーを選択します。
[新しいトークンを生成]ボタンをクリックします。
トークンを使用するアプリを選択します。
アプリが正しく機能するために必要とするアクセス許可をすべて選択し、トークンを生成します。

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

ビジネス連携システムユーザーアクセストークンの対象範囲はオンボーディングされた個々の顧客であり、技術提供者やソリューションパートナーが、オンボーディングされた顧客のデータにアクセスする際に使用します。

これらは、顧客のWhatsAppビジネスアカウントでプログラムによる自動アクションを実行するアプリに便利なトークンです。アプリユーザーの入力に頼ることも、今後再認証が必要になることもありません。

ビジネス連携システムユーザーアクセストークンを生成するには、ビジネス向けFacebookログインで設定された埋め込み登録を実装し、顧客がフローを完了したときに返されるコードを交換する必要があります。

これらのトークンと生成方法について詳しくは、埋め込み登録のドキュメントとビジネス連携システムユーザーアクセストークンのドキュメントをご覧ください。

ユーザーアクセストークン

ユーザーアクセストークンはすべてのアプリ開発者が使用できるようサポートされています。しかし、このトークンは往々にして、初めてアプリダッシュボードを使って最初のテストメッセージを送信するときしか利用できません。ただし、アプリを開発中にシステムユーザーアクセストークン(技術提供者またはソリューションプロバイダーである場合、最終的にビジネスシステムユーザーアクセストークンに)切り替わります。ユーザーアクセストークンはすぐに期限切れになり、数時間ごとに新しいものを作成し続ける必要があるためです。

ユーザーアクセストークンを生成する方法はいくつかあります。

[アプリダッシュボード] > [WhatsApp] > [API設定]パネルにアクセスします。このパネルでは、アクセスするたびに必ず新しいユーザーアクセストークンが生成されます。パネルにアクセスすると開発者アカウントにサインインインされるため、トークンは自動的にそのユーザーを対象とします。
グラフAPIエクスプローラを使用します。
Facebookログインを実装します。

リクエストでのトークンの使用

APIリクエストを行うときは、Bearerで始まる認証リクエストヘッダーにトークンを含めてください。例えば、次のようにします。

curl 'https://graph.facebook.com/v18.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \

WhatsApp Businessアカウントのアクセス許可

多くのエンドポイントでは、APIリクエストに含められたトークンのユーザーにも、クエリ対象のWhatsApp Businessアカウント(またはそのアセット)への部分的またはフルアクセス許可が付与されていなければなりません。ユーザーがアクセスできない場合、APIはエラーコード200を返します。

詳細なアクセス許可は、システムユーザーを含めどのユーザーにも設定できます。あるユーザーグループの特定のアセットへのアクセスを制限したい場合は、システムユーザーに詳細なアクセス許可を設定すると便利です。例えば、大規模なビジネスを所有していて、特定の部門にはWhatsApp Businessアカウントのテンプレートとビジネス電話番号のデータへの読み取りアクセスのみを許可したい場合は、その部門のシステムユーザーを作成し、閲覧専用アクセスを設定することができます。

WhatsApp Businessアカウントやそのアセットに対するユーザーアクセスを指定するには、次のようにします。

Meta Business Suiteにサインインします。
左上のドロップダウンメニューでビジネスアカウントを見つけ、設定(歯車)アイコンをクリックします。
[ビジネス設定]をクリックします。
[アカウント] > [WhatsAppアカウント]の順に移動します。
適切なWhatsApp Businessアカウントを選択します。
[WhatsAppアカウントアクセス]タブを選択します。
[+人を追加]ボタンをクリックします。
適切なシステムユーザーを選択し、WhatsApp Businessアカウントに対する適切なアクセスレベルを割り当てます。

エンドポイントのテスト

エンドポイントのテストには、PostmanコレクションかcURLを使うことをおすすめします。グラフAPIエクスプローラツールも使えますが、トークンがクエリー文字列パラメーターとして渡されるため、利用はおすすめしません(代わりに、リクエストヘッダーでトークンを渡してください)。

ビジネスに関する情報を入手する

ビジネスに関する情報を入手するには、GETリクエストをWhatsAppBusinessAccountエンドポイントに送信します。ここで、<WHATSAPP_BUSINESS_ACCOUNT_ID>は、お持ちのWhatsApp BusinessアカウントIDにします。

リクエストの例

curl -i -X GET 'https://graph.facebook.com/v19.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

応答の例

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "timezone_id": "1",
  "message_template_namespace": "05155c78_261e_4b2f_82b3_d7958d4cf75f"
}

ビジネスの特定の情報(名称、メッセージテンプレート、電話番号など)を入手するには、GETリクエストをWhatsAppBusinessAccountエンドポイントに送ります。ここで、<WHATSAPP_BUSINESS_ACCOUNT_ID>にはお持ちのWhatsApp BusinessアカウントIDを、fieldsパラメーターには戻り値を希望する項目のリストを設定します。

リクエストの例

curl -i -X GET 'https://graph.facebook.com/v19.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>?fields=id,name,message_templates,phone_numbers' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

応答の例

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "message_templates": {
    "data": [
      {
        "name": "hello_world",
        "components": [
          {
            "type": "HEADER",
            "format": "TEXT",
            "text": "Hello World"
          },
          {
            "type": "BODY",
            "text": "Welcome and congratulations!! This message demonstrates your ability to send a message notification from WhatsApp Business Platform. Thank you for taking the time to test with us."
          },
          {
            "type": "FOOTER",
            "text": "WhatsApp Business Team"
          }
        ],
        "language": "en_US",
        "status": "APPROVED",
        "category": "ACCOUNT_UPDATE",
        "id": "307191531401674"
      },
      {
        "name": "sample_flight_confirmation",
        "components": [
          {
            "type": "HEADER",
            "format": "DOCUMENT"
          },
          {
            "type": "BODY",
            "text": "Confirmamos tu vuelo a {{1}}-{{2}} para el {{3}}."
          },
          {
            "type": "FOOTER",
            "text": "Este mensaje proviene de un negocio no verificado."
          }
        ],
        "language": "es",
        "status": "APPROVED",
        "category": "TICKET_UPDATE",
      },
      ...

レート制限

アプリからWhatsApp Business管理APIに対してなされるリクエストは、アプリのカウントに含まれます。アプリの呼び出しカウントは、1時間のローリング枠で可能な呼び出しの数です。次のWhatsApp Business管理APIでは、デフォルトで、1アプリあたり、WhatsApp Businessアカウント(WABA)ごとに1時間あたり200回の呼び出しを実施できます。少なくとも1つの電話番号が登録されているアクティブなWABAの場合、1アプリあたり、アクティブなWABAごとに1時間あたり5000件の呼び出しが可能です。

呼び出しのタイプ	エンドポイント
`GET`	`/{whatsapp-business-account-id}`
`GET`、`POST`、`DELETE`	`/{whatsapp-business-account-id}/assigned_users`
`GET`	`/{whatsapp-business-account-id}/phone_numbers`
`GET`、`POST`、`DELETE`	`/{whatsapp-business-account-id}/message_templates`
`GET`、`POST`、`DELETE`	`/{whatsapp-business-account-id}/subscribed_apps`
`GET`	`/{whatsapp-business-account-to-number-current-status-id}`

以下の融資限度額APIの場合、1アプリ当たり、1時間に5000回の呼び出しが可能です。

呼び出しのタイプ	エンドポイント
`GET`	`/{business-id}/extendedcredits`
`POST`	`/{extended-credit-id}/whatsapp_credit_sharing_and_attach`
`GET`と`DELETE`	`/{allocation-config-id}`
`GET`	`/{extended-credit-id}/owning_credit_allocation_configs`

レート制限に達することがないようにするため、Webhooksを使うことによって、メッセージテンプレート、電話番号、WABAのステータスの更新を常に把握しておくことをおすすめします。

現在のレート使用率を知る方法について詳しくは、ヘッダーをご覧湯ください。

詳細情報

Facebook SDK — Facebookログインを使用してユーザーにアクセス許可を求めるには、いずれかのSDKを実装します。
マーケティングAPIビジネスマネージャ – マーケティングAPIビジネスマネージャについての詳細を確認できます。
アプリレビュー – 自社データや他社が所有するデータにアクセスするプロセスの詳細を確認できます。
WhatsApp Businessプラットフォームの設定方法の動画をご覧ください。

次のステップ

ガイド – ほかにWhatsApp Business管理APIでできることについて、こちらで確認できます。
Postmanコレクションを探索する

WhatsApp Businessプラットフォーム | クラウドAPI | オンプレミスAPI | ビジネス管理API