Formaty webhooka Actions on Google (Dialogflow)

Ten dokument opisuje format webhooka do komunikacji między Actions on Google a usługą realizacji, która definiuje niestandardowy interfejs konwersacyjny.

Uwaga: jeśli masz serwer backendu Node.js, zdecydowanie zalecamy skorzystanie z biblioteki klienta Actions on Google Node.js, aby uprościć tworzenie webhooka. Biblioteka klienta udostępnia kod formatu webhooka. Jeśli wolisz wdrożyć własną implementację backendu bez korzystania z biblioteki klienta, Twój backend jest odpowiedzialny za przetwarzanie i przetwarzanie wiadomości JSON wysyłanych przez Actions on Google za pomocą metody POST HTTP.

Ważne jest, aby zrozumieć, w jaki sposób Actions on Google i realizacja zamówień korzystają z formatów webhooka Actions on Google:

• Jeśli chcesz uczestniczyć w rozmowach z Actions on Google, musisz zrealizować webhook, który może reagować na żądania HTTP z Actions on Google.
• Gdy użytkownicy wywołują Twoją akcję, Twoja realizacja otrzymuje HTTP POST z ładunkiem JSON opisującym żądanie użytkownika.
• Twoja kolejna realizacja jest odpowiedzialna za odczytanie parametrów z ładunku żądania, wygenerowanie odpowiedniej odpowiedzi w formacie JSON i wysłanie tej odpowiedzi do Asystenta.

Kluczowe warunki:

• Format webhooka Dialogflow: format ładunku JSON, gdy Actions on Google wywołuje realizację przez Dialogflow.
• Format webhooka rozmowy: format ładunku JSON, gdy Actions on Google wywołuje realizację przez pakiet SDK Actions.

Typy żądań

W tej tabeli znajdziesz podsumowanie typów żądań, które webhook może otrzymywać od Asystenta:

Typ	Opis	Przykłady JSON
Żądania wywołania	Wyrażenia użytkownika inicjujące rozmowę z Twoim wykonaniem lub zawierające precyzyjne linki (np. Porozmawiaj z osobistym szefem kuchni, aby znaleźć przepisy na obiad). Jeśli używasz Dialogflow, żądania te odpowiadają intencjom zdefiniowanym w sekcji Discovery w ustawieniach integracji Asystenta Google. W przypadku pakietu SDK Actions żądania te odpowiadają zamiarom określonym w pakiecie działań.	Dialogflow webhook z wątkami,
Prośby o rozmowę	Wyrażenia użytkowników w tej samej sesji po rozpoczęciu rozmowy z realizacją. W formacie webhooka rozmowy są nieprzetworzone odpowiedzi tekstowe odpowiadające intencjom actions.intent.TEXT, które zostały spełnione w poprzedniej turze.	Dialogflow webhook z wątkami,
Wyniki pomocniczego	Żądania wysyłane przez Asystenta do realizacji, gdy webhook poprosi o intencję pomocniczą w poprzednim etapie rozmowy, aby obsłużyć fragmenty rozmowy (na przykład actions.intent.OPTION i actions.intent.PERMISSION).	Dialogflow webhook z wątkami,

Prośby o rozmowę i ich odpowiedzi

W typowym scenariuszu interakcji w Actions on Google użytkownicy tworzą wyrażenie wywołujące działanie. Aby odpowiedzieć, Actions on Google znajduje realizację pasującą do działania wywołanego przez użytkownika i wysyła tam żądanie.

Gdy Actions on Google stwierdzi, że Twoja realizacja jest zgodna z wywołaniem użytkownika, rozpoczyna sesję rozmowy, wysyłając żądanie HTTP zawierające ładunek JSON z informacjami o żądaniu użytkownika do punktu końcowego realizacji. Twoja realizacja analizuje żądanie i zwraca odpowiedź zawierającą ładunek JSON. Actions on Google konwertuje ładunek na renderowane mowę i dane wyjściowe multimediów dla użytkowników.

Ilustracja 1. Actions on Google wywołujący realizację za pomocą pakietu SDK Actions.

Aby dowiedzieć się więcej o formacie ładunku JSON, gdy Actions on Google wywołuje Twoją realizację przez pakiet SDK Actions, przeczytaj artykuł Format webhooka rozmowy.

Żądania i odpowiedzi Dialogflow

Przy tworzeniu działań możesz opcjonalnie używać Dialogflow, aby uprościć zadanie tworzenia interfejsów konwersacyjnych. W tym scenariuszu Dialogflow działa jako pośrednia między Actions on Google a Twoją realizacją. Zamiast wysyłać żądanie HTTP/JSON bezpośrednio do punktu końcowego realizacji, Actions on Google wysyła je do Dialogflow.

Dialogflow umieszcza ładunek JSON w pierwotnym żądaniu w formacie webhook Dialogflow i przekazuje wynikowe żądanie do Dialogflow Dialogflow.

Analogicznie przy wysyłaniu odpowiedzi do Dialogflow ładunek JSON odpowiedzi musi być zgodny z formatem webhooka Dialogflow. Twoja realizacja analizuje parametry z żądania Dialogflow JSON i generuje odpowiedź w formacie webhooka Dialogflow. Dialogflow zamienia odpowiedź z Twojej realizacji na wiadomość zwrotną zrozumiałą dla Asystenta.

Ilustracja 2. Actions on Google wywołujący realizację za pomocą Dialogflow.

Więcej informacji o formacie ładunku JSON, gdy Actions on Google wywołuje realizację przez Dialogflow, znajdziesz w artykule Format webhooka Dialogflow.