Bagian ini menjelaskan format payload JSON saat Actions on Google memanggil fulfillment Anda melalui Actions SDK.
Setelah dimulai, percakapan diidentifikasi oleh conversationId
unik. Untuk setiap kueri pengguna
berikutnya ke Asisten, fulfillment Anda akan menerima intent yang
harus diproses dan direspons oleh webhook Anda. conversationId
ini dipertahankan di setiap pasangan permintaan dan
respons hingga percakapan berakhir.
Isi permintaan
Saat pengguna membuat kueri awal atau memberikan beberapa input berikutnya, Asisten akan mengirimkan permintaan ke fulfillment Anda. Permintaan webhook percakapan dari Asisten berisi data seperti intent yang dipicu, teks mentah dari input pengguna, dan kemampuan platform perangkat pengguna.
Kolom utama untuk permintaan dalam format webhook percakapan dirangkum di bawah:
Kolom | Deskripsi |
---|---|
isInSandbox |
Variabel boolean ini terutama digunakan untuk fitur
transaksi, guna menunjukkan apakah webhook Anda harus menangani permintaan ini di mode
sandbox. Dalam mode sandbox, webhook Anda tidak boleh menagih atau memenuhi pesanan pembelian apa pun yang dilakukan pengguna.
Secara default, opsi ini disetel ke "true ". |
surface |
Informasi tentang Asisten menunjukkan interaksi pengguna dan kemampuannya. |
Inputs |
Informasi tentang permintaan pemanggilan. Untuk pemanggilan pemicu, ini mencakup intent yang memetakan ke tindakan. Untuk permintaan berikutnya dalam percakapan, objek ini mungkin juga menyertakan argumen yang sesuai dengan input yang diharapkan yang ditentukan oleh fulfillment Anda. |
User |
Informasi tentang pengguna yang memulai permintaan. Informasi ini mencakup izin yang diberikan oleh pengguna dan lokalitas pengguna. |
Conversation |
Informasi tentang konteks percakapan, termasuk ID percakapan, jenisnya (misalnya, apakah permintaan ini memulai percakapan baru), dan token percakapan untuk menyimpan data persisten selama masa aktif percakapan. |
availableSurfaces |
Informasi ini digunakan untuk percakapan multi-platform. |
Contoh permintaan panggilan sederhana
Cuplikan di bawah menunjukkan contoh permintaan panggilan dalam format webhook percakapan.
{ "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" } ] } ] }
Contoh permintaan percakapan sederhana
Cuplikan di bawah menunjukkan contoh permintaan percakapan dalam format webhook percakapan, dengan input pengguna adalah string teks (misalnya, “Angka keberuntungan saya 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" } ] } ] }
Isi respons
Content-Type
di header postingan HTTP dari endpoint fulfillment
Anda ke Asisten harus berupa application/json
.
Respons dalam format webhook percakapan berisi data seperti UI yang sebenarnya untuk menampilkan pengguna (termasuk komponen audio dan visual), dan intent yang dapat dipicu dalam permintaan berikutnya (disebut intent yang diharapkan). Intent yang diharapkan dapat berupa intent apa pun yang dipahami Asisten, seperti yang dijelaskan dalam referensi API Intent.
Untuk mempelajari lebih lanjut cara memformat antarmuka pengguna untuk respons Anda saat ditampilkan di Asisten, lihat dokumentasi Respons.
Contoh respons sederhana
Cuplikan di bawah ini menunjukkan contoh respons sederhana dalam format webhook percakapan.
{ "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?" } } ] } } } ] }
Contoh helper
Cuplikan di bawah ini menunjukkan contoh penggunaan intent helper dalam format
webhook percakapan. Dalam contoh ini, webhook menggunakan intent helper
actions.intent.OPTIONS
untuk menginstruksikan Asisten agar mendapatkan
pilihan pengguna di antara beberapa opsi.
Untuk mempelajari lebih lanjut cara menggunakan intent helper, lihat panduan Helper.
{ "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" } ] } } } ] }
Contoh mengakhiri percakapan
Cuplikan di bawah ini menunjukkan contoh respons sederhana untuk mengakhiri sesi percakapan dalam format respons webhook percakapan.
Nilai expectedUserResponse
dari false
dalam pesan respons memberi tahu Asisten bahwa tidak ada input
pengguna lebih lanjut yang diharapkan dan harus mengakhiri percakapan saat ini. Nilai
finalResponse
menunjukkan apa yang harus ditampilkan atau dihasilkan Asisten kepada pengguna sebelum
percakapan berakhir.
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "simpleResponse": { "textToSpeech": "Good bye" } } ] } } }
Untuk mempelajari cara mengganti perilaku default saat pengguna memanggil frasa standar untuk mengakhiri percakapan dengan Asisten, lihat Percakapan keluar.