Oracle Cloud Infrastructureドキュメント

Facebook Messenger

Facebook Messengerでチャネルを構成するには、次の手順を実行する必要があります:
  • Facebook開発者アカウント

  • Facebookページ

  • Facebookアプリケーション

  • ページ・アクセス・トークン

  • アプリケーション・シークレットID

  • webフックURL

  • 検証トークン

Facebook Messengerでデジタル・アシスタント(またはスタンドアロン・スキル)を実行するには、まず、FacebookページとFacebookアプリケーションを設定する必要があります。 これについては、「Facebook Messaging Platformのドキュメント」で詳しく調べることができます。

ナット・シェルでは、どのように動作するかを説明します。 Facebookページには、デジタル・アシスタントがホストされます。 ユーザーは、デスクトップ・ブラウザでチャット・ウィンドウを使用する際に、このページでデジタル・アシスタントとチャットを行います。 モバイル・デバイスを使用する場合、ユーザーは、Facebook Messenger自体を使用して、デジタル・アシスタントと直接対話します。 このシナリオでは、Facebookアプリケーションを使用して、デジタル・アシスタントで、Facebook Messengerによって処理されるメッセージを取得できます。

Facebook Messengerチャネルを作成するには、Oracle Digital AssistantとFacebook Messengerの両方によって生成されるアーティファクトが必要です。

Oracle Digital Assistantから、次のことが必要になります:

  • デジタル・アシスタントをFacebook Messengerに接続するwebフックURL
  • Facebook Messengerがデジタル・アシスタントを識別できるようにする検証トークン

Facebook Messengerから、次が必要です:

  • ページ・アクセス・トークン
  • アプリケーション秘密ID

Digital AssistantとFacebook Messengerの間でこれらのアーティファクトを転送する必要があるため、チャネルの構成時にこれらの2つのプラットフォームを切り替える必要があります。

ステップ1: Facebook Messengerの設定

Facebook Messengerでアプリケーション・シークレットとページ・アクセス・トークンを生成して、オフにします。

  1. Facebook開発者のアカウントにログインします。

  2. ボットをホストするFacebookページを作成します。 ページに追加した説明、イメージおよびカバー・ページにより、ユーザーにボットが示されます。

  3. 次に、このページにリンクするFacebookアプリケーションを作成します。 これはMessengerアプリケーションであるため、Messenger用のアプリケーションを選択してアプリIDの作成をクリックします。
    setup_fbapp.pngの説明が続きます
    「図setup_fbapp.pngの説明」

    このダイアログでMessenger用のアプリケーションオプションを選択していない場合(たとえば、テスト・アプリケーションを作成している場合)、左側のナビゲーション・バーの製品の追加をクリックして、製品の設定ページからMessengerを選択し、スタート・ガイドをクリックします。
    add_product.pngの説明が続きます
    「図add_product.pngの説明」

  4. Facebookアプリケーションのダッシュボード・ページで、アプリケーションのシークレットをコピーし、システムに便利な場所に貼り付けます。
    facebook_dashboard.pngの説明が続きます
    「図facebook_dashboard.pngの説明」

    Facebookチャネル構成を完了するには、アプリ・シークレットが必要です。

  5. アプリケーションのダッシュボードで、Facebookページを選択して、ページ・アクセス・トークンを生成します。
    page_access_token.pngの説明が続きます
    「図page_access_token.pngの説明」

  6. アクセス・トークンをコピーし、便利な場所に貼り付けます。

    このトークンを使用して、Digital Assistantでチャネルの定義を完了するために、Facebook AppにFacebookのMessaging APIへのアクセス権を与えます。

ノート

「Facebookユーザー・プロファイルAPI」を変更するには、2018年7月26日以前に作成したFacebookアプリの特定のユーザー・プロファイル・フィールドに対する権限をリクエストする必要があります。
次の権限がない場合、ユーザー名はランダムな数値文字列として移入されます。
  • pages_messaging

  • pages_user_locale

  • pages_user_timezone

7月26日より前にアプリケーションを作成した場合、2019年1月29日まで権限を適用しています。 2018年7月26日より後にアプリケーションを作成した場合、できるだけ早くこれらの権限を追加する必要があります。 メッセンジャ・ページのメッセンジャのアプリケーション・レビュー・セクションで設定できます。

ステップ2: Digital Assistantでのチャネルの作成

Facebookからページ・アクセス・トークンおよびアプリケーション秘密キーを指定して、「チャネルの作成」ダイアログを完了します。
  1. Digital Assistantの左側のメニューでチャネルをクリックして、ユーザーを選択します。
  2. 次に、チャネルの追加をクリックして「チャネルの作成」ダイアログを開きます。

  3. チャネルの名前を指定してください。

  4. チャネル・タイプとしてFacebook Messengerを選択します。
    create_channel_dialog_started.pngの説明が続きます
    「図create_channel_dialog_started.pngの説明」

  5. 「ページ・アクセス・トークン」フィールドに、Facebook Messengerの設定手順で前に生成したページ・アクセス・トークンを貼り付けます。

  6. 「App Secret」フィールドに、Facebook Messengerの設定手順で前にコピーしたアプリケーション・シークレットを貼り付けます。

  7. 「作成」(コールバック)をクリックします。

  8. チャネル・ページで、検証トークンとWebHook URLの両方をコピーし、システムで便利な場所に貼り付けます。 Facebook webフックを構成するには、これらが必要になります。
    fb_channel_complete.pngの説明が続きます
    「図fb_channel_complete.pngの説明」

ステップ3: Facebook Messenger Webフックの構成

Facebook Messengerで、前のステップでDigital Assistantによって生成されたWebフックURLを使用して、コールバックURLを定義します。
  1. Facebook Messengerで、webフックに対して最初に作成したプロジェクトを選択していることを確認します。



  2. Messengerをクリックして、設定を選択します。
    fb_navbar.pngの説明が続きます
    「図fb_navbar.pngの説明」

  3. イベントのサブスクライブをクリックして「新規ページ・サブスクリプション」ダイアログを開きます。

  4. Digital Assistantチャネル・ページから取得したWebフックURLをコピーし、それを「新規ページ・サブスクリプション」ダイアログの「CallBack URL」フィールドに貼り付けます。

  5. Digital Assistantによって生成される「トークンの検証」をコピーし、「トークンの検証」フィールドに貼り付けます。

  6. サブスクリプション・フィールドで、メッセージおよびmessaging_postbacksコールバック・イベントを選択します。

    messagesイベントは、Facebookページにメッセージが送信されるたびにトリガーされます。

  7. 確認して保存をクリックします。
  8. ページをサブスクライブします:
    1. Messenger設定のWebフック・セクションで、デジタル・アシスタント(またはスタンドアロン・スキル)のFacebookページを選択します。

    2. サブスクライブをクリックします。

    .

    ヒント:

    最初にサブスクライブ解除、次にサブスクライブをクリックして、webフックをバウンスする必要がある場合があります。

ステップ4: Facebookチャネルの有効化

構成が完了したら、Facebookチャネルをアクティブ化できます。

  • Digital Assistantで、チャネルを選択してチャネル有効コントロールをオンに切り替えます。
  • ルート先...ドロップダウンのアイコンをクリックし、チャネルに関連付けるデジタル・アシスタントまたはスキルを選択します。

これで、チャネルを介してボット・スルーできます。

ステップ5: Facebook Messengerでのボットのテスト

Facebookチャネルおよびメッセージの構成が完了したら、Facebookページ、Facebook Messenger (https://www.messenger.com/)および電話(これはFacebookアプリケーション・アイコンのイメージです。)のFacebook Messengerアプリケーションを使用してボットをテストできます。 検索でボットを見つけたら、そのボットとのチャットを開始できます。 ダイアログ・フローに対する変更をリアルタイムで確認できます。
test_bot.pngの説明が続きます
「図test_bot.pngの説明」

永続メニュー

Facebook Messengerでは、メッセージ・フィールドの横に永続メニューを作成できます。 この機能の詳細は、https://developers.facebook.com/docs/messenger-platform/send-messages/persistent-menu/を参照してください。

"Order Pizza"および"Order Pasta"の永続メニュー・アイテムを示す例を次に示します:



永続メニュー・アイテムの作成

デジタル・アシスタントまたはスタンドアロン・スキルの永続Facebookメニュー・アイテムを追加するには、次の手順を実行します:

  1. 開始ボタンを含む、すべての前提条件が設定されていることを確認します。

    これらの前提条件をここに示します : https://developers.facebook.com/docs/messenger-platform/send-messages/persistent-menu/#requirements

  2. Facebook永続メニューのcall_to_actions配列内のメニュー・アイテムごとに、一般的にhttps://developers.facebook.com/docs/messenger-platform/send-messages/persistent-menu/#set_menuで説明するアクションを追加します。
  3. 「MessengerプラットフォームAPI」へのPOSTコールを含む永続メニュー・アイテムを設定します。

    リクエストURIはhttps://graph.facebook.com/v2.6/me/messenger_profile?access_token=<PAGE_ACCESS_TOKEN>です。<PAGE_ACCESS_TOKEN>はFacebookアプリケーションのページ・アクセス・トークンです。

Digital Assistantの永続メニュー・アイテム

次に、デジタル・アシスタントの永続的なFacebookメニュー・アイテムを追加するための「MessengerプラットフォームAPI」へのPOSTの形式を示します:

{
  "persistent_menu":[
    {
      "locale":"default",
      "composer_input_disabled": false,
      "call_to_actions":[
            {
              "title":"menu item display name",
              "type":"postback",
              "payload":"{\"action\":\"system.textReceived\",\"variables\": {\"system.text\": \"utterance that contains the skill's invocation name\"}}"
            }
          ]
    }
  ]
}

ペイロードについては、Facebook Messengerからsystem.text変数を介してデジタル・アシスタントに発話を渡すsystem.textReceivedアクションを使用します。 その発話には、適切なルーティングを保証するために、ターゲット・スキルの起動名(つまり、明示的な起動)を含める必要があります。

Facebook Messengerでスキルの2つの永続メニュー・アイテム("Order Pizza"および"Order Pasta")を作成する例を次に示します:

{
  "persistent_menu":[
    {
      "locale":"default",
      "composer_input_disabled": false,
      "call_to_actions":[
            {
              "title":"Order Pizza",
              "type":"postback",
              "payload":"{\"action\":\"system.textReceived\",\"variables\": {\"system.text\": \"Order pizza from Pizza Joe \"}"
            },
            {
              "title":"Order Pasta",
              "type":"postback",
              "payload":"{\"action\":\"system.textReceived\",\"variables\": {\"system.text\": \"Order pasta from Pizza Joe \"}"
            }
          ]
    }
  ]
}

スタンドアロン・スキルの永続メニュー・アイテム

スタンドアロン・スキルの永続的なFacebookメニュー・アイテムを追加するための「MessengerプラットフォームAPI」へのPOSTの形式を次に示します:

{
  "persistent_menu":[
    {
      "locale":"default",
      "composer_input_disabled": false,
      "call_to_actions":[
            {
              "title":"menu item display name",
              "type":"postback",
              "payload":"{\"action\":\"action name\",\"variables\": {}"
            }
          ]
    }
  ]
}

ペイロードは、スキル・ダイアログ・フローでデフォルトの遷移として定義されるアクションです。

たとえば、メニュー・アイテムでスキルのヘルプ・フローを開始する場合は、ダイアログ・フローの次のようなデフォルトの遷移を定義します:

context:
  variables:
    ...
defaultTransitions:
  actions:
    help: "help"
states:

次に、そのヘルプ処理をFacebook永続メニューで参照します。

{
  "persistent_menu":[
    {
      "locale":"default",
      "composer_input_disabled": false,
      "call_to_actions":[
            {
              "title":"Help",
              "type":"postback",
              "payload":"{\"action\":\"help\",\"variables\": {}"
            }
          ]
    }
  ]
}

サポートされている機能

Digital AssistantのFacebook Messengerチャネルでは、次の機能がサポートされています:

  • テキスト(送信と受信の両方)
  • イメージ(送信と受信の両方)
  • ファイル(送信と受信の両方)
  • フィールド(送信と受信の両方)
  • ロケーション(送信と受信の両方)
  • links
  • ポストバック
  • 事業所リクエスト
  • カスタム・プロパティ
  • carouselコンポーネント
  • リスト・コンポーネント

メッセージの制約

Digital AssistantのFacebookメッセンジャのチャネルには、次のメッセージ制約があります:

  • テキスト・メッセージ
    • テキスト・メッセージの最大長: 640 characters. 長さが640を超えると、テキストは複数のメッセージに分割されます。
    • テキスト・アクション・ラベルの最大長: 20文字
    • 許可されるテキスト・アクションのタイプ: ポストバック、コール、URL
    • テキスト・アクションの最大数: 3。 さらにテキスト・アクションがある場合、メッセージは複数の水平カードに変換されます。その場合、各カードのタイトルと同じテキストが使用され、各カードには最大3個のアクションが含まれます。
  • 水平カード
    • タイトルの最大長: 80文字
    • 摘要の最大長: 80文字
    • カード処理ラベルの最大長: 20文字
    • カードの最大数: 10
    • カード処理の最大数: 3。 カード処理の数が3を超える場合、残りのカード処理を表示するためにカードが複製されます。
    • カード処理の最小数: 0
    • カード・リスト・アクションの最大数: 0
    • 少なくとも1つの説明、イメージまたはアクションが必要ですか: Yes
    • 許可されているカード処理のタイプ: ポストバック、コール、URL、シェア
    • カード・リスト処理のタイプ許可: N/A
  • 垂直カード
    • タイトルの最大長: 80文字
    • 摘要の最大長: 80文字
    • カード処理ラベルの最大長: 20文字
    • カードの最大数: 4
    • カード処理の最大数: 1。 その他のカード処理がある場合は、カードが重複して残りのカード処理がレンダリングされます。
    • カード処理の最小数: 0
    • カード・リスト・アクションの最大数: 1
    • 少なくとも1つの説明、イメージまたはアクションが必要ですか: Yes
    • 許可されているカード処理のタイプ: ポストバック、コール、URL、シェア
    • カード・リスト処理のタイプ許可: ポストバック、コール、URL
  • アタッチメント・メッセージ
    • サポート対象: Yes
    • アタッチ・アクションは許可されていますか: いいえ
  • 処理ボタン
    • グローバル・アクション・ラベルの最大長: 20文字
    • グローバル・アクションの最大数: 11
    • 許可されるグローバル・アクションのタイプ: ポストバック、ロケーション

Facebook Messengerチャネル拡張機能

Facebook Messengerチャネルでは、Facebook固有の機能を使用して、System.CommonResponseコンポーネントの機能を拡張できます。

拡張機能にアクセスするには、System.CommonResponseコンポーネントのchannelCustomProperties要素を使用し、適切なプロパティを設定します。 コードの書式は次のとおりです:

...
            channelCustomProperties:
            - channel: "facebook"
              properties:
                PROPERTY_NAME: "PROPERTY_VALUE"
...

Facebook Messengerチャネルで使用できるカスタム・プロパティは次のとおりです:

プロパティ名 指定できる値 適用対象... 説明
top_element_style
  • compact
  • large
次の属性を持つレスポンス品目:
  • type: "cards"
  • cardLayout: "vertical"
最初のカードのイメージがレンダリングされる方法を決定します。 詳細はhttps://developers.facebook.com/docs/messenger-platform/send-messages/template/list/#cover_imageを参照してください。

指定しない場合、Oracle Digital Assistantによって、このプロパティがcompact(Facebookのデフォルトの反対)にデフォルト設定されます。

image_aspect_ratio
  • horizontal
  • square
次の属性を持つレスポンス品目:
  • type: "cards"
  • cardLayout: "horizontal"
イメージのレンダリングに使用されるアスペクト比。 horizontal (1.91:1)にデフォルト設定されます。squareではアスペクト比が1: 1に設定されます。 https://developers.facebook.com/docs/messenger-platform/reference/template/generic#attachmentを参照してください
sharable
  • true
  • false
cardsタイプのレスポンス・アイテム。 trueに設定すると、Messengerのネイティブ共有ボタンがテンプレート・メッセージに対して有効になります。 デフォルトはfalseです。 https://developers.facebook.com/docs/messenger-platform/reference/template/generic#attachmentを参照してください
webview_height_ratio
  • compact
  • 高さ
  • full
次のいずれかです。
  • "url"のプロパティが指定されているカード
  • "type": "url"action
URLボタンがタップされたとき、またはURLプロパティが指定されているカードの高さがタップされたときに開かれるwebビューの高さ。 https://developers.facebook.com/docs/messenger-platform/reference/buttons/url#propertiesを参照してください
messenger_extensions
  • true
  • false
次のいずれかです。
  • "url"のプロパティが指定されているカード
  • "type": "url"action
Messenger拡張機能を使用すると、webビューで追加した機能をアクセス可能にすることによって、Webビューでエクスペリエンスを緊密に統合できます。 https://developers.facebook.com/docs/messenger-platform/reference/messenger-extensions-sdkを参照してください
fallback_url 有効なURL 次のいずれかです。
  • "url"のプロパティが指定されているカード
  • "type": "url"action
「メッセンジャ拡張機能」をサポートしていないクライアントで使用するURL。 これが定義されていない場合、urlがフォールバックとして使用されます。 指定できるのは、messenger_extensionsがtrueの場合のみです。 https://developers.facebook.com/docs/messenger-platform/reference/buttons/url#propertiesを参照してください
webview_share_button
  • hide
次のいずれかです。
  • "url"のプロパティが指定されているカード
  • "type": "url"action
webビューで共有ボタンを無効にする(機密情報の)には、hideに設定します。 これは、開発者が拡張機能を使用して開始したシェアには影響しません。
share_contents 「Facebook Messengerの送信API」で使用される形式は次のとおりです。
  • "type": "share"action
シェアの受信者が、このボタンがアタッチされているメッセージと異なる場合に、シェアの受信者に表示されるメッセージ。 https://developers.facebook.com/docs/messenger-platform/reference/buttons/share#propertiesを参照してください

次に、レスポンス・アイテム・レベル(top_element_style)とカード・レベル(webview_height_ratioおよびfallback_url)で定義されているカスタム・プロパティの例を示します:

OrderPizza:
  component: "System.CommonResponse"
  properties:
    metadata:
      responseItems:
        - type: "cards"
          cardLayout: "vertical"
          cards:
            - title: "${pizzas.name}"
              description: "${pizzas.description}"
              imageUrl: "${pizzas.image}"
              url: "${pizzas.moreInfo}"
              iteratorVariable: "pizzas"
              channelCustomProperties:
                - channel: "facebook"
                  properties:
                    webview_height_ratio: "compact"
                    fallback_url: "http://www.oracle.com"
          channelCustomProperties:
            - channel: "facebook"
              properties:
                top_element_style: "large"
  ...

channelCustomPropertiesの全般的な情報は、「チャネル固有の拡張」を参照してください。