Định dạng webhook của cuộc trò chuyện {:#conversation-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 Action SDK.

Sau khi một cuộc trò chuyện bắt đầu, cuộc trò chuyện đó được xác định bằng một conversationId duy nhất. Đối với mỗi người dùng tiếp theo truy vấn đến Trợ lý, phương thức thực hiện sẽ nhận được một ý định webhook của bạn phải xử lý và phản hồi. conversationId này vẫn tồn tại trong mọi yêu cầu và cho đến khi cuộc trò chuyện kết thúc.

Nội dung yêu cầu

Khi người dùng đưa ra một truy vấn ban đầu hoặc đưa ra thông tin đầu vào tiếp theo, Trợ lý sẽ gửi một yêu cầu cho đơn hàng của bạn. Yêu cầu webhook cuộc trò chuyện từ Trợ lý chứa dữ liệu như ý định đã được kích hoạt, văn bản thô của người dùng đầu vào và khả năng trên giao diện mà thiết bị của người dùng sử dụng.

Dưới đây là các trường chính cho một yêu cầu theo định dạng webhook cuộc trò chuyện:

Trường Mô tả
isInSandbox Biến boolean này chủ yếu được dùng cho giao dịch, để cho biết liệu webhook của bạn có xử lý yêu cầu này trong hộp cát hay không . Ở chế độ hộp cát, webhook của bạn không được tính phí hoặc thực hiện bất kỳ đơn đặt hàng nào của người dùng. Theo mặc định, mục này được đặt thành "true".
surface Thông tin về Trợ lý hiển thị mà người dùng đang tương tác và các khả năng của Trợ lý.
Inputs Thông tin về yêu cầu gọi. Đối với lệnh gọi kích hoạt, tham số này bao gồm ý định liên kết với một hành động. Để trong một cuộc trò chuyện, đối tượng này cũng có thể bao gồm các đối số tương ứng với giá trị đầu vào dự kiến do phương thức thực hiện của bạn chỉ định.
User Thông tin về người dùng đã đưa ra yêu cầu. Thông tin này bao gồm cả các quyền được cấp bởi người dùng và ngôn ngữ của người dùng.
Conversation Thông tin về ngữ cảnh cuộc trò chuyện, bao gồm cả mã cuộc trò chuyện, loại (ví dụ: liệu yêu cầu này có đang bắt đầu một cuộc trò chuyện mới hay không) và mã thông báo cuộc trò chuyện để lưu trữ dữ liệu liên tục trong suốt thời gian trò chuyện.
availableSurfaces Thông tin này dùng cho cuộc trò chuyện trên nhiều nền tảng.

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 định dạng webhook cuộc trò chuyện.

{
  "user": {
    "userId": "ABwppHEF...",
    "locale": "en-US",
    "lastSeen": "2018-03-21T17:59:52Z",
    "userStorage": "{\"data\":{}}"
  },
  "device": {},
  "surface": {
    "capabilities": [
      {
        "name": "actions.capability.SCREEN_OUTPUT"
      },
      {
        "name": "actions.capability.AUDIO_OUTPUT"
      },
      {
        "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
      },
      {
        "name": "actions.capability.WEB_BROWSER"
      }
    ]
  },
  "conversation": {
    "conversationId": "1521784527171",
    "type": "NEW"
  },
  "inputs": [
    {
      "intent": "actions.intent.MAIN",
      "rawInputs": [
        {
          "inputType": "VOICE",
          "query": "Talk to my test app"
        }
      ]
    }
  ],
  "availableSurfaces": [
    {
      "capabilities": [
        {
          "name": "actions.capability.SCREEN_OUTPUT"
        },
        {
          "name": "actions.capability.AUDIO_OUTPUT"
        },
        {
          "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
        },
        {
          "name": "actions.capability.WEB_BROWSER"
        }
      ]
    }
  ]
}

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 định dạng webhook cuộc trò chuyện: trong đó hoạt động đầu vào của người dùng là một chuỗi văn bản (ví dụ: "Số may mắn của tôi là 88"):

{
  "user": {
    "userId": "ABwppHEF...",
    "locale": "en-US",
    "lastSeen": "2018-03-21T17:59:52Z",
    "userStorage": "{\"data\":{}}"
  },
  "device": {},
  "surface": {
    "capabilities": [
      {
        "name": "actions.capability.SCREEN_OUTPUT"
      },
      {
        "name": "actions.capability.AUDIO_OUTPUT"
      },
      {
        "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
      },
      {
        "name": "actions.capability.WEB_BROWSER"
      }
    ]
  },
  "conversation": {
    "conversationId": "1521784527171",
    "type": "NEW"
  },
  "inputs": [
    {
      "intent": "actions.intent.TEXT",
      "rawInputs": [
        {
          "inputType": "VOICE",
          "query": "My lucky number is 88."
        }
      ]
    }
  ],
  "availableSurfaces": [
    {
      "capabilities": [
        {
          "name": "actions.capability.SCREEN_OUTPUT"
        },
        {
          "name": "actions.capability.AUDIO_OUTPUT"
        },
        {
          "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
        },
        {
          "name": "actions.capability.WEB_BROWSER"
        }
      ]
    }
  ]
}

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ản hồi trong định dạng webhook của cuộc trò chuyện chứa dữ liệu, chẳng hạn như giao diện người dùng thực tế để hiển thị người dùng (bao gồm các thành phần âm thanh và hình ảnh) cũng như ý định có thể được kích hoạt trong yêu cầu tiếp theo (gọi là ý định dự kiến). Dự kiến ý định có thể là bất kỳ ý định nào mà Trợ lý hiểu được, như mô tả trong tài liệu tham khảo API Ý định.

Để tìm hiểu thêm về cách định dạng giao diện người dùng cho câu trả lời của bạn khi chúng hiển thị trong Trợ lý, hãy xem Tài liệu về Phản hồi.

Ví dụ về phản hồi đơn giản

Đoạn mã dưới đây cho thấy ví dụ về một câu trả lời đơn giản trong cuộc trò chuyện webhook.

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "You are using the Actions SDK. Do you want to hear more about it?"
              }
            }
          ]
        }
      }
    }
  ]
}

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

Đoạn mã dưới đây cho thấy ví dụ về cách sử dụng ý định trợ giúp trong cuộc trò chuyện webhook. Trong ví dụ này, webhook 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 trong số nhiều tuỳ chọn.

Để tìm hiểu thêm về cách sử dụng ý định của trình trợ giúp, hãy xem Hướng dẫn dành cho Trợ giúp.

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.OPTION",
          "inputValueData": {
            "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec",
            "carouselSelect": {
              "items": [
                {
                  "optionInfo": {
                    "key": "one",
                    "synonyms": [
                      "synonym of KEY_ONE 1",
                      "synonym of KEY_ONE 2"
                    ]
                  },
                  "description": "Description of number one",
                  "title": "Number one"
                },
                {
                  "optionInfo": {
                    "key": "two",
                    "synonyms": [
                      "synonym of KEY_TWO 1",
                      "synonym of KEY_TWO 2"
                    ]
                  },
                  "description": "Description of number two",
                  "title": "Number two"
                }
              ]
            }
          }
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "this shows an example of a carousel"
              }
            }
          ],
          "suggestions": [
            {
              "title": "1"
            },
            {
              "title": "2"
            }
          ]
        }
      }
    }
  ]
}

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 theo định dạng phản hồi webhook của cuộc trò chuyện.

expectedUserResponse giá trị false trong tin nhắn phản hồi báo hiệu cho Trợ lý rằng không có người dùng nào khác dữ liệu đầu vào dự kiến và sẽ kết thúc cuộc trò chuyện hiện tại. Chiến lược phát hành đĩa đơn finalResponse cho biết nội dung mà Trợ lý sẽ hiển thị hoặc đưa ra cho người dùng cuộc trò chuyện kết thúc.

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "simpleResponse": {
            "textToSpeech": "Good bye"
          }
        }
      ]
    }
  }
}

Để 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 Thoát khỏi cuộc trò chuyện.