Actions on Google Webhook 形式（Dialogflow）

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

注: Node.js バックエンド サーバーがある場合は、Actions on Google Node.js クライアント ライブラリを使用して Webhook の作成を簡素化することを強くおすすめします。クライアント ライブラリは、Webhook 形式のラッパーを提供します。クライアント ライブラリを使用せずに独自のバックエンド実装を開始する場合、HTTP POST を介して Actions on Google から送信された JSON メッセージの使用と処理はバックエンドが行います。

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

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

主な用語:

• Dialogflow Webhook 形式: Actions on Google が Dialogflow を介してフルフィルメントを呼び出すときの JSON ペイロード形式。
• 会話 Webhook 形式: Actions on Google が Actions SDK を通じてフルフィルメントを呼び出すときの JSON ペイロード形式。

リクエスト タイプ

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

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

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

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 の形式をご覧ください。