Đị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 thực hiện đơn hàng thông qua Dialogflow phiên bản 2.

Nếu bạn đang dùng Dialogflow để tạo Hành động, phương thức thực hiện của bạn giao tiếp với Dialogflow thông qua định dạng webhook chuẩn, riêng thay vì Định dạng webhook của cuộc trò chuyện trên Google ( Actions on Google). Định dạng webhook Dialogflow chứa tất cả thông tin của định dạng webhook của cuộc trò chuyện cùng với dữ liệu bổ sung cụ thể về 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 webhook, bạn có thể tham khảo cho dự án GitHub này.

Nội dung yêu cầu

Thư yêu cầu từ Dialogflow chứa dữ liệu ở định dạng webhook. Đối tượng này bao gồm Thông tin cụ thể về các 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 Actions on Google cho yêu cầu.
  • originalDetectIntentRequest.payload chứa các Hành động chính dành riêng cho Google thông tin, bao gồm cả cuộc trò chuyện yêu cầu JSON của Trợ lý.
  • Trường Conversation.conversationToken không được webhook của Dialogflow hỗ trợ yêu cầu. Thay vào đó, phương thức thực hiện đơn hàng của bạn có thể sử dụng Dialogflow ngữ cảnh để duy trì dữ liệu trên suốt thời gian 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 trong Dialogflow 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 trong Dialogflow định dạng webhook, trong đó thông tin đầu vào 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ả trợ giúp

Đoạn mã dưới đây cho thấy ví dụ về kết quả từ trình trợ giúp trong định dạng webhook của Dialogflow. Ví dụ này cho thấy câu trả lời của người dùng sau khi webhook chỉ định cho Trợ lý cần có đượ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 thực hiện của bạn cho Trợ lý phải là application/json.

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

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

Các trường chính cho "google" được tóm tắt dưới đây về đối tượng tải trọng:

Trường 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 liên quan đến một người dùng cụ thể. Tổng bộ nhớ dung lượng 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ý kết xuất. Để tìm hiểu thêm về việc sử dụng câu trả lời nhiều định dạng cho Actions on Google, hãy xem Câu trả lờ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. Chiến lược phát hành đĩa đơn possibleIntents trường trong systemIntent phải được đặt thành ExpectedIntent với tên trường inputValueData được thay đổi thành data.

Trong ExpectedIntent , bạn chỉ định các giá trị sau:

  • intent: Tên ý định của trình trợ giúp cho biết loại thông tin mà bạn muốn người dùng cung cấp và
  • data: Thông số kỹ thuật giá trị, là một chuỗi mô tả dữ liệu cần thiết để Trợ lý thực hiện việc 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 vào quy cách giá trị để "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec", cùng với các trường dành cho loại đó.

Danh sách sau đây tóm tắt các chuỗi thông số kỹ thuật giá trị dành cho trình trợ giúp mà bạn có thể đặt trong một systemIntent cho phản hồi webhook Dialogflow. Để xem danh sách đầy đủ các ý định của Actions on Google để kiểm soát 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ố kỹ thuật giá trị Mô tả
actions.intent.CONFIRMATION actions_intent_CONFIRMATION "@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec" Nhận được 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" Nhận thông tin nhập ngày và giờ 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 một luồng liên kết sâu trong ứ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" Lấy thông tin của người dùng, bao gồm 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 một tài khoản của người dùng.

Ví dụ về phản hồ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 trong Dialogflow 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 một ví dụ về cách sử dụng ý định trợ giúp trong Dialogflow webhook. Trong ví dụ này, webhook của bạn sử dụng actions.intent.OPTIONS ý định của trình trợ giúp để hướng dẫn Trợ lý có được lựa chọn của người dùng giữa hai tuỳ chọn.

{
  "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 thông báo từ ví dụ trước, Trợ lý tạm thời tiếp quản cuộc trò chuyện và nhắc người dùng lựa chọn dựa trên các tuỳ chọn đã cho. Sau khi thu thập tất cả thông tin đầu vào cần thiết của người dùng, Trợ lý gửi kết quả trợ giúp này trở lại phương thức thực hiện của bạn trong yêu cầu webhook webhook.

Đoạn mã dưới đây cho thấy một 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ề kết thúc cuộc trò chuyện

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

{
  "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 để 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.