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

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

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

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

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

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

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

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

ข้อมูลโค้ดด้านล่างแสดงตัวอย่างคำขอเรียกใช้ในรูปแบบเว็บฮุคของ 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 จากปลายทาง Fulfillment ไปยัง Assistant ต้องเป็น application/json

ข้อความตอบกลับที่ Fulfillment ของคุณส่งไปยัง 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 สำหรับ Helper ที่ระบุประเภทข้อมูล ที่คุณต้องการให้ผู้ใช้ระบุ และ
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 ในตัวอย่างนี้ เว็บฮุคของคุณใช้ Intent ของตัวช่วย 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 จะส่งผลลัพธ์ของผู้ช่วยนี้กลับไปยัง Fulfillment ของคุณในคำขอเว็บฮุคของ 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 expectUserResponse ในข้อความตอบกลับจะส่งสัญญาณให้ Assistant ทราบว่าผู้ใช้ไม่ควรป้อนข้อมูลเพิ่มเติมและควรสิ้นสุดการสนทนาปัจจุบัน

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

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