Actions on Google Webhook 形式（Dialogflow）

このドキュメントでは、Actions on Google と、カスタム会話ユーザー インターフェースを定義するフルフィルメント サービスと間の通信を行うための Webhook 形式について説明します。

Actions on Google とフルフィルメントが Actions on Google Webhook 形式を介してどのように通信するかを理解することが重要です。

  • Actions on Google との会話に参加するために、フルフィルメントには、Actions on Google からの HTTP リクエストに応答できる Webhook が実装されています。
  • ユーザーがアクションを呼び出すと、フルフィルメントは、ユーザーのリクエストを記述する JSON ペイロードを含む HTTP POST を受け取ります。
  • 次に、フルフィルメントは、リクエスト ペイロードからパラメータを読み取り、適切な JSON 形式のレスポンスを生成し、そのレスポンスを使用してアシスタントに返信します。

リクエスト タイプ

この表は、Webhook がアシスタントから受け取る可能性のあるリクエストのタイプをまとめたものです。

種類 説明 JSON の例
呼び出しリクエスト フルフィルメントとの会話を開始する、またはディープリンク アクションをトリガーするユーザーの発話（例: 「パーソナル シェフと話して夕食のレシピを教えて」）。
  • Dialogflow を使用している場合、これらのリクエストは、Google アシスタントの統合設定の [検出] セクションで定義されているインテントに対応します。
  • Actions SDK を使用している場合、これらのリクエストは、アクション パッケージで定義されたインテントに対応します。
会話リクエスト フルフィルメントとの会話が開始した後の同じセッション内のユーザーによる発話。会話 Webhook 形式では、これらは前のターンでフルフィルメントがリクエストした actions.intent.TEXT インテントに対応する、ユーザーからの未加工のテキスト レスポンスです。
ヘルパー結果 Webhook が会話の前のターンでヘルパー インテントをリクエストして会話の一部（actions.intent.OPTION と actions.intent.PERMISSION など）を処理した場合に、アシスタントからフルフィルメントに送信されるリクエスト。

会話のリクエストとレスポンス

Actions on Google の典型的なインタラクションのシナリオでは、ユーザーがフレーズを発話してアクションを呼び出します。Actions on Google は、レスポンスを提供するため、ユーザーが呼び出したアクションに一致するフルフィルメントを見つけてリクエストを送信します。

Actions on Google は、フルフィルメントがユーザーの呼び出しに適していることを確認すると、ユーザーのリクエスト情報を含む JSON ペイロードを含む HTTP リクエストをフルフィルメント エンドポイントに送信して会話セッションを開始します。フルフィルメントはリクエストを解析し、JSON ペイロードを含むレスポンスを返します。Actions on Google は、ペイロードをレンダリングされた音声とマルチメディア出力に変換します。

図 1. Actions SDK を介してフルフィルメントを呼び出す Actions on Google。

Actions on Google が Actions SDK を介してフルフィルメントを呼び出すときの JSON ペイロードの形式については、会話 Webhook の形式をご覧ください。

Dialogflow のリクエストとレスポンス

アクションを作成するときに、必要に応じて Dialogflow を使用して、会話インターフェースの構築タスクを簡素化できます。このシナリオでは、Dialogflow は Actions on Google とフルフィルメントの間のプロキシとして機能します。HTTP/JSON リクエストをフルフィルメント エンドポイントに直接送信するのではなく、Actions on Google が Dialogflow に送信します。

Dialogflow は、元のリクエストに含まれる JSON ペイロードを Dialogflow Webhook 形式にラップし、生成されたリクエストを Dialogflow フルフィルメントに転送します。

逆に、フルフィルメントから Dialogflow にレスポンスを送信する場合、レスポンスの JSON ペイロードは Dialogflow Webhook 形式に準拠している必要があります。フルフィルメントは、Dialogflow JSON リクエストのパラメータを解析し、Dialogflow Webhook 形式でレスポンスを生成します。Dialogflow は、フルフィルメントからのレスポンスを、アシスタントが理解できるレスポンス メッセージに変換します。

図 2. Dialogflow を通じてフルフィルメントを呼び出す Actions on Google。

Actions on Google が Dialogflow を通じてフルフィルメントを呼び出すときの JSON ペイロードの形式については、Dialogflow Webhook の形式をご覧ください。