Tindakan Percakapan tidak digunakan lagi pada 13 Juni 2023. Untuk mengetahui informasi selengkapnya, lihat Penghentian Action Percakapan.

Halaman ini diterjemahkan oleh Cloud Translation API.

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

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

Jika Anda menggunakan Dialogflow untuk membuat Action, fulfillment Anda akan berkomunikasi dengan Dialogflow melalui format webhook standarnya sendiri, bukan format webhook percakapan Actions on Google. Format webhook Dialogflow berisi semua informasi 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 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 dirangkum di bawah:

Nilai originalDetectIntentRequest.source adalah "google".
originalDetectIntentRequest.version menunjukkan versi Actions on Google untuk permintaan tersebut.
originalDetectIntentRequest.payload berisi informasi utama khusus Actions on Google, termasuk JSON permintaan percakapan dari Asisten.
Kolom Conversation.conversationToken tidak didukung oleh permintaan webhook Dialogflow. Sebagai gantinya, fulfillment Anda dapat menggunakan konteks Dialogflow untuk mempertahankan data selama masa aktif percakapan.

Contoh permintaan panggilan sederhana

Cuplikan di bawah ini menunjukkan contoh permintaan pemanggilan dalam format webhook 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}"
}

Contoh permintaan percakapan sederhana

Cuplikan di bawah ini menunjukkan contoh permintaan percakapan dalam format webhook Dialogflow, dengan input pengguna berupa 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 helper

Cuplikan di bawah ini menunjukkan contoh hasil helper dalam format webhook Dialogflow. Contoh ini menunjukkan respons pengguna setelah webhook menunjukkan kepada Asisten bahwa 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 berupa application/json.

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

Saat berkomunikasi dengan Asisten, respons Anda biasanya berisi objek payload yang mengenkapsulasi objek "google". Objek payload "google" mencakup informasi khusus Actions on Google. Kolom ini harus berisi, minimum, kolom expectUserResponse, dan kolom richResponse atau systemIntent.

Kolom utama untuk objek payload "google" dirangkum di bawah:

Kolom	Deskripsi
`expectUserResponse`	Menunjukkan apakah fulfillment Anda mengharapkan respons pengguna. Tetapkan nilai ke `true` kapan harus mempertahankan percakapan dan `false` untuk mengakhiri percakapan.
`userStorage`	Menyimpan data persisten yang terkait dengan pengguna tertentu. Total penyimpanan adalah 10.000 byte.
`richResponse`	Kolom ini berisi audio, teks, kartu, saran, atau data terstruktur untuk dirender oleh Asisten. Untuk mempelajari lebih lanjut cara menggunakan respons kaya untuk Actions on Google, lihat Respons kaya
`systemIntent`	Kolom ini memiliki struktur yang sama dengan `ExpectedInput.possibleIntents`. Respons Anda biasanya berisi `systemIntent` jika fulfillment Anda menggunakan intent bantuan. Kolom `possibleIntents` di `systemIntent` harus ditetapkan ke objek `ExpectedIntent`, dengan nama kolom `inputValueData` diubah menjadi `data`.

Dalam objek ExpectedIntent, Anda menetapkan nilai berikut:

intent: Nama intent untuk helper yang menunjukkan jenis informasi yang Anda inginkan untuk diberikan pengguna, dan
data: Spesifikasi nilai, yaitu string yang mendeskripsikan data yang diperlukan Asisten untuk menjalankan helper.

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

Daftar berikut merangkum string spesifikasi nilai untuk helper yang dapat Anda tetapkan 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"`	Memperoleh konfirmasi dari pengguna (misalnya, jawaban untuk 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 alur 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 sementara, atau lokasi akurat.
`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 format webhook Dialogflow.

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

Contoh helper

Cuplikan di bawah ini menunjukkan contoh penggunaan intent helper dalam format webhook Dialogflow. Dalam contoh ini, webhook Anda menggunakan intent helper actions.intent.OPTIONS untuk menginstruksikan Asisten agar mendapatkan pilihan 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 percakapan dan meminta pengguna membuat pilihan berdasarkan opsi yang diberikan. Setelah mengumpulkan semua input pengguna yang diperlukan, Asisten akan mengirimkan hasil helper ini kembali ke fulfillment Anda dalam permintaan webhook Dialogflow.

Cuplikan di bawah ini 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 mengakhiri percakapan

Cuplikan di bawah ini menunjukkan contoh respons sederhana untuk mengakhiri sesi percakapan dalam format webhook Dialogflow. Nilai expectUserResponse dari false dalam pesan respons memberi tahu Asisten bahwa tidak ada input pengguna lebih lanjut yang diharapkan dan harus mengakhiri percakapan saat ini.

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

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