Đị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 phương thức thực hiện của bạn thông qua Actions SDK.

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

Lưu ý: Phản hồi của bạn phải được trả lời trong vòng 10 giây, nếu không, Trợ lý sẽ giả định rằng phương thức thực hiện đã hết thời gian chờ và sẽ kết thúc cuộc trò chuyện của bạn.

Nội dung yêu cầu

Khi người dùng đưa ra truy vấn ban đầu hoặc cung cấp một số dữ liệu đầu vào tiếp theo, Trợ lý sẽ gửi yêu cầu đến phương thức thực hiện của bạn. Các yêu cầu webhook trò chuyện từ Trợ lý chứa các dữ liệu như ý định đã được kích hoạt, văn bản thô mà người dùng nhập và các chức năng trên nền tảng của thiết bị của người dùng.

Dưới đây là thông tin tóm tắt về các trường chính cho một yêu cầu ở định dạng webhook cuộc trò chuyện:

Trường	Nội dung mô tả
isInSandbox	Biến boolean này chủ yếu được dùng cho tính năng giao dịch, để cho biết liệu webhook của bạn có phải xử lý yêu cầu này ở chế độ 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ề nền tảng Trợ lý mà người dùng đang tương tác và khả năng của ứng dụng.
Inputs	Thông tin về yêu cầu gọi. Đối với lệnh gọi kích hoạt, phương thức này có ý định liên kết với một hành động. Đối với các yêu cầu tiếp theo 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 đầ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 quyền do người dùng cấp 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ã nhận dạng cuộc trò chuyện, loại cuộc trò chuyện (ví dụ: việc yêu cầu này có 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 các 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 ở định dạng webhook cho 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 ở định dạng webhook đối với cuộc trò chuyện, trong đó thông tin do người dùng nhập 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 của phương thức thực hiện đến Trợ lý phải là application/json.

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

Lưu ý: Trong thông tin phản hồi của webhook, bạn thường sẽ chỉ định actions.intent.TEXT làm ý định dự kiến. Ý định này đại diện cho một phản hồi dạng văn bản thô từ người dùng. Hàm ask() chung trong thư viện ứng dụng dự kiến ý định này.

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

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

Đoạn mã dưới đây là ví dụ về một phản hồi đơn giản theo định dạng webhook cho cuộc trò chuyện.

{
  "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 là một ví dụ về cách sử dụng ý định trợ giúp theo định dạng webhook trong cuộc trò chuyện. Trong ví dụ này, webhook đang sử dụng ý định trợ giúp actions.intent.OPTIONS để hướng dẫn Trợ lý lấy lựa chọn của người dùng trong số nhiều lựa chọn.

Để tìm hiểu thêm về cách sử dụng ý định của trình trợ giúp, vui lòng xem hướng dẫn dành cho Trình 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ề việc kết thúc cuộc trò chuyện

Đoạn mã dưới đây là ví dụ về một câu trả lời đơn giản để kết thúc phiên trò chuyện ở định dạng phản hồi webhook.

Giá trị expectedUserResponse của false trong thông báo phản hồi sẽ báo cho Trợ lý biết rằng không có hoạt động đầu vào nào khác của người dùng cần được người dùng nhập thêm và sẽ kết thúc cuộc trò chuyện hiện tại. Giá trị finalResponse cho biết nội dung mà Trợ lý sẽ hiển thị hoặc xuất cho người dùng trước khi 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 cụm từ tiêu chuẩn để kết thúc cuộc trò chuyện với Trợ lý, hãy xem phần Thoát khỏi cuộc trò chuyện.