Đị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ả của trình 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 đến 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 đối tượng tải trọng "google" được tóm tắt dưới đây:

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

• ý định: Tên ý định cho 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 quyền của người dùng, 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ị 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.

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ề cách 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 hoạt động ở định dạng webhook của 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.