W tej sekcji opisano format ładunku JSON, gdy Actions on Google wywołuje Twoją realizację za pomocą pakietu SDK Actions.
Po rozpoczęciu rozmowy jest identyfikowany przez unikalny identyfikator conversationId. W przypadku każdego kolejnego zapytania użytkownika wysyłanego do Asystenta Twoja realizacja otrzymuje intencję, którą musi przetworzyć webhook i na niego odpowiedzieć. Ten parametr conversationId jest zachowywany w każdej parze żądania i odpowiedzi do momentu zakończenia rozmowy.
Treść żądania
Gdy użytkownicy wykonują wstępne zapytanie lub podają dodatkowe dane, Asystent wysyła żądanie do Twojej realizacji. Żądania webhooka rozmowy przesyłane przez Asystenta zawierają takie dane jak wywołana intencja, nieprzetworzony tekst danych wejściowych użytkownika i możliwości interfejsu urządzenia użytkownika.
Podsumowanie najważniejszych pól żądania w formacie webhooka rozmowy:
| Pole | Opis |
|---|---|
isInSandbox |
Ta zmienna logiczna służy przede wszystkim do funkcji
transakcji, aby wskazywać, czy webhook ma obsługiwać to żądanie w trybie piaskownicy. W trybie piaskownicy Twój webhook nie powinien naliczać żadnych opłat za zamówienia użytkowników ani ich realizować.
Domyślna wartość to „true”. |
surface |
Informacje o interfejsie Asystenta, z którym użytkownik wchodzi w interakcję, i o jego funkcjach. |
Inputs |
Informacje o żądaniu wywołania. W przypadku wywołania aktywującego obejmuje to intent mapowany na działanie. W przypadku kolejnych żądań w wątku ten obiekt może też zawierać argumenty odpowiadające oczekiwanym danym wejściowych określonym przez realizację. |
User |
Informacje o użytkowniku, który wysłał żądanie. Informacje te obejmują uprawnienia przyznane przez użytkownika oraz jego język. |
Conversation |
Informacje o kontekście rozmowy, w tym identyfikator, typ (np. czy żądanie inicjuje nową rozmowę) oraz token rozmowy do przechowywania trwałych danych przez cały okres trwania rozmowy. |
availableSurfaces |
Te informacje są używane w rozmowach na wielu powierzchniach. |
Przykład prostego żądania wywołania
Poniższy fragment kodu zawiera przykład żądania wywołania w formacie webhooka rozmowy.
{
"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"
}
]
}
]
}
Przykład prostej prośby o rozmowę
Poniższy fragment kodu przedstawia przykład żądania konwersacyjnego w formacie webhooka rozmowy, w którym dane wejściowe użytkownika są ciągiem tekstowym (np. „Moja szczęśliwa liczba to 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"
}
]
}
]
}
Treść odpowiedzi
Content-Type w nagłówku postów HTTP z punktu końcowego realizacji do Asystenta musi mieć wartość application/json.
Odpowiedź w formacie webhooka rozmowy zawiera dane takie jak rzeczywisty interfejs wyświetlany użytkownikowi (w tym komponenty dźwiękowe i wizualne) oraz intencja, która może zostać wywołana w kolejnym żądaniu (tzw. oczekiwana intencja). Oczekiwany zamiar może obejmować dowolną intencję zrozumiałą dla Asystenta. Opisaliśmy to w dokumentacji interfejsu Intents API.
Więcej informacji o formatowaniu odpowiedzi wyświetlanych w Asystencie w interfejsie znajdziesz w dokumentacji Odpowiedzi.
Przykład prostej odpowiedzi
Poniższy fragment kodu zawiera przykład prostej odpowiedzi w formacie webhooka rozmowy.
{
"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?"
}
}
]
}
}
}
]
}
Przykład aplikacji pomocniczej
Fragment kodu poniżej zawiera przykład użycia intencji pomocniczej w formacie webhooka rozmowy. W tym przykładzie webhook korzysta z intencji pomocniczej actions.intent.OPTIONS, aby nakazać Asystentowi uzyskanie przez użytkownika wyboru między wieloma opcjami.
Więcej informacji o korzystaniu z intencji pomocniczych znajdziesz w przewodniku dla pomocników.
{
"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"
}
]
}
}
}
]
}
Przykład strony Zakończ rozmowę
Poniższy fragment kodu zawiera przykład prostej odpowiedzi na zakończenie sesji rozmowy w formacie odpowiedzi webhooka rozmowy.
Wartość parametru expectedUserResponse w polu false w wiadomości z odpowiedzią informuje Asystenta, że nie powinno się nic więcej robić w tej sprawie i że powinna zakończyć bieżącą rozmowę. Wartość finalResponse wskazuje, co Asystent powinien wyświetlić lub wypisać użytkownikowi przed zakończeniem rozmowy.
{
"expectUserResponse": false,
"finalResponse": {
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "Good bye"
}
}
]
}
}
}
Informacje o tym, jak zastąpić domyślne zachowanie, gdy użytkownicy wywołują standardowe wyrażenie w celu zakończenia rozmowy z Asystentem, znajdziesz w sekcji Zakończenie rozmowy.