Guia de início rápido: criar um webhook

Neste guia, mostramos como usar um webhook para que seu agente seja mais dinâmico. O Cloud Functions é usado para hospedar o webhook devido à simplicidade dele, mas há muitas outras maneiras de hospedar um serviço de webhook. No exemplo, também usamos a linguagem de programação Go, mas é possível usar qualquer linguagem compatível com o Cloud Functions. Não será necessário editar o código para este guia.

O código do webhook de exemplo faz o seguinte:

• Lê os valores de parâmetro da solicitação do webhook.
• Grava um valor de parâmetro na resposta do webhook.
• Fornece uma resposta de texto na resposta do webhook.

Antes de começar

Se você não planeja usar webhooks, pule este guia de início rápido.

Faça o seguinte antes de ler este guia:

1. Leia os Princípios básicos do Dialogflow CX.
2. Execute as etapas de configuração.
3. Realize as etapas no guia de início rápido Criar um agente. As etapas abaixo continuam funcionando no mesmo agente. Se você não tiver mais esse agente, faça o download dele e restaure-o.

Criar a função do Cloud

O Cloud Functions pode ser criado com o console do Google Cloud. Acesse a documentação e abra o console. Para criar uma função para este guia:

1. É importante que o agente e a função do Dialogflow estejam no mesmo projeto. Essa é a maneira mais fácil de o Dialogflow ter acesso seguro à função. Para escolher seu projeto, acesse o seletor de projetos.
2. Acesse a página de visão geral do Cloud Functions.
3. Clique em Criar função e defina os seguintes campos:
   • Ambiente: 1a geração
   • Nome da função: shirts-agent-webhook
   • Região: se você especificou uma região para seu agente, use a mesma região.
   • Tipo de acionador HTTP: HTTP
   • URL: clique no botão de cópia aqui e salve o valor. Você precisará desse URL ao configurar o webhook.
   • Autenticação: exige autenticação.
   • Exigir HTTPS: marcada
4. Clique em Save.
5. Clique em Next. Você não precisa de configurações especiais de ambiente de execução, build, conexões ou segurança.
6. Defina os seguintes campos:
   • Ambiente de execução: selecione o ambiente de execução mais recente do Go.
   • Código-fonte: editor in-line
   • Ponto de entrada: HandleWebhookRequest
7. Substitua o código pelo seguinte:

   // Package cxwh contains an example Dialogflow CX webhook
   package cxwh
   
   import (
   	"encoding/json"
   	"fmt"
   	"log"
   	"net/http"
   )
   
   type fulfillmentInfo struct {
   	Tag string `json:"tag"`
   }
   
   type sessionInfo struct {
   	Session    string                 `json:"session"`
   	Parameters map[string]interface{} `json:"parameters"`
   }
   
   type text struct {
   	Text []string `json:"text"`
   }
   
   type responseMessage struct {
   	Text text `json:"text"`
   }
   
   type fulfillmentResponse struct {
   	Messages []responseMessage `json:"messages"`
   }
   
   // 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://pkg.go.dev/google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3#WebhookRequest
   type webhookRequest struct {
   	FulfillmentInfo fulfillmentInfo `json:"fulfillmentInfo"`
   	SessionInfo     sessionInfo     `json:"sessionInfo"`
   }
   
   // 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://pkg.go.dev/google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3#WebhookResponse
   type webhookResponse struct {
   	FulfillmentResponse fulfillmentResponse `json:"fulfillmentResponse"`
   	SessionInfo         sessionInfo         `json:"sessionInfo"`
   }
   
   // confirm handles webhook calls using the "confirm" tag.
   func confirm(request webhookRequest) (webhookResponse, error) {
   	// Create a text message that utilizes the "size" and "color"
   	// parameters provided by the end-user.
   	// This text message is used in the response below.
   	t := fmt.Sprintf("You can pick up your order for a %s %s shirt in 5 days.",
   		request.SessionInfo.Parameters["size"],
   		request.SessionInfo.Parameters["color"])
   
   	// Create session parameters that are populated in the response.
   	// The "cancel-period" parameter is referenced by the agent.
   	// This example hard codes the value 2, but a real system
   	// might look up this value in a database.
   	p := map[string]interface{}{"cancel-period": "2"}
   
   	// Build and return the response.
   	response := webhookResponse{
   		FulfillmentResponse: fulfillmentResponse{
   			Messages: []responseMessage{
   				{
   					Text: text{
   						Text: []string{t},
   					},
   				},
   			},
   		},
   		SessionInfo: sessionInfo{
   			Parameters: p,
   		},
   	}
   	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)
   
   	// Get the tag from the request, and call the corresponding
   	// function that handles that tag.
   	// This example only has one possible tag,
   	// but most agents would have many.
   	switch tag := request.FulfillmentInfo.Tag; tag {
   	case "confirm":
   		response, err = confirm(request)
   	default:
   		err = fmt.Errorf("Unknown tag: %s", tag)
   	}
   	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
   	}
   }
   
   

8. Clique em Implantar.
9. Aguarde até que o indicador de status mostre que a função foi implantada com sucesso. Enquanto espera, examine o código que você acabou de implantar. Os comentários de código descrevem detalhes importantes.

Criar o webhook

Agora que o webhook existe como uma função do Cloud, você vai associá-lo ao seu agente. Para criar o webhook do agente:

1. Abra o Console do Dialogflow CX.
2. Escolha seu projeto do Google Cloud.
3. Selecione seu agente.
4. Selecione a guia Gerenciar.
5. Clique em Webhooks.
6. Clique em Criar.
7. Preencha os seguintes campos:
   • Nome de exibição: shirts-agent-webhook
   • URL do webhook: forneça o URL do webhook que você salvou ao criar a função.
   • Subtipo: padrão.
   • Todos os outros campos usam valores padrão.
8. Clique em Save.

Usar o webhook

Agora que o webhook está disponível para o agente, você usará-o em fulfillment. A página Confirmação do pedido tem um fulfillment de entrada, que no momento tem uma resposta de texto estático. Para atualizar o fulfillment para usar o webhook:

1. Selecione a guia Build.
2. Clique na página Confirmação do pedido para abrir a página no gráfico do builder de agentes.
3. Clique no campo Entry Fulfillment na página para abrir o painel de fulfillment.
4. Exclua a resposta de texto atual sob o título O agente diz. Ao passar o cursor sobre o texto, o botão de exclusão aparece.
5. Clique em Ativar webhook.
6. Selecione a opção shirts-agent-webhook no menu suspenso Webhook.
7. Insira confirm no campo Tag.
8. Clique em Save.
9. Feche o painel de fulfillment.

O código do webhook implantado envia uma resposta que cria um parâmetro chamado cancel-period. Atualize o agente para referenciar esse parâmetro na resposta final do agente para a mesma página de Confirmação do pedido:

1. Clique na rota da condição mostrada com uma condição true para abrir o painel de rotas.
2. Role para baixo até a seção Fulfillment do painel de rota e adicione a seguinte resposta de texto no título O agente diz: You can cancel your order within $session.params.cancel-period days. Goodbye.
3. Clique em Save.
4. Feche o painel de rota.

Testar o agente no simulador

Seu agente e webhook estão prontos para serem testados com o simulador:

1. Clique em Agente de teste.
2. Digite I want to buy a large red shirt e pressione "Enter".

Como você forneceu um tamanho e uma cor, forneceu ao agente tudo o que é necessário para criar um pedido de camisa, para que ele faça a transição diretamente para a página Confirmação do pedido.

Confira a seguir a descrição das respostas do agente:

Resposta	Explicação
Ok, vamos começar outro pedido.	Quando a página Novo pedido ficou ativa, o fulfillment da entrada foi chamado. A resposta foi acionada com esse fulfillment.
Você selecionou uma camisa vermelha grande.	Quando todos os parâmetros de formulário forem fornecidos para a página Novo pedido, a rota de condição que verifica o preenchimento do formulário será chamada. A resposta foi acionada pelo fulfillment para essa rota. Essa rota também faz a transição para a página Confirmação do pedido.
Você pode retirar seu pedido de uma camisa vermelha grande em cinco dias.	O fulfillment de entrada da página de Confirmação do pedido chama o webhook. Consulte a função confirm no código do webhook. Essa função cria essa resposta de texto e usa os parâmetros fornecidos na solicitação do webhook.
Você pode cancelar seu pedido em até dois dias. Goodbye.	A página Confirmação do pedido tem uma rota de condição com uma condição que é sempre verdadeira. Essa resposta é acionada pelo fulfillment para essa rota. Observe que a resposta usa o parâmetro definido pelo webhook na resposta do webhook.