Crie um webhook

Este guia mostra como usar um webhook, para que o seu agente possa ser mais dinâmico. As Cloud Functions são usadas para alojar o webhook devido à sua simplicidade, mas existem muitas outras formas de alojar um serviço de webhook. O exemplo também usa a linguagem de programação Go, mas pode usar qualquer linguagem suportada pelas Cloud Functions. Não precisa de editar o código para este guia.

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

  • Lê os valores dos parâmetros do pedido de webhook.
  • Escreve um valor de parâmetro na resposta do webhook.
  • Fornece uma resposta de texto na resposta do webhook.

Antes de começar

Se não planeia usar webhooks, pode ignorar este guia de início rápido.

Antes de ler este guia, deve fazer o seguinte:

  1. Leia as noções básicas sobre fluxos.
  2. Realize os passos de configuração.
  3. Execute os passos no guia de início rápido Crie um agente com fluxos. Os passos abaixo continuam a funcionar no mesmo agente. Se já não tiver esse agente, pode transferir o agente e restaurá-lo.

Crie a função do Cloud

As Cloud Functions podem ser criadas com a Google Cloud Console (visite a documentação, abra a consola). Para criar uma função para este guia:

  1. É importante que o agente dos agentes conversacionais (Dialogflow CX) e a função estejam no mesmo projeto. Esta é a forma mais fácil de os agentes conversacionais (Dialogflow CX) terem acesso seguro à sua função. Para selecionar o seu projeto, aceda ao seletor de projetos.
  2. Aceda à página Vista geral do Cloud Functions.
  3. Clique em Criar função e defina os seguintes campos:
    • Ambiente: 1.ª geração
    • Nome da função: shirts-agent-webhook
    • Região: se especificou uma região para o seu agente, use a mesma região.
    • Tipo de acionador HTTP: HTTP
    • URL: clique no botão de cópia aqui e guarde o valor. Precisa deste URL quando configurar o webhook.
    • Autenticação: exigir autenticação
    • Exigir HTTPS: selecionado
  4. Clique em Guardar.
  5. Clique em Seguinte (não precisa de definições especiais de tempo de execução, compilação, ligações nem segurança).
  6. Defina os seguintes campos:
    • Tempo de execução: selecione o tempo de execução do Go mais recente.
    • Código fonte: editor inline
    • 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 Implementar.

  9. Aguarde até que o indicador de estado mostre que a função foi implementada com êxito. Enquanto espera, examine o código que acabou de implementar. Os comentários no código descrevem detalhes importantes.

Crie o webhook

Agora que o webhook existe como uma função do Google Cloud, vai associar este webhook ao seu agente. Para criar o webhook para o seu agente:

  1. Abra a consola do Dialogflow CX.
  2. Escolha o seu projeto do Google Cloud.
  3. Selecione o seu agente.
  4. Selecione o separador Gerir.
  5. Clique em Webhooks.
  6. Clique em Criar.
  7. Preencha os seguintes campos:
    • Nome a apresentar: shirts-agent-webhook
    • URL do webhook: indique o URL do webhook que guardou quando criou a função.
    • Subtipo: padrão.
    • Todos os outros campos usam valores predefinidos.
  8. Clique em Guardar.

Use o webhook

Agora que o webhook está disponível para o agente, vai usá-lo no processamento de pedidos. A página de confirmação da encomenda tem um preenchimento de entrada que, atualmente, tem uma resposta de texto estático. Para atualizar o processamento de pedidos para usar o webhook:

  1. Selecione o separador Criar.
  2. Clique na página Confirmação da encomenda para expandir a página no gráfico do criador de agentes.
  3. Clique no campo Cumprimento da entrada na página para abrir o painel de cumprimento.
  4. Elimine a resposta de texto existente no título O agente diz. Quando passa o cursor do rato sobre o texto, é apresentado o botão eliminar .
  5. Clique em Ativar webhook.
  6. Selecione a opção shirts-agent-webhook no menu pendente Webhook.
  7. Introduza confirm no campo Etiqueta.
  8. Clique em Guardar.
  9. Feche o painel de processamento.

Captura de ecrã do gráfico do agente

O código do webhook implementado envia uma resposta que cria um parâmetro denominado cancel-period. Atualize o agente para referenciar este parâmetro na resposta final do agente para a mesma página Confirmação da encomenda:

  1. Clique na condição rota apresentada com uma condição true para abrir o painel de rotas.
  2. Desloque a página para baixo até à secção Preenchimento do painel de trajeto e adicione a seguinte resposta de texto no cabeçalho O agente diz: You can cancel your order within $session.params.cancel-period days. Goodbye.
  3. Clique em Guardar.
  4. Feche o painel de trajeto.

Captura de ecrã do gráfico do agente

Teste o agente no simulador

O seu agente e webhook estão prontos para teste com o simulador:

  1. Clique em Agente de teste.
  2. Introduza I want to buy a large red shirt e prima Enter.

Como indicou um tamanho e uma cor, deu ao agente tudo o que precisa para criar uma encomenda de uma camisola, pelo que a transição é feita diretamente para a página Confirmação da encomenda.

Captura de ecrã do gráfico do agente

A seguir, são descritas as respostas do agente:

Resposta Explicação
OK, vamos iniciar uma nova encomenda. Quando a página New Order ficou ativa, foi chamado o preenchimento da entrada. A resposta foi acionada a partir deste preenchimento.
Selecionou uma camisa vermelha de tamanho grande. Quando todos os parâmetros do formulário são fornecidos para a página Nova encomenda, é chamada a verificação do caminho da condição para a conclusão do formulário. A resposta foi acionada a partir do preenchimento deste trajeto. Esta rota também faz a transição para a página Confirmação da encomenda.
Pode levantar a sua encomenda de uma camisola vermelha de tamanho L dentro de 5 dias. O preenchimento da entrada para a página Confirmação da encomenda chama o webhook. Consulte a função confirm no código do webhook. Essa função cria esta resposta de texto e usa os parâmetros fornecidos no pedido de webhook.
Pode cancelar a encomenda no prazo de 2 dias. Adeus. A página Confirmação de encomenda tem um percurso condicional com uma condição que é sempre verdadeira. Esta resposta é acionada pelo processamento desse trajeto. Tenha em atenção que a resposta usa o parâmetro definido pelo webhook na resposta do webhook.
Anterior
Crie um agente com fluxos
Avançar
Interações com uma integração