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:
- Leia os Princípios básicos do Dialogflow CX.
- Execute as etapas de configuração.
- 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:
- É 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.
- Acesse a página de visão geral do Cloud Functions.
- 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
- Clique em Save.
- Clique em Next. Você não precisa de configurações especiais de ambiente de execução, build, conexões ou segurança.
- 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
- 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 } }
- Clique em Implantar.
- 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:
- Abra o Console do Dialogflow CX.
- Escolha seu projeto do Google Cloud.
- Selecione seu agente.
- Selecione a guia Gerenciar.
- Clique em Webhooks.
- Clique em Criar.
- 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.
- 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:
- Selecione a guia Build.
- Clique na página Confirmação do pedido para abrir a página no gráfico do builder de agentes.
- Clique no campo Entry Fulfillment na página para abrir o painel de fulfillment.
- 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 delete aparece.
- Clique em Ativar webhook.
- Selecione a opção
shirts-agent-webhook
no menu suspenso Webhook. - Insira
confirm
no campo Tag. - Clique em Save.
- 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:
- Clique na rota da condição mostrada com uma condição
true
para abrir o painel de rotas. - 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.
- Clique em Save.
- Feche o painel de rota.
Testar o agente no simulador
Seu agente e webhook estão prontos para serem testados com o simulador:
- Clique em Agente de teste.
- 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. |