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
WebhookRequestcom 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:
400Solicitação inválida401Não autorizado403Proibido404Não encontrado500Falha no servidor503Serviç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:
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.