Crie um serviço de webhook

O agente pré-criado que criou no último passo requer um webhook. As funções do Cloud Run são usadas para alojar o webhook neste tutorial 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 funções do Cloud Run.

Crie a função

As funções do Cloud Run podem ser criadas com a Google Cloud Console (visite a documentação, abra a consola). Para criar uma função para este tutorial:

  1. É importante que o agente do Dialogflow e a função estejam no mesmo projeto. Esta é a forma mais fácil de o Dialogflow ter acesso seguro à sua função. Antes de criar a função, selecione o seu projeto na Google Cloud consola.

    Aceder ao seletor de projetos

  2. Abra a página de vista geral das funções do Cloud Run.

    Aceda à vista geral das funções do Cloud Run

  3. Clique em Criar função e defina os seguintes campos:

    • Ambiente: 1.ª geração
    • Nome da função: tutorial-telecommunications-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 cxtwh

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
	"strings"

	"cloud.google.com/go/spanner"
  "google.golang.org/grpc/codes"
)

// client is a Spanner client, created only once to avoid creation
// for every request.
// See: https://cloud.google.com/functions/docs/concepts/go-runtime#one-time_initialization
var client *spanner.Client

func init() {
	// If using a database, these environment variables will be set.
	pid := os.Getenv("PROJECT_ID")
	iid := os.Getenv("SPANNER_INSTANCE_ID")
	did := os.Getenv("SPANNER_DATABASE_ID")
	if pid != "" && iid != "" && did != "" {
		db := fmt.Sprintf("projects/%s/instances/%s/databases/%s",
			pid, iid, did)
		log.Printf("Creating Spanner client for %s", db)
		var err error
		// Use the background context when creating the client,
		// but use the request context for calls to the client.
		// See: https://cloud.google.com/functions/docs/concepts/go-runtime#contextcontext
		client, err = spanner.NewClient(context.Background(), db)
		if err != nil {
			log.Fatalf("spanner.NewClient: %v", err)
		}
	}
}

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"`
}

// detectCustomerAnomaly handles same-named tag.
func detectCustomerAnomaly(ctx context.Context, request webhookRequest) (
	webhookResponse, error) {
	// Create session parameters that are populated in the response.
	// This example hard codes values, but a real system
	// might look up this value in a database.
	p := map[string]interface{}{
		"anomaly_detect":        "false",
		"purchase":              "device protection",
		"purchase_amount":       "12.25",
		"bill_without_purchase": "54.34",
		"total_bill":            "66.59",
		"first_month":           "January 1",
	}
	// Build and return the response.
	response := webhookResponse{
		SessionInfo: sessionInfo{
			Parameters: p,
		},
	}
	return response, nil
}

// validatePhoneLine handles same-named tag.
func validatePhoneLine(ctx context.Context, request webhookRequest) (
	webhookResponse, error) {
	// Create session parameters that are populated in the response.
	// This example hard codes values, but a real system
	// might look up this value in a database.
	p := map[string]interface{}{
		"domestic_coverage":   "true",
		"phone_line_verified": "true",
	}
	// Build and return the response.
	response := webhookResponse{
		SessionInfo: sessionInfo{
			Parameters: p,
		},
	}
	return response, nil
}

// cruisePlanCoverage handles same-named tag.
func cruisePlanCoverage(ctx context.Context, request webhookRequest) (
	webhookResponse, error) {
	// Get the existing parameter values
	port := request.SessionInfo.Parameters["destination"].(string)
	port = strings.ToLower(port)
	// Check if the port is covered
	covered := "false"
	if client != nil {
		// A Spanner client exists, so access the database.
		// See: https://pkg.go.dev/cloud.google.com/go/spanner#ReadOnlyTransaction.ReadRow
		row, err := client.Single().ReadRow(ctx,
			"Destinations",
			spanner.Key{port},
			[]string{"Covered"})
		if err != nil {
			if spanner.ErrCode(err) == codes.NotFound {
				log.Printf("Port %s not found", port)
			} else {
				return webhookResponse{}, err
			}
		} else {
			// A row was returned, so check the value
			var c bool
			err := row.Column(0, &c)
			if err != nil {
				return webhookResponse{}, err
			}
			if c {
				covered = "true"
			}
		}
	} else {
		// No Spanner client exists, so use hardcoded list of ports.
		coveredPorts := map[string]bool{
			"anguilla": true,
			"canada":   true,
			"mexico":   true,
		}
		_, ok := coveredPorts[port]
		if ok {
			covered = "true"
		}
	}
	// Create session parameters that are populated in the response.
	// This example hard codes values, but a real system
	// might look up this value in a database.
	p := map[string]interface{}{
		"port_is_covered": covered,
	}
	// Build and return the response.
	response := webhookResponse{
		SessionInfo: sessionInfo{
			Parameters: p,
		},
	}
	return response, nil
}

// internationalCoverage handles same-named tag.
func internationalCoverage(ctx context.Context, request webhookRequest) (
	webhookResponse, error) {
	// Get the existing parameter values
	destination := request.SessionInfo.Parameters["destination"].(string)
	destination = strings.ToLower(destination)
	// Hardcoded list of covered international monthly destinations
	coveredMonthly := map[string]bool{
		"anguilla":  true,
		"australia": true,
		"brazil":    true,
		"canada":    true,
		"chile":     true,
		"england":   true,
		"france":    true,
		"india":     true,
		"japan":     true,
		"mexico":    true,
		"singapore": true,
	}
	// Hardcoded list of covered international daily destinations
	coveredDaily := map[string]bool{
		"brazil":    true,
		"canada":    true,
		"chile":     true,
		"england":   true,
		"france":    true,
		"india":     true,
		"japan":     true,
		"mexico":    true,
		"singapore": true,
	}
	// Check coverage
	coverage := "neither"
	_, monthly := coveredMonthly[destination]
	_, daily := coveredDaily[destination]
	if monthly && daily {
		coverage = "both"
	} else if monthly {
		coverage = "monthly_only"
	} else if daily {
		coverage = "daily_only"
	}
	// Create session parameters that are populated in the response.
	// This example hard codes values, but a real system
	// might look up this value in a database.
	p := map[string]interface{}{
		"coverage": coverage,
	}
	// Build and return the response.
	response := webhookResponse{
		SessionInfo: sessionInfo{
			Parameters: p,
		},
	}
	return response, nil
}

// cheapestPlan handles same-named tag.
func cheapestPlan(ctx context.Context, request webhookRequest) (
	webhookResponse, error) {
	// Create session parameters that are populated in the response.
	// This example hard codes values, but a real system
	// might look up this value in a database.
	p := map[string]interface{}{
		"monthly_cost":   70,
		"daily_cost":     100,
		"suggested_plan": "monthly",
	}
	// Build and return the response.
	response := webhookResponse{
		SessionInfo: sessionInfo{
			Parameters: p,
		},
	}
	return response, nil
}

// Define a type for handler functions.
type handlerFn func(ctx context.Context, request webhookRequest) (
	webhookResponse, error)

// Create a map from tag to handler function.
var handlers map[string]handlerFn = map[string]handlerFn{
	"detectCustomerAnomaly": detectCustomerAnomaly,
	"validatePhoneLine":     validatePhoneLine,
	"cruisePlanCoverage":    cruisePlanCoverage,
	"internationalCoverage": internationalCoverage,
	"cheapestPlan":          cheapestPlan,
}

// handleError handles internal errors.
func handleError(w http.ResponseWriter, err error) {
	log.Printf("ERROR: %v", err)
	http.Error(w,
		fmt.Sprintf("ERROR: %v", err),
		http.StatusInternalServerError)
}

// 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.
	tag := request.FulfillmentInfo.Tag
	if fn, ok := handlers[tag]; ok {
		response, err = fn(r.Context(), request)
	} else {
		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.

Configure o webhook para o seu agente

Agora que o webhook existe como um serviço, vai associar este webhook ao seu agente. Para configurar o webhook do 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 no webhook existente (criado pelo agente pré-criado).
  7. Atualize o URL do webhook para o URL do webhook que guardou quando criou a função.
  8. Defina o Subtipo como Padrão.
  9. Clique em Guardar.

Experimente o agente

O seu agente já está pronto para ser testado. Clique no botão Agente de teste para abrir o simulador. Tente ter a seguinte conversa com o agente:

Interação conversacional Eu Agente
1 Olá, Olá! Sou o agente virtual de telecomunicações. Posso ajudar a resolver questões de faturação e planos, resolver problemas e adicionar planos de viagens e cruzeiros. Como posso ajudar hoje?
2 Quero adicionar um plano de cruzeiro Vou verificar a situação. Qual é o seu número de telefone connosco?
3 123-123-1234 Quantos dias dura o cruzeiro?
4 7 A opção 1 inclui chamadas e mensagens. Tem um custo de $[XX]/dia. Mais informações aqui [URL]. A opção 2 inclui chamadas, mensagens de texto e dados. Tem um custo de $[XX]/dia. Mais informações aqui [URL]. Que plano de cruzeiro quer adicionar?
5 Opção 1 OK. Adicionei esse plano à sua conta. Durante o cruzeiro, também pode precisar de cobertura em terra. Em que porto vai parar?
6 México E quantos dias vai passar lá?
7 3 Boas notícias! O México tem cobertura terrestre gratuita. Está tudo pronto. Há mais alguma questão com que possa ajudar?

Esta conversa específica foi gerida pelo fluxo do Cruise Plan.

Na conversa n.º 6, indicou "México" como o porto de destino. A porta de destino e o número de dias aí são capturados como os parâmetros de formulário destination e trip_duration da página Collect Port. Procure no seu agente para encontrar estas definições de parâmetros.

Captura de ecrã da página Collect Port na consola do Dialogflow

Na página Collect Port, existe um caminho de condição para a conclusão do formulário: $page.params.status = "FINAL". Quando os dois parâmetros do formulário são fornecidos, esta rota é chamada. Esta rota chama o seu webhook e fornece a etiqueta cruisePlanCoverage ao webhook. Se examinar o código do webhook acima, vai ver que esta etiqueta aciona a mesma função com nome a ser chamada.

Esta função determina se o destino fornecido está coberto pelo plano. A função verifica se existem variáveis de ambiente específicas definidas com informações para estabelecer ligação à base de dados. Se estas variáveis de ambiente não estiverem definidas, a função usa uma lista codificada de destinos. Nos passos seguintes, vai alterar o ambiente da função para que obtenha dados de uma base de dados para validar a cobertura do plano para destinos.

Resolução de problemas

O código do webhook inclui declarações de registo. Se estiver a ter problemas, experimente ver os registos da sua função.

Mais informações

Para mais informações sobre os passos acima, consulte:

Anterior
Crie um agente pré-criado
Avançar
Consultar uma base de dados