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 | Nas configurações do 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 do webhook. Esse cabeçalho tem o formato: "authorization: Basic <base 64 encoding of the string username:password>" . |
Cabeçalhos de autenticação | Nas configurações do webhook, especifique pares de chave-valor do 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 nome de usuário de login, senha de login ou 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 e a senha de login ou um cabeçalho com uma chave authorization , o Dialogflow presume automaticamente que os tokens de identidade do serviço devem ser usados e adiciona um cabeçalho HTTP de autorização às solicitações do webhook. Esse cabeçalho tem o formato: "authorization: Bearer <identity token>" . |
Autenticação TLS mútua | Consulte a documentação 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...>"
}
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 criado de modo automático quando você cria o primeiro agente para 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.