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

Ta sekcja opisuje format ładunku JSON, gdy Actions on Google wywołuje Twoją za pomocą pakietu SDK Actions.

Po rozpoczęciu rozmowy jest identyfikowany przez unikalny conversationId. Dla każdego kolejnego użytkownika do Asystenta, Twoja realizacja otrzyma zamiar, który webhook musi przetworzyć dane i na nie zareagować. Ten plik conversationIdjest utrwalony w każdym żądaniu, do zakończenia rozmowy.

Treść żądania

Gdy użytkownik sformułuje pierwsze zapytanie lub wpisze jakieś kolejne zapytanie, Asystent wyśle prośbę o połączenie. do realizacji transakcji. Żądania webhooka rozmowy z Asystenta zawierają dane takie jak wywołana intencja czy nieprzetworzony tekst użytkownika i możliwości, jakie daje urządzenie użytkownika.

Podsumowanie najważniejszych pól żądania w formacie webhooka rozmowy:

Pole Opis
isInSandbox Ta zmienna logiczna jest używana głównie do transakcji, aby wskazać, czy webhook powinien obsługiwać to żądanie w trybie piaskownicy i trybu uzyskiwania zgody. W trybie piaskownicy Twój webhook nie powinien obciążać użytkowników ani realizować żadnych zamówień zakupu. Domyślna wartość to „true”.
surface Informacje o platformie Asystenta, z którą użytkownik wchodzi w interakcję, oraz o jej możliwościach.
Inputs Informacje o żądaniu wywołania. W przypadku wywołania wyzwalającego obejmuje to element intent, który odzwierciedla działanie. Kolejne żądań w wątku, ten obiekt może również zawierać argumenty odpowiadające argumentowi oczekiwane dane wejściowe określone w realizacji.
User Informacje o użytkowniku, który wysłał żądanie. Te informacje obejmują uprawnienia zgodnie z ustawieniami regionalnymi użytkownika i jego ustawieniami regionalnymi.
Conversation informacje o kontekście rozmowy, w tym jej identyfikator i typ; (na przykład czy to żądanie inicjuje nowy wątek) i token rozmowy do przechowywania trwałych danych przez cały okres trwania rozmowy.
availableSurfaces Te informacje są używane do: do prowadzenia rozmów z różnymi platformami.

Przykład prostego żądania wywołania

Fragment kodu poniżej 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 zawiera przykład żądania konwersacyjnego w formacie webhooka rozmowy: gdzie dane wejściowe użytkownika to ciąg tekstowy (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 format webhooka rozmowy zawiera dane takie jak rzeczywisty interfejs użytkownika, który pokazuje użytkownika (w tym komponentów dźwiękowych i wizualnych) oraz intencji, aktywowanych w kolejnym żądaniu (nazywanym oczekiwaną intencją). Oczekiwany intencją mogą być dowolne intencje rozumiene przez Asystenta, zgodnie z opisem w dokumentacji interfejsu API Intents.

Aby dowiedzieć się więcej o formatowaniu interfejsu użytkownika, gdy: wyświetlane w Asystencie, zobacz Odpowiedzi.

Przykład prostej odpowiedzi

Fragment poniżej zawiera przykładową prostą odpowiedź w rozmowie webhooka.

{
  "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 Asystenta

Fragment kodu poniżej pokazuje przykład użycia intencji pomocniczej w rozmowie webhooka. W tym przykładzie webhook używa funkcji actions.intent.OPTIONS ma zamiar poinstruować Asystenta, że ma uzyskać do wyboru wielu opcji.

Aby dowiedzieć się więcej o korzystaniu z intencji pomocniczych, przeczytaj Przewodnik 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 kończenia rozmowy

Fragment kodu poniżej to przykład prostej odpowiedzi na zakończenie rozmowy .

expectedUserResponse wartość false w wiadomości z odpowiedzią informuje Asystenta, że nie będzie już dane wejściowe są prawidłowe i powinny zakończyć bieżący wątek. finalResponse wskazuje, co Asystent powinien wyświetlić lub wyświetlić użytkownikowi przed rozmowa dobiegnie końca.

{
  "expectUserResponse": false,
  "finalResponse": {
    "richResponse": {
      "items": [
        {
          "simpleResponse": {
            "textToSpeech": "Good bye"
          }
        }
      ]
    }
  }
}

Informacje o zastępowaniu domyślnego działania, gdy użytkownicy wywołują standardowe działanie aby zakończyć rozmowę z Asystentem, zobacz Wyjścia rozmów.