Para usar o fulfillment em um sistema de produção, você deve implementar e implantar um serviço de webhook. Para processar o fulfillment, seu serviço de webhook precisa aceitar solicitações JSON e retornar respostas JSON conforme especificado neste guia. O fluxo de processamento detalhado do fulfillment e dos webhooks é descrito no documento de visão geral do fulfillment.
Requisitos de serviço do webhook
Os seguintes requisitos devem ser atendidos pelo serviço do webhook:
- Ele precisa processar solicitações HTTPS. O HTTP não é compatível. Se você hospedar seu serviço de webhook no Google Cloud Platform usando uma solução de computação ou computação sem servidor, consulte a documentação do produto para veiculação com HTTPS. Para conhecer outras opções de hospedagem, consulte Adquira um certificado SSL para seu domínio.
- Seu URL para solicitações deve ser acessível publicamente.
- Ele precisa processar solicitações POST com um corpo JSON
WebhookRequest
. - Ele precisa responder a solicitações
WebhookRequest
com um corpo JSONWebhookResponse
.
Autenticação
É importante proteger seu serviço de webhook para que somente você ou seu agente do Dialogflow sejam autorizados a fazer solicitações. O Dialogflow é compatível com os seguintes mecanismos de autenticação:
Termo | Definição |
---|---|
Nome de usuário e senha de login | Para as configurações do webhook, você pode 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 tem o formato: "authorization: Basic <base 64 encoding of the string username:password>" . |
Cabeçalhos de autenticação | Para as configurações do webhook, é possível especificar pares de chave-valor de cabeçalho HTTP opcionais. 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 Functions | Você pode usar a autenticação integrada ao usar o Cloud Functions. Para usar esse tipo de autenticação, não forneça o nome de usuário, a senha de login ou os cabeçalhos de autorização. Se você fornecer algum desses campos, eles serão usados para autenticação em vez da autenticação integrada. |
Tokens de identidade de serviço | Use tokens de identidade de serviço para autenticação. Se você não fornecer o nome de usuário, a senha de login ou um cabeçalho com a chave authorization , o Dialogflow vai presumir automaticamente que os tokens de identidade do serviço precisam ser usados e vai adicionar um cabeçalho HTTP de autorização às solicitações de webhook. Esse cabeçalho tem o seguinte 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 é correspondido, o Dialogflow envia uma solicitação de webhook HTTPS POST para 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 algumas
informações sobre o usuário final. Por exemplo, um ID para identificar
exclusivamente o usuário. Essas informações podem ser acessadas pelo campo originalDetectIntentRequest
na solicitação do webhook, que conterá as informações enviadas da
plataforma de integração.
Consulte a documentação de referência de WebhookRequest
para mais detalhes.
Veja um 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
Uma vez que seu webhook recebe uma solicitação de webhook, ela precisa enviar uma resposta a um webhook. O corpo dessa resposta é um objeto JSON com as seguintes informações:
- A resposta que o Dialogflow retorna ao usuário final.
- Atualizações nos contextos ativos para a conversa.
- Um evento de acompanhamento para acionar uma correspondência de intent.
- Um payload personalizado para ser enviado para a integração ou para detectar o cliente de intent
As seguintes limitações se aplicam à sua resposta:
- A resposta deve ocorrer dentro de 10 segundos para aplicativos do Google Assistente ou 5 segundos para todos os outros aplicativos. Caso contrário, a solicitação atingirá o tempo limite.
- É necessário que o tamanho da resposta seja menor ou igual a 64 KiB.
Consulte a documentação de referência de WebhookResponse
para mais detalhes.
Resposta de texto
Exemplo para uma resposta de texto:
{ "fulfillmentMessages": [ { "text": { "text": [ "Text response from webhook" ] } } ] }
Resposta do card
Exemplo para uma resposta do 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
Exemplo para uma resposta do Google Assistente:
{ "payload": { "google": { "expectUserResponse": true, "richResponse": { "items": [ { "simpleResponse": { "textToSpeech": "this is a Google Assistant response" } } ] } } } }
Contexto
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
Exemplo que invoca um evento personalizado:
{ "followupEventInput": { "name": "event-name", "languageCode": "en-US", "parameters": { "param-name": "param-value" } } }
Entidade de sessão
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
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 esquerda.
- 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 na parte inferior da página.
Para ativar e gerenciar o fulfillment do agente com a API, consulte a referência do agente.
Os métodos getFulfillment
e updateFulfillment
podem ser usados para 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.
- Role para baixo até a seção Fulfillment.
- Alternar Ativar chamada de webhook para este intent para ativada.
- Clique em Save.
Para ativar o fulfillment para uma intent com a API, consulte a referência de intents.
Defina o campo webhookState
como WEBHOOK_STATE_ENABLED
.
Erros de webhook
Se o serviço do webhook encontrar um erro, ele retornará um dos seguintes códigos de status HTTP:
400
Solicitação inválida401
Não autorizado403
Proibido404
Não encontrado500
Falha no servidor503
Serviço não disponí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:
- Tempo limite de resposta excedido.
- Código de status de erro recebido.
- A resposta é inválida.
- O serviço de webhook não está disponível.
Além disso, se a correspondência de intent tiver sido acionada por uma chamada de API de intent de detecção, o campo status
na resposta de intent de detecção 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 automaticamente repetem determinados erros de webhook para melhorar a robustez. Somente erros não terminais são retentativas (por exemplo, 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 à idempotencia na lógica do webhook ou faça a deduplicação.
Como usar o Cloud Functions
Há algumas maneiras de usar o Cloud Functions para fulfillment. O editor in-line do Dialogflow é integrado ao Cloud 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. talvez você queira usar uma linguagem diferente do Node.js. Se a função do Cloud estiver no mesmo projeto que o agente, ele poderá chamar o webhook sem precisar de configuração especial.
No entanto, há duas situações em que é preciso configurar essa integração manualmente:
- 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:
Essa conta de serviço especial e a chave associada normalmente são criadas automaticamente quando você cria o primeiro agente de um projeto. Se o agente tiver sido criado antes de 10 de maio de 2021, talvez seja necessário acionar a criação dessa conta de serviço especial com o seguinte:service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
- Crie um novo agente para o projeto.
- Execute o comando a seguir:
gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
- Se a função do webhook residir em um projeto diferente do agente, forneça o Papel do IAM Invocador do Cloud Functions à conta de serviço 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, opcionalmente, validar o token
usando bibliotecas de cliente do Google ou bibliotecas de código aberto, como em
github.com/googleapis/google-auth-library-nodejs (em inglês).
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 de intents de referência são criados no
guia de início rápido.
Go
Para autenticar no Dialogflow, 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 no Dialogflow, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Node.js
Para autenticar no Dialogflow, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.
Python
Para autenticar no Dialogflow, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.