รูปแบบเว็บฮุคของการสนทนา {:#conversation-webhook-format} (Dialogflow)

ส่วนนี้จะอธิบายรูปแบบของเพย์โหลด JSON เมื่อ Actions on Google เรียกใช้ การดำเนินการผ่าน Actions SDK

เมื่อการสนทนาเริ่มขึ้นแล้ว ระบบจะระบุการสนทนานั้นด้วย conversationId ที่ไม่ซ้ำกัน สำหรับผู้ใช้แต่ละคนที่ตามมา Assistant จะถือว่าการดำเนินการตามคำสั่งซื้อได้รับความตั้งใจที่ เว็บฮุคจะต้องประมวลผลและตอบกลับ จะมีconversationIdข้อมูลนี้อยู่ในทุกคำขอและ คู่คำตอบจนกว่าการสนทนาจะสิ้นสุด

เนื้อหาของคำขอ

เมื่อผู้ใช้ทำการค้นหาเบื้องต้นหรือป้อนข้อมูลในภายหลัง Assistant จะส่งคำขอ ได้ตามคำสั่งซื้อ คำขอเว็บฮุคของการสนทนา จาก Assistant ประกอบด้วยข้อมูล เช่น ความตั้งใจที่ถูกเรียกให้แสดง ข้อความดิบของผู้ใช้ และความสามารถในการแสดงผลของอุปกรณ์ของผู้ใช้

ช่องคีย์สําหรับคําขอในรูปแบบเว็บฮุคของการสนทนาจะสรุปได้ดังนี้

ช่อง คำอธิบาย
isInSandbox ตัวแปรบูลีนนี้ใช้สำหรับ เป็นหลัก ธุรกรรม เพื่อระบุว่าเว็บฮุคควรจัดการคำขอนี้ในแซนด์บ็อกซ์หรือไม่ ในโหมดแซนด์บ็อกซ์ เว็บฮุคของคุณไม่ควรเรียกเก็บเงินหรือดำเนินการตามใบสั่งซื้อจากผู้ใช้ ระบบจะตั้งค่าเป็น "true" โดยค่าเริ่มต้น
surface ข้อมูลเกี่ยวกับ Assistant จะแสดงการโต้ตอบกับผู้ใช้และความสามารถต่างๆ ของผู้ใช้
Inputs ข้อมูลเกี่ยวกับคำขอเรียกใช้ สำหรับการเรียกใช้ทริกเกอร์ เงื่อนไขนี้รวมถึง intent ที่แมปกับการดำเนินการ สำหรับตอนถัดไป ในการสนทนา ออบเจ็กต์นี้อาจมีอาร์กิวเมนต์ที่สอดคล้องกับ ข้อมูลที่คาดว่าจะได้รับซึ่งระบุโดยการดำเนินการของคุณ
User ข้อมูลเกี่ยวกับผู้ใช้ที่ส่งคำขอ ข้อมูลนี้รวมถึงสิทธิ์ ที่ได้รับจากผู้ใช้ และภาษาของผู้ใช้
Conversation ข้อมูลเกี่ยวกับบริบทการสนทนา รวมถึงรหัสการสนทนา ประเภท (ตัวอย่างเช่น คำขอนี้กำลังเริ่มการสนทนาใหม่หรือไม่) และโทเค็นการสนทนา เพื่อเก็บข้อมูลถาวรของการสนทนา
availableSurfaces ข้อมูลนี้ใช้สำหรับ การสนทนาแบบหลายแพลตฟอร์ม

ตัวอย่างคำขอการเรียกใช้แบบง่าย

ข้อมูลโค้ดด้านล่างแสดงตัวอย่างคำขอเรียกใช้ในรูปแบบเว็บฮุคของการสนทนา

{
  "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"
        }
      ]
    }
  ]
}

ตัวอย่างคำขอการสนทนาอย่างง่าย

ตัวอย่างข้อมูลด้านล่างแสดงตัวอย่างคำขอแบบสนทนาในรูปแบบเว็บฮุคของการสนทนา โดยที่ผู้ใช้ป้อนเป็นสตริงข้อความ (เช่น “เลขนำโชคของฉันคือ 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"
        }
      ]
    }
  ]
}

เนื้อหาการตอบกลับ

Content-Type ในส่วนหัวของโพสต์ HTTP จากปลายทางของการดำเนินการตามคำสั่งซื้อ Assistant ต้องเป็น application/json

การตอบกลับใน รูปแบบเว็บฮุคของการสนทนาจะประกอบด้วยข้อมูล เช่น UI จริงเพื่อแสดง ผู้ใช้ (รวมถึงองค์ประกอบเสียงและภาพ) และความตั้งใจที่สามารถ ทริกเกอร์ในคำขอที่ตามมา (เรียกว่า Intent ที่คาดการณ์) ผลลัพธ์ที่คาดไว้ Intent อาจเป็น Intent ใดก็ได้ที่ Assistant เข้าใจตามที่อธิบายไว้ ในข้อมูลอ้างอิง API ของ Intent

หากต้องการดูข้อมูลเพิ่มเติมเกี่ยวกับการจัดรูปแบบอินเทอร์เฟซผู้ใช้สําหรับคําตอบ ที่แสดงใน Assistant โปรดดู เอกสารประกอบเกี่ยวกับการตอบกลับ

ตัวอย่างคำตอบอย่างง่าย

ตัวอย่างข้อมูลด้านล่างแสดงตัวอย่างคำตอบง่ายๆ ในการสนทนา รูปแบบเว็บฮุค

{
  "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?"
              }
            }
          ]
        }
      }
    }
  ]
}

ตัวอย่างตัวช่วย

ตัวอย่างข้อมูลด้านล่างแสดงตัวอย่างการใช้ Intent ที่เป็นตัวช่วยในการสนทนา รูปแบบเว็บฮุค ในตัวอย่างนี้ เว็บฮุคกำลังใช้เมธอด ความตั้งใจของตัวช่วย actions.intent.OPTIONS ที่จะสั่งให้ Assistant ดาวน์โหลด ที่ผู้ใช้สามารถเลือกระหว่างตัวเลือกที่หลากหลาย

ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้ Intent ของตัวช่วยได้ที่ คู่มือผู้ช่วย

{
  "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"
            }
          ]
        }
      }
    }
  ]
}

ตัวอย่างสิ้นสุดการสนทนา

ตัวอย่างข้อมูลด้านล่างแสดงตัวอย่างการตอบกลับง่ายๆ เพื่อสิ้นสุดการสนทนา เซสชันในรูปแบบการตอบกลับของเว็บฮุคของการสนทนา

expectedUserResponse ค่า false ในข้อความตอบกลับจะส่งสัญญาณให้ Assistant ทราบว่าไม่มีผู้ใช้ ต้องการ และควรสิ้นสุดการสนทนาปัจจุบัน finalResponse จะบ่งชี้ว่า Assistant ควรแสดงอะไรหรือแสดงผลให้ผู้ใช้เห็นก่อน การสนทนาจะสิ้นสุดลง

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

ดูวิธีลบล้างลักษณะการทำงานเริ่มต้นเมื่อผู้ใช้เรียกใช้มาตรฐาน วลีสำหรับจบการสนทนากับ Assistant โปรดดู การออกจากการสนทนา