รูปแบบเว็บฮุค Dialogflow {:#dialogflow-webhook-format} (Dialogflow)

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

หากคุณใช้ Dialogflow เพื่อสร้างการดำเนินการ การดำเนินการตามคำสั่งซื้อ สื่อสารกับ Dialogflow ผ่านรูปแบบเว็บฮุคแบบมาตรฐานของตัวเองแทน รูปแบบเว็บฮุคของการสนทนา Actions on Google รูปแบบเว็บฮุคของ Dialogflow มี ข้อมูลทั้งหมดของ รูปแบบเว็บฮุคของการสนทนา รวมทั้งข้อมูลอื่นๆ แบบเจาะจงของ Dialogflow เช่น ข้อมูลเกี่ยวกับ บริบทและพารามิเตอร์

คุณสามารถดูตัวอย่างข้อความ JSON สำหรับเว็บฮุคของ Dialogflow เพิ่มเติม ในโปรเจ็กต์ GitHub นี้

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

ข้อความคำขอจาก Dialogflow มีข้อมูลในรูปแบบเว็บฮุคของ Dialogflow ออบเจ็กต์นี้มี ข้อมูลของ Actions on Google โดยเฉพาะ ตามที่สรุปไว้ด้านล่างนี้

  • ค่า originalDetectIntentRequest.source คือ "google"
  • originalDetectIntentRequest.version บ่งชี้ถึงการดำเนินการใน Actions on Google สำหรับคำขอ
  • originalDetectIntentRequest.payload มีการดำเนินการสำคัญสำหรับ Google โดยเฉพาะ ข้อมูล รวมถึงการสนทนา คำขอ JSON จาก Assistant
  • เว็บฮุคของ Dialogflow ไม่รองรับช่อง Conversation.conversationToken คำขอ แต่การดำเนินการให้สมบูรณ์สามารถใช้ Dialogflow แทนได้ context เพื่อคงข้อมูลไว้ทั่วทั้ง ในการสนทนา

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

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

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

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

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

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

ตัวอย่างผลการค้นหาตัวช่วย

ข้อมูลโค้ดด้านล่างแสดงตัวอย่างผลลัพธ์ที่เป็นตัวช่วยในรูปแบบเว็บฮุคของ Dialogflow ตัวอย่างนี้แสดงการตอบสนองของผู้ใช้หลังจากที่เว็บฮุคบอกให้ Assistant ทราบ ที่ต้องได้รับการยืนยันจากผู้ใช้

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

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

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

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

เมื่อสื่อสารกับ Assistant คำตอบของคุณมักจะมี payload สรุป "google" ออบเจ็กต์ "google" ออบเจ็กต์เพย์โหลดมี ข้อมูลเฉพาะของ Actions on Google ต้องมีองค์ประกอบอย่างน้อย expectUserResponse และช่อง richResponse หรือ systemIntent

ช่องคีย์สำหรับ "google" ออบเจ็กต์เพย์โหลดมีการสรุปไว้ด้านล่างนี้

ช่อง คำอธิบาย
expectUserResponse ระบุว่าการดําเนินการตามคําขอของคุณคาดหวังการตอบกลับจากผู้ใช้หรือไม่ ตั้งค่าเป็น true ควรสนทนาต่อและ false จะสิ้นสุดลงเมื่อใด การสนทนา
userStorage จัดเก็บข้อมูลแบบถาวรที่ผูกอยู่กับผู้ใช้ที่เฉพาะเจาะจง พื้นที่เก็บข้อมูลทั้งหมด เท่ากับ 10,000 ไบต์
richResponse ช่องนี้มีเสียง ข้อความ การ์ด คำแนะนำ หรือข้อมูลที่มีโครงสร้าง เพื่อให้ Assistant แสดงผล หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับการใช้คำตอบที่เป็นสื่อสมบูรณ์สำหรับ Actions on Google โปรดดู การตอบกลับที่สมบูรณ์
systemIntent ช่องนี้มีโครงสร้างเหมือนกับ ExpectedInput.possibleIntents โดยปกติแล้วการตอบกลับของคุณจะมี systemIntent หาก Fulfillment ใช้ ความตั้งใจที่เป็นตัวช่วย possibleIntents ใน systemIntent ต้องตั้งค่าเป็น ExpectedIntent เปลี่ยนชื่อช่อง inputValueData เป็น data แล้ว

ภายในExpectedIntent ให้คุณระบุค่าต่อไปนี้

  • intent: ชื่อ Intent ของตัวช่วยที่ระบุประเภทของ ข้อมูลที่ต้องการให้ผู้ใช้ระบุ และ
  • data: ข้อกำหนดของค่า ซึ่งเป็นสตริงที่อธิบายข้อมูลที่ Assistant ต้องใช้การให้ความช่วยเหลือ

ตัวอย่างเช่น หากคุณกำลังขอสิทธิ์จากผู้ใช้ ให้ตั้งค่า intent เป็น actions.intent.PERMISSSION และ data ในข้อกำหนดของค่าเพื่อ "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" พร้อมด้วยช่องสำหรับ ประเภทนั้นๆ

รายการต่อไปนี้จะสรุปสตริงข้อกำหนดของค่าสำหรับผู้ช่วยที่คุณสามารถตั้งค่าใน systemIntent สําหรับการตอบกลับเว็บฮุคของ Dialogflow สำหรับรายการ Intent ของ Actions on Google ทั้งหมด สำหรับการควบคุมการสนทนา โปรดดู ข้อมูลอ้างอิง Intent

ชื่อ Intent ชื่อเหตุการณ์ Dialogflow ข้อมูลจำเพาะด้านค่า คำอธิบาย
actions.intent.CONFIRMATION actions_intent_CONFIRMATION "@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec" ได้รับการยืนยันจากผู้ใช้ (เช่น คำตอบของคำถามใช่หรือไม่)
actions.intent.DATETIME actions_intent_DATETIME "@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec" รับข้อมูลวันที่และเวลาจากผู้ใช้
actions.intent.DELIVERY_ADDRESS actions_intent_DELIVERY_ADDRESS "@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec" รับข้อมูลที่อยู่สำหรับจัดส่งจากผู้ใช้
actions.intent.LINK actions_intent_LINK "@type": "type.googleapis.com/google.actions.v2.LinkValueSpec" ขอ Deep Link ที่เข้ามาในแอป Android
actions.intent.OPTION actions_intent_OPTION "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec" รับรายการที่เลือกจากรายการหรือ UI ของภาพสไลด์
actions.intent.PERMISSION actions_intent_PERMISSION "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" หาข้อมูลของผู้ใช้ ซึ่งรวมถึงชื่อเต็ม ตำแหน่งคร่าวๆ หรือ ตำแหน่งที่แน่นอน
actions.intent.SIGN_IN actions_intent_SIGN_IN "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec" ขอขั้นตอนการลิงก์บัญชีเพื่อลิงก์บัญชีของผู้ใช้

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

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

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "this is a simple response"
            }
          }
        ]
      }
    }
  }
}

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

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

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

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

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

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

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

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

{
  "payload": {
    "google": {
      "expectUserResponse": false,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Goodbye!"
            }
          }
        ]
      }
    }
  }
}

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