Định dạng webhook {:#Dialogflow-webhook-format} (Dialogflow)

Phần này mô tả định dạng của tải trọng JSON khi Actions on Google gọi phương thức thực hiện của bạn thông qua Dialogflow phiên bản 2.

Nếu bạn đang sử dụng Dialogflow để tạo Hành động, thì phương thức thực hiện của bạn sẽ giao tiếp với Dialogflow thông qua định dạng webhook riêng thay vì định dạng webhook dành cho cuộc trò chuyện trong Actions on Google. Định dạng webhook chứa tất cả thông tin về định dạng webhook của cuộc trò chuyện cùng với dữ liệu bổ sung dành riêng cho Dialogflow, chẳng hạn như thông tin về ngữ cảnh và thông số.

Để xem thêm ví dụ về thông báo JSON cho webhook, bạn có thể tham khảo dự án GitHub này.

Nội dung yêu cầu

Tin nhắn yêu cầu từ Dialogflow chứa dữ liệu ở định dạng webhook Dialogflow. Đối tượng này bao gồm thông tin cụ thể về Hành động trên Google, như được tóm tắt dưới đây:

  • Giá trị originalDetectIntentRequest.source là "google".
  • originalDetectIntentRequest.version cho biết phiên bản Actions on Google cho yêu cầu đó.
  • originalDetectIntentRequest.payload chứa thông tin quan trọng về Hành động trên Google dành riêng cho Google, bao gồm cả JSON yêu cầu cuộc trò chuyện từ Trợ lý.
  • Các yêu cầu webhook không hỗ trợ trường Conversation.conversationToken. Thay vào đó, phương thức thực hiện của bạn có thể sử dụng ngữ cảnh Dialogflow để lưu trữ dữ liệu trong suốt thời gian diễn ra cuộc trò chuyện.

Ví dụ về yêu cầu gọi đơn giản

Đoạn mã dưới đây cho thấy ví dụ về một yêu cầu gọi ở định dạng webhook webhook.

{
  "responseId": "c4b863dd-aafe-41ad-a115-91736b665cb9",
  "queryResult": {
    "queryText": "GOOGLE_ASSISTANT_WELCOME",
    "action": "input.welcome",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_welcome"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_voice"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/8b006880-0af7-4ec9-a4c3-1cc503ea8260",
      "displayName": "Default Welcome Intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "Talk to my test app",
              "inputType": "VOICE"
            }
          ],
          "intent": "actions.intent.MAIN"
        }
      ],
      "user": {
        "lastSeen": "2018-03-16T22:08:48Z",
        "permissions": [
          "UPDATE"
        ],
        "locale": "en-US",
        "userId": "ABwppHEvwoXs18xBNzumk18p5h02bhRDp_riW0kTZKYdxB6-LfP3BJRjgPjHf1xqy1lxqS2uL8Z36gT6JLXSrSCZ"
      },
      "conversation": {
        "conversationId": "${SESSIONID}",
        "type": "NEW"
      },
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            }
          ]
        }
      ]
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Ví dụ về yêu cầu trò chuyện đơn giản

Đoạn mã dưới đây cho thấy ví dụ về một yêu cầu trò chuyện ở định dạng webhook Dialogflow, trong đó dữ liệu nhập của người dùng là một chuỗi văn bản.

{
  "responseId": "68efa569-4ba1-4b7f-9b1b-ac2865deb539",
  "queryResult": {
    "queryText": "query from the user",
    "action": "action.name.of.matched.dialogflow.intent",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_screen_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_audio_output"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/google_assistant_input_type_keyboard"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_media_response_audio"
      },
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_capability_web_browser"
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1f4e5bd9-a670-4161-a22e-2c97b077f29f",
      "displayName": "Name of Dialogflow Intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "query from the user",
              "inputType": "KEYBOARD"
            }
          ],
          "arguments": [
            {
              "rawText": "query from the user",
              "textValue": "query from the user",
              "name": "text"
            }
          ],
          "intent": "actions.intent.TEXT"
        }
      ],
      "user": {
        "lastSeen": "2017-10-06T01:06:56Z",
        "locale": "en-US",
        "userId": "AI_yXq-AtrRh3mJX5D-G0MsVhqun"
      },
      "conversation": {
        "conversationId": "1522951193000",
        "type": "ACTIVE",
        "conversationToken": "[]"
      },
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            }
          ]
        }
      ]
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Ví dụ về kết quả của trình trợ giúp

Đoạn mã dưới đây cho thấy ví dụ về một kết quả của trình trợ giúp cho định dạng webhook của Dialogflow. Ví dụ này cho thấy phản hồi của người dùng sau khi webhook cho Trợ lý biết rằng cần có xác nhận của người dùng.

{
  "responseId": "cb6f5ec2-c26e-4349-b561-a9ddd6a0e495",
  "queryResult": {
    "queryText": "actions_intent_CONFIRMATION",
    "action": "Dialogflow action name of matched intent",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_confirmation",
        "parameters": {
          "CONFIRMATION": true
        }
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
      "displayName": "Dialogflow action name of matched intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {},
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "yes",
              "inputType": "VOICE"
            }
          ],
          "arguments": [
            {
              "name": "CONFIRMATION",
              "boolValue": true
            }
          ],
          "intent": "actions.intent.CONFIRMATION"
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": []
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Nội dung phản hồi

Content-Type trong tiêu đề của các bài đăng HTTP từ điểm cuối của phương thức thực hiện đến Trợ lý phải là application/json.

Tin nhắn phản hồi mà phương thức thực hiện của bạn gửi cho Dialogflow phải ở định dạng webhook hộp thoại.

Khi giao tiếp với Trợ lý, phản hồi của bạn thường chứa đối tượng payload đóng gói đối tượng "google". Đối tượng tải trọng "google" bao gồm thông tin cụ thể của Actions on Google. Tệp này phải chứa tối thiểu một trường expectUserResponse, và một trường richResponse hoặc systemIntent.

Dưới đây là thông tin tóm tắt các trường chính cho đối tượng tải trọng "google":

Trường Nội dung mô tả
expectUserResponse Cho biết liệu phương thức thực hiện của bạn có mong đợi phản hồi của người dùng hay không. Đặt giá trị thành true thời điểm để tiếp tục cuộc trò chuyện và false để kết thúc cuộc trò chuyện.
userStorage Lưu trữ dữ liệu cố định được liên kết với một người dùng cụ thể. Tổng dung lượng bộ nhớ là 10.000 byte.
richResponse Trường này chứa âm thanh, văn bản, thẻ, nội dung đề xuất hoặc dữ liệu có cấu trúc để Trợ lý hiển thị. Để tìm hiểu thêm về cách sử dụng câu trả lời nhiều định dạng cho Actions on Google, hãy xem phần Phản hồi nhiều định dạng
systemIntent Trường này có cấu trúc giống như ExpectedInput.possibleIntents. Phản hồi của bạn thường chứa systemIntent nếu phương thức thực hiện của bạn đang sử dụng ý định trợ giúp. Trường possibleIntents trong systemIntent phải được đặt thành đối tượng ExpectedIntent, trong đó tên trường inputValueData được thay đổi thành data.

Trong đối tượng ExpectedIntent, bạn chỉ định các giá trị sau:

  • intent (ý định): Tên ý định của trình trợ giúp, cho biết loại thông tin bạn muốn người dùng cung cấp, và
  • dữ liệu: Thông số kỹ thuật của giá trị, là một chuỗi mô tả dữ liệu cần thiết để Trợ lý thực hiện trình trợ giúp.

Ví dụ: nếu bạn đang yêu cầu người dùng cấp quyền, hãy đặt intent thành actions.intent.PERMISSSION và data thành thông số kỹ thuật giá trị thành "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec", cùng với các trường cho loại đó.

Danh sách sau đây tóm tắt các chuỗi thông số kỹ thuật giá trị cho trình trợ giúp mà bạn có thể đặt trong systemIntent cho phản hồi bằng webhook. Để biết danh sách đầy đủ các ý định trong Actions on Google dành cho việc kiểm soát cuộc trò chuyện, hãy xem tài liệu tham khảo về Ý định.

Tên ý định Tên sự kiện Dialogflow Thông số giá trị Nội dung mô tả
actions.intent.CONFIRMATION actions_intent_CONFIRMATION "@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec" Lấy thông tin xác nhận của người dùng (ví dụ: câu trả lời cho câu hỏi có hoặc không).
actions.intent.DATETIME actions_intent_DATETIME "@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec" Lấy ngày và giờ nhập từ người dùng.
actions.intent.DELIVERY_ADDRESS actions_intent_DELIVERY_ADDRESS "@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec" Nhận thông tin nhập địa chỉ giao hàng từ người dùng.
actions.intent.LINK actions_intent_LINK "@type": "type.googleapis.com/google.actions.v2.LinkValueSpec" Yêu cầu luồng liên kết sâu vào ứng dụng Android.
actions.intent.OPTION actions_intent_OPTION "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec" Lấy mục đã chọn từ giao diện người dùng danh sách hoặc băng chuyền.
actions.intent.PERMISSION actions_intent_PERMISSION "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" Thu thập thông tin của người dùng, bao gồm cả tên đầy đủ, vị trí tương đối hoặc vị trí chính xác.
actions.intent.SIGN_IN actions_intent_SIGN_IN "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec" Yêu cầu một quy trình liên kết tài khoản để liên kết tài khoản của người dùng.

Ví dụ về câu trả lời đơn giản

Đoạn mã dưới đây cho thấy ví dụ về một phản hồi đơn giản theo định dạng webhook webhook.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "this is a simple response"
            }
          }
        ]
      }
    }
  }
}

Ví dụ về trình trợ giúp

Đoạn mã dưới đây cho thấy ví dụ về việc sử dụng ý định của người trợ giúp trong định dạng webhook Dialogflow. Trong ví dụ này, webhook của bạn đang sử dụng ý định trợ giúp actions.intent.OPTIONS để hướng dẫn Trợ lý chọn một trong hai lựa chọn của người dùng.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Choose a item"
            }
          }
        ]
      },
      "systemIntent": {
        "intent": "actions.intent.OPTION",
        "data": {
          "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
          "listSelect": {
            "title": "Hello",
            "items": [
              {
                "optionInfo": {
                  "key": "first title key"
                },
                "description": "first description",
                "image": {
                  "url": "/assistant/images/badges/XPM_BADGING_GoogleAssistant_VER.png",
                  "accessibilityText": "first alt"
                },
                "title": "first title"
              },
              {
                "optionInfo": {
                  "key": "second"
                },
                "description": "second description",
                "image": {
                  "url": "https://lh3.googleusercontent.com/Nu3a6F80WfixUqf_ec_vgXy_c0-0r4VLJRXjVFF_X_CIilEu8B9fT35qyTEj_PEsKw",
                  "accessibilityText": "second alt"
                },
                "title": "second title"
              }
            ]
          }
        }
      }
    }
  }
}

Khi nhận được tin nhắn từ ví dụ trước, Trợ lý sẽ tạm thời tiếp quản cuộc trò chuyện và nhắc người dùng đưa ra lựa chọn dựa trên các tuỳ chọn cho sẵn. Khi thu thập tất cả dữ liệu cần thiết mà người dùng nhập, Trợ lý sẽ gửi lại kết quả trợ giúp này cho phương thức thực hiện của bạn trong yêu cầu webhook của Dialogflow.

Đoạn mã dưới đây cho thấy ví dụ về kết quả của trình trợ giúp với lựa chọn do người dùng chọn.

{
  "responseId": "ea166558-615a-48f3-ae5b-7f55d895784b",
  "queryResult": {
    "queryText": "actions_intent_OPTION",
    "action": "",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [
      {
        "name": "projects/${PROJECTID}/agent/sessions/${SESSIONID}/contexts/actions_intent_option",
        "parameters": {
          "OPTION": "key of selected item"
        }
      }
    ],
    "intent": {
      "name": "projects/${PROJECTID}/agent/intents/1777d616-a5f7-4838-a9a9-870f2956bd14",
      "displayName": "Dialogflow intent name of matched intent"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": "en-us"
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": []
      },
      "inputs": [
        {
          "rawInputs": [
            {
              "query": "Title of selected item",
              "inputType": "TOUCH"
            }
          ],
          "arguments": [
            {
              "textValue": "Key of selected item",
              "name": "OPTION"
            }
          ],
          "intent": "actions.intent.OPTION"
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": []
    }
  },
  "session": "projects/${PROJECTID}/agent/sessions/${SESSIONID}"
}

Ví dụ về việc kết thúc cuộc trò chuyện

Đoạn mã dưới đây cho thấy ví dụ về một phản hồi đơn giản để kết thúc phiên trò chuyện ở định dạng webhook của Dialogflow. Giá trị expectUserResponse của false trong tin nhắn phản hồi sẽ báo cho Trợ lý biết rằng người dùng không cần nhập thêm dữ liệu đầu vào nữa và giá trị này sẽ kết thúc cuộc trò chuyện hiện tại.

{
  "payload": {
    "google": {
      "expectUserResponse": false,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Goodbye!"
            }
          }
        ]
      }
    }
  }
}

Để tìm hiểu cách ghi đè hành vi mặc định khi người dùng gọi một cụm từ tiêu chuẩn để kết thúc cuộc trò chuyện với Trợ lý, hãy xem hướng dẫn thoát khỏi cuộc trò chuyện.