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

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.