Format webhook percakapan {:#conversation-webhook-format} (Dialogflow)

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.

Catatan: Respons Anda harus muncul dalam 10 detik. Jika tidak, Asisten akan menganggap waktu fulfillment Anda telah habis dan mengakhiri percakapan Anda.

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.

Catatan: Dalam respons webhook, biasanya Anda akan menentukan actions.intent.TEXT sebagai intent yang diharapkan. Intent ini mewakili respons teks mentah dari pengguna. Fungsi ask() generik di library klien mengharapkan intent ini.

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.