ハンドオーバープロトコル

Messengerプラットフォームのハンドオーバープロトコルを使えば、スレッドのコントロールをアプリ間で移譲して、複数のFacebookアプリがスレッドに参加できるようになります。この機能をさまざまな方法で使用して、Messengerサービスを充実させることができます。例えば、このプロトコルでは、自動応答を処理するボットを開発するFacebookアプリと、ライブエージェントを使ってカスタマーサービスを行う別のFacebookアプリを、1つのページで同時に使用できます。

デフォルトでは、すべてのメッセージがプライマリ受信者アプリに送信されます。スレッドのコントロールが別のアプリに渡されると、Messengerプラットフォームはスレッドのメッセージを代わりにそのアプリに送信します。一度に1つのアプリだけがスレッドをコントロールできます。スレッドのコントロールを持たないすべてのアプリは、standby Webhookイベントをフォローすることによって、引き続きスレッドをリッスンできます。

ボットの動作を予期せず中断してしまわないよう、いずれかのアプリがハンドオーバープロトコルを使ってメッセージに応答する場合があります。

すべてのAPI呼び出しとリクエストプロパティのリストについては、「Handover Protocol API Reference (ハンドオーバープロトコルのAPIリファレンス)」をご覧ください。

内容

要件

ハンドオーバープロトコルを使用するには、ページ設定で、プライマリ受信者の役割にはアプリを1つのみ割り当て、セカンダリ受信者の役割にアプリを少なくとも1つ割り当てる必要があります。

ハンドオーバープロトコルの使用

ハンドオーバープロトコルについて理解を深めるために、以下の例に従ってプロトコルのしくみを説明します。

  1. ページでアプリをフォローする: アプリ設定の[Messenger]セクションで、ページのWebhookイベントを受け取るように2つのFacebookアプリをフォローします。

  2. ハンドオーバープロトコルを有効にする: [ページ設定] > [Messengerプラットフォーム]で、1つのFacebookアプリにプライマリ受信者の役割、別のアプリにセカンダリ受信者の役割を割り当てます。それぞれのアプリには、プライマリ受信者であるかセカンダリ受信者であるかを通知するapp_rolesプロパティを含むmessaging_handovers Webhookイベントが送信されます。通常、プライマリ受信者は、ほとんどの受信メッセージに自動的に応答できるボットになり、セカンダリ受信者は、ライブエージェントとのチャットに転送したり、特定のリクエストタイプを処理するための専用アプリになります。

  3. Webhookイベントをフォローする: ページのmessagesstandbyのWebhookイベントを受け取るアプリをそれぞれフォローします。

  4. メッセージを送信する: ページにメッセージを送信します。Webhookで受信イベントを記録する場合は、プライマリ受信者アプリが受信したmessagesイベントと、セカンダリ受信者が受信したstandbyイベントを確認する必要があります。デフォルトでは、利用者がボットとやり取りを開始すると、Primary Receiverアプリがスレッドのコントロールを持ち、受信メッセージの処理や応答を行ったり、別のアプリにコントロールを渡したりする役割を担います。

  5. スレッドコントロールを受け渡す: スレッドの中で、利用者がライブエージェントとのやり取りなどを希望することがあります。これを処理するために、プライマリ受信者からセカンダリ受信者へスレッドのコントロールを渡します。セカンダリ受信者には、現在スレッドをコントロールしていることを知らせるmessaging_handovers Webhookイベントが送信されます。

  6. メッセージを送信する: セカンダリ受信者がスレッドのコントロールを持つとmessagesイベントを受信し、プライマリ受信者はstandbyイベントを受信します。

  7. スレッドコントロールを取得するPrimary ReceiverアプリからテイクスレッドコントロールAPIを呼び出して、スレッドコントロールをプライマリ受信者に戻します。スレッドコントロールを取得できるのは、プライマリ受信者だけです。

  8. メッセージを送信する: Primary Receiverアプリがスレッドコントロールを持つとmessagesイベントを受信し、セカンダリ受信者はstandbyイベントを受信します。

アプリの役割ごとに許可されたアクション

アプリが開始できるハンドオーバープロトコルのアクションは、そのアプリの役割によって異なります。以下は、役割別の許可されたアクションの概要です。各ハンドオーバープロトコルのアクションの詳細情報と使用方法については、以下をご覧ください。

ハンドオーバープロトコルの有効化(アプリの役割)

ハンドオーバープロトコルをアクティブにするには、ページでPrimary Receiverの役割にはアプリを1つのみ割り当て、Secondary Receiverの役割にアプリを少なくとも1つ割り当てる必要があります。 デフォルトでは、Primary Receiverアプリに利用者からの受信メッセージを処理するスレッドコントロールがあります。

詳しくはこちら→

スレッドコントロールの受け渡し

パススレッドコントロールAPIは、アプリ間でスレッドのコントロールを渡す際に使用します。呼び出し元のアプリは、APIリクエストとともに任意のメタデータを渡すことができます。スレッドのコントロールをアプリに渡したら、pass_thread_control webhookイベントが任意のメタデータとともにこのアプリに送られます。

Primary ReceiverアプリとSecondary Receiverアプリの両方が、このAPIを使ってスレッドコントロールを渡すことができます。

また、スレッドコントロールをページの受信箱に直接渡すことで、ボットでライブチャットを有効にすることもできます。

詳しくはこちら→

スレッドコントロールの取得

プライマリ受信者のみ

スレッドコントロールを取得できるのは、プライマリ受信者アプリの役割を割り当てられたFacebookアプリのみです。

テイクスレッドコントロールAPIでは、Secondary Receiverの応答が遅い、または応答がない場合は、Primary ReceiverアプリがSecondary Receiverアプリからメッセージスレッドのコントロールを取り戻すことができます。

このAPIを呼び出すことができるのは、Primary Receiverアプリのみです。

詳しくはこちら→

スレッドコントロールのリクエスト

リクエストスレッドコントロールAPIを使用すると、セカンダリ受信者アプリからプライマリ受信者にチャットのコントロールを要求できます。それに対し、プライマリ受信者は必要に応じてチャットのコントロールを取得し、リクエストを送信したセカンダリ受信者にコントロールを渡すことができます。また、リクエストに任意のメタデータ文字列を追加して送信できます。

リクエストはプライマリ受信者によって無視される場合もあります。

詳しくはこちら→

ページの受信箱を使用したライブチャットの有効化

あらゆるメッセージに応答できるボットを開発することは非常に困難です。そのため多くの場合、実在の人物にスレッドを転送できると望ましいです。

これを実現するため、ハンドオーバープロトコルを使用してスレッドのコントロールをページの受信箱に渡すことで、必要に応じてメッセージに手動で応答することができます。これは、ボットがメッセージに応答できないか、またはボットがメッセージへの応答方法を理解できない場合に対応する、理想的なフォールバックです。

詳しくはこちら→

セカンダリ受信者のリストの取得

プライマリ受信者のみ

セカンダリ受信者のリストを取得できるのは、プライマリ受信者アプリの役割を割り当てられたFacebookアプリのみです。

ページに対するセカンダリ受信者の役割があるアプリのリストをプログラムで取得するには、プライマリ受信者アプリのページトークンを使用して、GETリクエストをMessengerプラットフォームに送信します。

curl -X GET "https://graph.facebook.com/v2.6/me/secondary_receivers?fields=id,name&access_token=<PAGE_ACCESS_TOKEN>"

Messengerプラットフォームは、ページに対するセカンダリ受信者の役割があるアプリのリストで応答を返します。

{
  "data":[
    {
      "id":"12345678910",
      "name":"David's Composer"
    },
    {
      "id":"23456789101",
      "name":"Messenger Rocks"
    }
  ]
}

すべてのAPIの詳細とリクエストプロパティについては、「Secondary Receivers List API Reference (セカンダリ受信者リストのAPIリファレンス)」をご覧ください。

Webhookイベント

ハンドオーバープロトコルの使用を管理し、Facebookアプリ間でやり取りされるスレッドのコントロールを追跡するために、Messengerプラットフォームには、次の特殊なWebhookイベントセットが用意されています。

messaging_handovers

messaging_handovers 次のいずれかのハンドオーバープロトコルのアクションがFacebookアプリで実行されると、そのアプリに関連付けられたWebhookにWebhookイベントが送信されます。

  • スレッドコントロールがアプリに渡された
  • スレッドコントロールがアプリから取得された
  • アプリの役割が変更された

詳細とイベントプロパティについては、messaging_handovers Webhookイベントのリファレンスをご覧ください。

standby

ページでハンドオーバープロトコルが設定された場合、その時点でスレッドコントロールのないアプリは任意で別の「standby」チャネルをフォローして、受信メッセージをリッスンできます。standbyチャネルの実装は、アプリがスレッドのすべての内容を追跡し、コントロールがアプリに渡された場合にその後の対応を進めやすくするため重要です。

このWebhookイベントによって影響を受けるのは、messagesmessage_readsmessage_deliveriesのみです。

詳細とイベントプロパティについては、standby Webhookイベントのリファレンスをご覧ください。