Para usar o fulfillment em um sistema de produção, é necessário implementar e implantar um serviço de webhook. Para processar o fulfillment, o serviço de webhook precisa aceitar solicitações JSON e retornar respostas JSON, conforme especificado neste guia. O fluxo de processamento detalhado para fulfillment e webhooks é descrito no documento de visão geral do fulfillment.
Requisitos de serviço do webhook
Seu serviço de webhook precisa atender aos seguintes requisitos:
- Processar solicitações HTTPS. O HTTP não é compatível. Se você hospedar seu serviço de webhook no Google Cloud usando uma solução de computação ou de computação sem servidor, consulte a documentação do produto para veiculação com HTTPS. Para outras opções de hospedagem, consulte Gerar um certificado SSL para seu domínio.
- Verifique se o URL do serviço de webhook está acessível publicamente.
- Processar solicitações POST com um corpo JSON
WebhookRequest. - Responda às solicitações
WebhookRequestcom um corpo JSONWebhookResponse.
Autenticação
| X | Item |
|---|---|
| Nome de usuário e senha de login | Para as configurações de webhook, é possível especificar valores opcionais de nome de usuário e senha de login. Se fornecido, o Dialogflow adiciona um cabeçalho HTTP de autorização às solicitações de webhook. Esse cabeçalho está no formato: "authorization: Basic <base 64 encoding of the string username:password>". |
| Cabeçalhos de autenticação | Para as configurações de webhook, é possível especificar pares de chave-valor opcionais de cabeçalho HTTP. Se fornecidos, o Dialogflow adiciona esses cabeçalhos HTTP às solicitações de webhook. É comum fornecer um único par com uma chave de authorization. |
| Autenticação integrada do Cloud Run functions | É possível usar a autenticação integrada ao usar as funções do Cloud Run. Para usar esse tipo de autenticação, não forneça nome de usuário, senha ou cabeçalhos de autorização. Se você fornecer algum desses campos, eles não serão usados para a autenticação integrada. |
| Tokens de identidade de serviço | É possível usar tokens de identidade de serviço para autenticação. Se você não fornecer um nome de usuário, uma senha de login ou um cabeçalho com uma chave de authorization, o Dialogflow vai presumir automaticamente que os tokens de identidade de serviço precisam ser usados e vai adicionar um cabeçalho HTTP de autorização às solicitações de webhook. Esse cabeçalho está no formato: "authorization: Bearer <identity token>". |
| Autenticação TLS mútua | Consulte a documentação sobre autenticação TLS mútua. |
Solicitação de webhook
Quando uma intent configurada para fulfillment é correspondida, o Dialogflow envia uma solicitação de webhook HTTPS POST ao seu serviço de webhook. O corpo dessa solicitação é um objeto JSON com informações sobre a intent correspondente.
Além da consulta do usuário final, muitas integrações também enviam informações
sobre o usuário final. Por exemplo, um ID que identifica o usuário de forma exclusiva. Essas
informações podem ser acessadas usando o campo originalDetectIntentRequest na
solicitação de webhook, que contém as informações enviadas pela plataforma de
integração.
Para saber mais, consulte a documentação de referência do WebhookRequest.
Confira este exemplo de solicitação:
{
"responseId": "response-id",
"session": "projects/project-id/agent/sessions/session-id",
"queryResult": {
"queryText": "End-user expression",
"parameters": {
"param-name": "param-value"
},
"allRequiredParamsPresent": true,
"fulfillmentText": "Response configured for matched intent",
"fulfillmentMessages": [
{
"text": {
"text": [
"Response configured for matched intent"
]
}
}
],
"outputContexts": [
{
"name": "projects/project-id/agent/sessions/session-id/contexts/context-name",
"lifespanCount": 5,
"parameters": {
"param-name": "param-value"
}
}
],
"intent": {
"name": "projects/project-id/agent/intents/intent-id",
"displayName": "matched-intent-name"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en"
},
"originalDetectIntentRequest": {}
}
Resposta do webhook
Depois que o webhook recebe uma solicitação, ele precisa enviar uma resposta. O corpo dessa resposta é um objeto JSON que contém as seguintes informações:
- A resposta que o Dialogflow retorna ao usuário final.
- Atualizações para contextos ativos para a conversa.
- Um evento de acompanhamento para acionar uma correspondência de intent.
- Um payload personalizado a ser enviado para a integração ou o cliente de intent de detecção.
As seguintes limitações se aplicam à sua resposta:
- Responda em até 10 segundos para aplicativos do Google Assistente ou em até 5 segundos para outros aplicativos. Caso contrário, a solicitação vai expirar.
- Mantenha o tamanho da resposta em 64 KiB ou menos.
Para saber mais, consulte a documentação de referência do WebhookResponse.
Resposta de texto
Veja a seguir um exemplo de resposta de texto:
{
"fulfillmentMessages": [
{
"text": {
"text": [
"Text response from webhook"
]
}
}
]
}
Resposta do card
Veja a seguir um exemplo de resposta de card:
{
"fulfillmentMessages": [
{
"card": {
"title": "card title",
"subtitle": "card text",
"imageUri": "https://example.com/images/example.png",
"buttons": [
{
"text": "button text",
"postback": "https://example.com/path/for/end-user/to/follow"
}
]
}
}
]
}
Resposta do Google Assistente
Veja a seguir um exemplo de resposta do Google Assistente:
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "this is a Google Assistant response"
}
}
]
}
}
}
}
Contexto
Veja a seguir um exemplo que define o contexto de saída:
{
"fulfillmentMessages": [
{
"text": {
"text": [
"Text response from webhook"
]
}
}
],
"outputContexts": [
{
"name": "projects/project-id/agent/sessions/session-id/contexts/context-name",
"lifespanCount": 5,
"parameters": {
"param-name": "param-value"
}
}
]
}
Evento
Veja um exemplo que invoca um evento personalizado:
{
"followupEventInput": {
"name": "event-name",
"languageCode": "en-US",
"parameters": {
"param-name": "param-value"
}
}
}
Entidade de sessão
Veja a seguir um exemplo que define uma entidade de sessão:
{
"fulfillmentMessages": [
{
"text": {
"text": [
"Choose apple or orange"
]
}
}
],
"sessionEntityTypes":[
{
"name":"projects/project-id/agent/sessions/session-id/entityTypes/fruit",
"entities":[
{
"value":"APPLE_KEY",
"synonyms":[
"apple",
"green apple",
"crabapple"
]
},
{
"value":"ORANGE_KEY",
"synonyms":[
"orange"
]
}
],
"entityOverrideMode":"ENTITY_OVERRIDE_MODE_OVERRIDE"
}
]
}
Payload personalizado
Veja um exemplo que fornece um payload personalizado:
{
"fulfillmentMessages": [
{
"payload": {
"facebook": { // for Facebook Messenger integration
"attachment": {
"type": "",
"payload": {}
}
},
"slack": { // for Slack integration
"text": "",
"attachments": []
},
"richContent": [ // for Dialogflow Messenger integration
[
{
"type": "image",
"rawUrl": "https://example.com/images/logo.png",
"accessibilityText": "Example logo"
}
]
],
// custom integration payload here
}
}
]
}
Ativar e gerenciar o fulfillment
Para ativar e gerenciar o preenchimento de seu agente com o console:
- Acesse o console do Dialogflow ES.
- Selecione um agente.
- Selecione Fulfillment no menu da barra lateral.
- Alterne o campo Webhook para Ativado.
- Forneça os detalhes do serviço de webhook no formulário. Se o webhook não exigir autenticação, deixe os campos de autenticação em branco.
- Clique em Salvar.
Para ativar e gerenciar o fulfillment do agente com a API, consulte a
referência do agente. Os métodos getFulfillment e updateFulfillment permitem gerenciar as configurações de fulfillment.
Para ativar o fulfillment para uma intent com o console:
- Selecione Intents no menu da barra lateral à esquerda.
- Selecione uma intent.
- Acesse a seção Fulfillment.
- Ative a opção Ativar chamada de webhook para esta intent.
- Clique em Salvar.
Para ativar o fulfillment de uma intent com a API, consulte a
referência de intents e defina o
campo webhookState como WEBHOOK_STATE_ENABLED.
Erros de webhook
Se o serviço de webhook encontrar um erro, ele vai retornar um dos seguintes códigos de status HTTP:
400: solicitação inválida401: não autorizado403: proibido404: não encontrado500: erro interno do servidor503: serviço indisponível
Em qualquer uma das seguintes situações de erro, o Dialogflow responde ao usuário final com a resposta integrada configurada para a intent correspondente:
- O tempo limite de resposta foi excedido.
- Um código de status de erro foi recebido.
- A resposta é inválida.
- O serviço de webhook está indisponível.
Além disso, se uma chamada de API de detecção de intent
acionar a correspondência de intent, o campo status na resposta de detecção de intent
vai conter as informações de erro do webhook. Exemplo:
"status": {
"code": 206,
"message": "Webhook call failed. <details of the error...>"
}
Novas tentativas automáticas
O Dialogflow ES inclui mecanismos internos que repetem automaticamente determinados erros de webhook para melhorar a robustez. Somente erros não terminais são repetidos, como erros de tempo limite ou de conexão.
Para reduzir a probabilidade de chamadas duplicadas:
- Defina limites de tempo limite de webhook mais longos.
- Ofereça suporte à idempotência na lógica do webhook ou elimine a duplicação de solicitações.
Como usar o Cloud Run functions
É possível usar as funções do Cloud Run para fulfillment de várias maneiras. O editor inline do Dialogflow é integrado ao Cloud Run functions. Quando você usa o editor in-line para criar e editar o código do webhook, o Dialogflow estabelece uma conexão segura com a função do Cloud.
Também é possível usar uma função do Cloud que não foi criada pelo editor in-line. Se a função do Cloud estiver no mesmo projeto que o agente, ele poderá chamar o webhook sem precisar de nenhuma configuração especial.
No entanto, é necessário configurar manualmente essa integração nas duas situações a seguir:
- A conta de serviço
do agente de serviço do Dialogflow
com o endereço a seguir precisa existir para o projeto de agente:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
- Crie um novo agente para o projeto.
- Execute o seguinte comando:
gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
- Se a função de webhook estiver em um projeto diferente do agente, você precisará fornecer o papel do IAM de Invocador do Cloud Functions à conta de serviço do Agente de serviço do Dialogflow no projeto da função.
Tokens de identidade de serviço
Quando o Dialogflow chama um webhook, ele fornece um
token de identidade do Google
com a solicitação. Qualquer webhook pode validar o token usando as bibliotecas de cliente do Google ou de código aberto, como github.com/googleapis/google-auth-library-nodejs.
Por exemplo, verifique o email do token de ID como:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Amostras
Os exemplos a seguir mostram como receber um WebhookRequest e enviar um
WebhookResponse. Esses exemplos usam intents criadas no
guia de início rápido.
Go
Para autenticar na Dialogflow CX, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
import (
"encoding/json"
"fmt"
"log"
"net/http"
)
type intent struct {
DisplayName string `json:"displayName"`
}
type queryResult struct {
Intent intent `json:"intent"`
}
type text struct {
Text []string `json:"text"`
}
type message struct {
Text text `json:"text"`
}
// webhookRequest is used to unmarshal a WebhookRequest JSON object. Note that
// not all members need to be defined--just those that you need to process.
// As an alternative, you could use the types provided by
// the Dialogflow protocol buffers:
// https://godoc.org/google.golang.org/genproto/googleapis/cloud/dialogflow/v2#WebhookRequest
type webhookRequest struct {
Session string `json:"session"`
ResponseID string `json:"responseId"`
QueryResult queryResult `json:"queryResult"`
}
// webhookResponse is used to marshal a WebhookResponse JSON object. Note that
// not all members need to be defined--just those that you need to process.
// As an alternative, you could use the types provided by
// the Dialogflow protocol buffers:
// https://godoc.org/google.golang.org/genproto/googleapis/cloud/dialogflow/v2#WebhookResponse
type webhookResponse struct {
FulfillmentMessages []message `json:"fulfillmentMessages"`
}
// welcome creates a response for the welcome intent.
func welcome(request webhookRequest) (webhookResponse, error) {
response := webhookResponse{
FulfillmentMessages: []message{
{
Text: text{
Text: []string{"Welcome from Dialogflow Go Webhook"},
},
},
},
}
return response, nil
}
// getAgentName creates a response for the get-agent-name intent.
func getAgentName(request webhookRequest) (webhookResponse, error) {
response := webhookResponse{
FulfillmentMessages: []message{
{
Text: text{
Text: []string{"My name is Dialogflow Go Webhook"},
},
},
},
}
return response, nil
}
// handleError handles internal errors.
func handleError(w http.ResponseWriter, err error) {
w.WriteHeader(http.StatusInternalServerError)
fmt.Fprintf(w, "ERROR: %v", err)
}
// HandleWebhookRequest handles WebhookRequest and sends the WebhookResponse.
func HandleWebhookRequest(w http.ResponseWriter, r *http.Request) {
var request webhookRequest
var response webhookResponse
var err error
// Read input JSON
if err = json.NewDecoder(r.Body).Decode(&request); err != nil {
handleError(w, err)
return
}
log.Printf("Request: %+v", request)
// Call intent handler
switch intent := request.QueryResult.Intent.DisplayName; intent {
case "Default Welcome Intent":
response, err = welcome(request)
case "get-agent-name":
response, err = getAgentName(request)
default:
err = fmt.Errorf("Unknown intent: %s", intent)
}
if err != nil {
handleError(w, err)
return
}
log.Printf("Response: %+v", response)
// Send response
if err = json.NewEncoder(w).Encode(&response); err != nil {
handleError(w, err)
return
}
}
Java
Para autenticar na Dialogflow CX, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar na Dialogflow CX, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para autenticar na Dialogflow CX, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.