Bagian ini menjelaskan format payload JSON saat Actions on Google memanggil fulfillment melalui Actions SDK.
Setelah dimulai, percakapan akan diidentifikasi oleh conversationId
unik. Untuk setiap pengguna berikutnya
kueri ke Asisten, fulfillment Anda akan menerima intent yang
yang harus diproses dan direspons oleh webhook Anda. conversationId
ini disimpan dalam setiap permintaan dan
pasangan respons hingga percakapan berakhir.
Isi permintaan
Saat pengguna membuat kueri awal atau memberikan beberapa input berikutnya, Asisten akan mengirimkan permintaan dengan {i>fulfillment<i} Anda. Permintaan webhook percakapan dari Asisten berisi data seperti intent yang dipicu, teks mentah pengguna input, dan kemampuan permukaan perangkat pengguna.
Kolom utama untuk permintaan dalam format webhook percakapan dirangkum di bawah:
Kolom | Deskripsi |
---|---|
isInSandbox |
Variabel boolean ini terutama digunakan untuk fitur
transaksi, untuk menunjukkan apakah webhook Anda harus menangani permintaan ini dalam mode sandbox. Dalam mode sandbox, webhook Anda tidak boleh menagih atau memenuhi pesanan pembelian apa pun oleh pengguna.
Secara default, nilai ini ditetapkan ke "true ". |
surface |
Informasi tentang platform Asisten yang berinteraksi dengan pengguna dan kemampuannya. |
Inputs |
Informasi tentang permintaan pemanggilan. Untuk pemanggilan pemicu, ini mencakup intent yang memetakan ke suatu tindakan. Untuk berikutnya permintaan dalam percakapan, objek ini juga dapat 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 yang persisten selama masa aktif percakapan. |
availableSurfaces |
Informasi ini digunakan untuk percakapan multi-platform. |
Contoh permintaan pemanggilan sederhana
Cuplikan di bawah menunjukkan contoh permintaan pemanggilan 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 ini menunjukkan contoh permintaan percakapan dalam format webhook percakapan, dengan input pengguna adalah string teks (misalnya, “Angka keberuntungan saya adalah 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 application/json
.
Respons di format webhook percakapan berisi data seperti UI yang sebenarnya untuk menampilkan pengguna (termasuk komponen audio dan visual), dan maksud yang dapat dipicu dalam permintaan berikutnya (disebut intent yang diharapkan). Diharapkan intent 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 yang ditampilkan di Asisten, lihat Dokumentasi Respons.
Contoh respons sederhana
Cuplikan di bawah ini menunjukkan contoh respons sederhana dalam percakapan format webhook.
{ "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 bantuan
Cuplikan di bawah ini menunjukkan contoh penggunaan intent bantuan dalam percakapan
format webhook. 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 tentang penggunaan intent bantuan, lihat Panduan bantuan.
{ "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 akhir percakapan
Cuplikan di bawah ini menunjukkan contoh respons sederhana untuk mengakhiri percakapan dalam format respons webhook percakapan.
expectedUserResponse
nilai false
dalam pesan respons memberi sinyal kepada Asisten bahwa tidak ada pengguna lagi
input sebelumnya yang diharapkan dan tindakan ini akan mengakhiri percakapan saat ini. Tujuan
finalResponse
nilai menunjukkan apa yang akan ditampilkan atau dihasilkan oleh Asisten kepada pengguna sebelum
percakapan berakhir.
{ "expectUserResponse": false, "finalResponse": { "richResponse": { "items": [ { "simpleResponse": { "textToSpeech": "Good bye" } } ] } } }
Untuk mempelajari cara mengganti perilaku default saat pengguna memanggil perintah untuk mengakhiri percakapan dengan Asisten, lihat Keluar dari percakapan.