Bu bölümde, Actions on Google'ın Actions SDK aracılığıyla karşılamanızı çağırdığı durumlardaki JSON yükünün biçimi açıklanmaktadır.
Bir görüşme başladıktan sonra benzersiz bir conversationId ile tanımlanır. Asistan'a gönderilen her kullanıcı sorgusu için istek karşılamanız, webhook'unuzun işlemesi ve yanıt vermesi gereken bir niyet alır. Bu conversationId, görüşme sona erene kadar her istek ve yanıt çiftinde korunur.
İstek içeriği
Kullanıcılar ilk sorguda bulunduğunda veya ardından başka bir giriş yaptığında Asistan, istek karşılama mantığınıza bir istek gönderir. Asistan'dan gelen sohbet webhook istekleri tetiklenen amaç, kullanıcı girişinin ham metni ve kullanıcı cihazının yüzey özellikleri gibi veriler içerir.
Görüşme webhook'u biçimindeki bir istek için önemli alanlar aşağıda özetlenmiştir:
| Alan | Açıklama |
|---|---|
isInSandbox |
Bu boole değişkeni, webhook'unuzun bu isteği korumalı alan modunda işlemesinin gerekip gerekmediğini belirtmek amacıyla öncelikli olarak
işlemler özelliği için kullanılır. Korumalı alan modunda webhook'unuz kullanıcılardan ücret almamalı veya satın alma siparişlerini yerine getirmemelidir.
Varsayılan olarak "true" şeklinde ayarlanmıştır. |
surface |
Kullanıcının etkileşimde bulunduğu Asistan yüzeyi ve yetenekleriyle ilgili bilgiler. |
Inputs |
Çağrı isteği hakkında bilgi. Tetikleme için buna, bir işlemle eşlenen bir niyet dahildir. Bir görüşmede takip eden istekler için bu nesne, istek karşılama mantığınız tarafından belirtilen beklenen girişlere karşılık gelen bağımsız değişkenler de içerebilir. |
User |
İsteği başlatan kullanıcı hakkında bilgiler. Bu bilgiler arasında kullanıcı tarafından verilen izinler ve kullanıcının yerel ayarı bulunur. |
Conversation |
Görüşme kimliği, tür (örneğin, bu isteğin yeni bir görüşme başlatıp başlatmadığı) ve görüşme ömrü boyunca kalıcı verileri depolamak için bir görüşme jetonu da dahil olmak üzere görüşme bağlamıyla ilgili bilgiler. |
availableSurfaces |
Bu bilgiler, çok yüzeyli görüşmeler için kullanılır. |
Basit çağrı isteği örneği
Aşağıdaki snippet'te görüşme webhook'u biçiminde bir çağrı isteği örneği gösterilmektedir.
{
"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"
}
]
}
]
}
Basit sohbet isteği örneği
Aşağıdaki snippet'te sohbet webhook'u biçiminde bir görüşme isteği örneği gösterilmektedir. Bu örnekte kullanıcı girişi bir metin dizesidir (örneğin, "Şanslı sayım 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"
}
]
}
]
}
Yanıt gövdesi
Karşılama uç noktanızdan Asistan'a giden HTTP yayınlarının başlığındaki Content-Type, application/json olmalıdır.
Görüşme webhook'u biçimindeki yanıt, kullanıcıyı göstermek için kullanılan gerçek kullanıcı arayüzü (işitsel ve görsel bileşenler dahil) ve sonraki istekte tetiklenebilen amaç (beklenen amaç olarak adlandırılır) gibi verileri içerir. Beklenen niyet, Intents API referansında açıklandığı gibi Asistan'ın anladığı amaçlardan herhangi biri olabilir.
Yanıtlarınız Asistan'da görüntülendiğinde kullanıcı arayüzünü biçimlendirme hakkında daha fazla bilgi edinmek için Yanıtlar dokümanlarına bakın.
Basit yanıt örneği
Aşağıdaki snippet'te sohbet web kancası biçiminde basit bir yanıt örneği gösterilmektedir.
{
"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?"
}
}
]
}
}
}
]
}
Yardımcı örneği
Aşağıdaki snippet'te, görüşme webhook biçiminde yardımcı amacı kullanmaya ilişkin bir örnek gösterilmektedir. Bu örnekte webhook, Asistan'a birden fazla seçenek arasından bir kullanıcı seçimi alması talimatını vermek için actions.intent.OPTIONS yardımcı niyetini kullanmaktadır.
Yardımcı amaçları kullanma hakkında daha fazla bilgi edinmek için Yardımcılar kılavuzuna bakın.
{
"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"
}
]
}
}
}
]
}
Görüşmeyi sonlandırma örneği
Aşağıdaki snippet'te, görüşme webhook'u yanıt biçiminde bir görüşme oturumunu sonlandırmak için kullanılabilecek basit bir yanıt örneği gösterilmektedir.
Yanıt mesajındaki expectedUserResponse
false
değeri, Asistan'a başka kullanıcı girişi beklenmeyen ve
mevcut sohbeti sonlandırması gerektiğini belirtir. finalResponse değeri, Asistan'ın görüşme sona ermeden önce kullanıcıya ne göstermesi veya çıkış vermesi gerektiğini ifade eder.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Good bye"
}
}
]
}
}
}
Kullanıcılar Asistan'la görüşmelerini sonlandırmak için standart bir kelime öbeği çağırdığında varsayılan davranışı nasıl geçersiz kılacağınızı öğrenmek için Sohbet çıkışları bölümüne bakın.