Format webhook Dialogflow {:#dialogflow-webhook-format} (Dialogflow)

Bagian ini menjelaskan format payload JSON saat Actions on Google memanggil fulfillment melalui Dialogflow v2.

Jika Anda menggunakan Dialogflow untuk membuat Actions, fulfillment Anda berkomunikasi dengan Dialogflow melalui format webhook standarnya sendiri, bukan Format webhook percakapan Actions on Google. Format webhook Dialogflow berisi semua informasi dari format webhook percakapan beserta data khusus Dialogflow tambahan, seperti informasi tentang konteks, dan parameter.

Untuk melihat contoh pesan JSON lainnya untuk webhook Dialogflow, Anda dapat melihat ke project GitHub ini.

Isi permintaan

Pesan request dari Dialogflow berisi data dalam format webhook Dialogflow. Objek ini mencakup Informasi khusus Actions on Google, seperti yang diringkas di bawah:

  • Nilai originalDetectIntentRequest.source adalah "google".
  • originalDetectIntentRequest.version menunjukkan Actions on Google untuk permintaan tersebut.
  • originalDetectIntentRequest.payload berisi Tindakan utama khusus di Google informasi, termasuk topik pembicaraan permintaan JSON dari Asisten.
  • Kolom Conversation.conversationToken tidak didukung oleh webhook Dialogflow permintaan. Sebagai gantinya, fulfillment Anda bisa menggunakan Dialogflow context untuk mempertahankan data di seluruh masa hidup percakapan.

Contoh permintaan pemanggilan sederhana

Cuplikan di bawah ini menunjukkan contoh permintaan pemanggilan di Dialogflow format webhook.

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

Contoh permintaan percakapan sederhana

Cuplikan di bawah ini menunjukkan contoh permintaan percakapan dalam Dialogflow webhook, dengan input pengguna adalah string teks.

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

Contoh hasil bantuan

Cuplikan di bawah ini menunjukkan contoh hasil helper dalam format webhook Dialogflow. Contoh ini menunjukkan respons pengguna setelah webhook menunjukkan kepada Asisten bahwa sistem perlu mendapatkan konfirmasi pengguna.

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

Isi respons

Content-Type di header postingan HTTP dari endpoint fulfillment Anda ke Asisten harus application/json.

Pesan respons yang dikirim fulfillment Anda ke Dialogflow harus dalam format webhook Dialogflow.

Saat berkomunikasi dengan Asisten, respons Anda biasanya berisi payload objek yang merangkum "google" . "google" objek payload mencakup Informasi khusus Actions on Google. Dokumen ini harus berisi, minimal, Kolom expectUserResponse, dan kolom richResponse atau systemIntent.

Kolom utama untuk "google" dirangkum di bawah ini:

Kolom Deskripsi
expectUserResponse Menunjukkan apakah fulfillment Anda mengharapkan respons pengguna. Setel nilai ke true kapan percakapan harus tetap berlangsung dan false kapan percakapan berakhir percakapan tersebut.
userStorage Menyimpan data persisten yang terkait dengan pengguna tertentu. Total penyimpanan berjumlah 10.000 byte.
richResponse Kolom ini berisi audio, teks, kartu, saran, atau data terstruktur yang akan dirender oleh Asisten. Untuk mempelajari lebih lanjut tentang cara menggunakan respons kaya untuk Actions on Google, lihat Respons lengkap
systemIntent Isian ini memiliki struktur yang sama dengan ExpectedInput.possibleIntents. Respons Anda biasanya berisi systemIntent jika fulfillment Anda menggunakan maksud bantuan. Tujuan possibleIntents bidang di systemIntent harus disetel ke ExpectedIntent , dengan nama kolom inputValueData diubah menjadi data.

Dalam ExpectedIntent Anda menetapkan nilai-nilai berikut:

  • intent: Nama intent untuk helper yang menunjukkan jenis informasi yang Anda inginkan dari pengguna, dan
  • data: Spesifikasi nilai, yaitu string yang menjelaskan data yang yang diperlukan Asisten untuk melakukan bantuan.

Misalnya, jika Anda meminta izin pengguna, setel intent ke actions.intent.PERMISSSION dan data ke spesifikasi nilai untuk "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec", beserta kolom untuk jenis tersebut.

Daftar berikut ini merangkum string spesifikasi nilai untuk helper yang dapat Anda atur dalam systemIntent untuk respons webhook Dialogflow. Untuk daftar lengkap intent Actions on Google untuk kontrol percakapan, lihat Referensi Intent.

Nama Intent Nama Peristiwa Dialogflow Spesifikasi Nilai Deskripsi
actions.intent.CONFIRMATION actions_intent_CONFIRMATION "@type": "type.googleapis.com/google.actions.v2.ConfirmationValueSpec" Mendapatkan konfirmasi dari pengguna (misalnya, jawaban atas pertanyaan ya atau tidak).
actions.intent.DATETIME actions_intent_DATETIME "@type": "type.googleapis.com/google.actions.v2.DateTimeValueSpec" Memperoleh input tanggal dan waktu dari pengguna.
actions.intent.DELIVERY_ADDRESS actions_intent_DELIVERY_ADDRESS "@type": "type.googleapis.com/google.actions.v2.DeliveryAddressValueSpec" Mendapatkan input alamat pengiriman dari pengguna.
actions.intent.LINK actions_intent_LINK "@type": "type.googleapis.com/google.actions.v2.LinkValueSpec" Meminta aliran deep link ke aplikasi Android.
actions.intent.OPTION actions_intent_OPTION "@type": "type.googleapis.com/google.actions.v2.OptionValueSpec" Mendapatkan item yang dipilih dari UI daftar atau carousel.
actions.intent.PERMISSION actions_intent_PERMISSION "@type": "type.googleapis.com/google.actions.v2.PermissionValueSpec" Memperoleh informasi pengguna termasuk nama lengkap, lokasi perkiraan, atau lokasi presisi.
actions.intent.SIGN_IN actions_intent_SIGN_IN "@type": "type.googleapis.com/google.actions.v2.SignInValueSpec" Meminta alur penautan akun untuk menautkan akun pengguna.

Contoh respons sederhana

Cuplikan di bawah ini menunjukkan contoh respons sederhana dalam Dialogflow format webhook.

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

Contoh bantuan

Cuplikan di bawah ini menunjukkan contoh penggunaan intent helper dalam Dialogflow format webhook. Dalam contoh ini, webhook Anda menggunakan intent bantuan actions.intent.OPTIONS untuk memerintahkan Asisten mendapatkan pemilihan pengguna di antara dua opsi.

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

Saat menerima pesan dari contoh sebelumnya, Asisten untuk sementara mengambil alih percakapan dan meminta pengguna untuk membuat pilihan berdasarkan opsi yang diberikan. Saat mengumpulkan semua input pengguna yang diperlukan, Asisten mengirimkan hasil helper ini kembali ke fulfillment Anda dalam permintaan webhook Dialogflow.

Cuplikan di bawah menunjukkan contoh hasil bantuan dengan pilihan pilihan pengguna.

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

Contoh akhir percakapan

Cuplikan di bawah ini menunjukkan contoh respons sederhana untuk mengakhiri percakapan dalam format webhook Dialogflow. Tujuan expectUserResponse nilai false dalam sinyal pesan respons kepada Asisten bahwa tidak ada input pengguna lebih lanjut yang diharapkan dan itu harus mengakhiri {i>input<i} saat percakapan.

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

Untuk mempelajari cara mengganti perilaku default saat pengguna memanggil perintah untuk mengakhiri percakapan dengan Asisten, lihat panduan untuk keluar dari percakapan.