Guida rapida: crea un webhook

Questa guida illustra come utilizzare un webhook, in modo che il tuo agente possa essere più dinamico. Cloud Functions vengono utilizzati per ospitare il webhook per via della loro semplicità, ma ci sono molti altri modi per ospitare un servizio webhook. L'esempio utilizza anche il linguaggio di programmazione Go, ma puoi utilizzare qualsiasi supportato da Cloud Functions. Per questa guida non è necessario modificare il codice.

Il codice webhook di esempio prevede quanto segue:

  • Legge i valori parametro dalla richiesta webhook.
  • Scrive un valore parametro nella risposta webhook.
  • Fornisce una risposta di testo nella risposta webhook.

Prima di iniziare

Se non prevedi di utilizzare i webhook, puoi saltare questa guida rapida.

Prima di leggere questa guida, devi procedere nel seguente modo:

  1. Leggi le nozioni di base su Dialogflow CX.
  2. Esegui la procedura di configurazione.
  3. Esegui i passaggi nella Crea un agente guida rapida. I passaggi riportati di seguito continuano a lavorare sullo stesso agente. Se non hai più quell'agente, puoi scarica l'agente e ripristinarla.

crea la Cloud Function

Le funzioni Cloud Functions possono essere create con la console Google Cloud (consulta la documentazione e apri la console). Per creare una funzione per questa guida:

  1. È importante che l'agente Dialogflow e la funzione sono entrambi nello stesso progetto. Questo è il modo più semplice per accesso sicuro alla tua funzione. Per selezionare il progetto: vai al selettore progetti.
  2. Vai alla sezione Pagina di riepilogo di Cloud Functions.
  3. Fai clic su Crea funzione e imposta i seguenti campi:
      .
    • Ambiente: 1ª generazione
    • Nome funzione: shirts-agent-webhook
    • Regione: se hai specificato una regione per l'agente, usano la stessa regione.
    • Tipo di trigger HTTP: HTTP
    • URL: fai clic sul pulsante di copia qui e salva il valore. Questo URL ti servirà durante la configurazione del webhook.
    • Autenticazione: richiedi l'autenticazione
    • Richiedi HTTPS: selezionato
  4. Fai clic su Salva.
  5. Fai clic su Avanti (non sono necessari runtime, build connessioni o impostazioni di sicurezza).
  6. Imposta i seguenti campi:
    • Runtime: seleziona il runtime Go più recente.
    • Codice sorgente: editor in linea
    • Punto di ingresso: HandleWebhookRequest
  7. Sostituisci il codice con quanto segue:

    // 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. Fai clic su Esegui il deployment.

  9. Attendi finché l'indicatore di stato indica che la funzione il deployment è stato eseguito correttamente. Nell'attesa, esamina il codice di cui hai appena eseguito il deployment. I commenti al codice descrivono dettagli importanti.

Crea il webhook

Ora che il webhook esiste come funzione Cloud Functions, assocerai questo webhook al tuo agente. Per creare il webhook per l'agente:

  1. Apri la console Dialogflow CX.
  2. Scegli il progetto Google Cloud.
  3. Seleziona l'agente.
  4. Seleziona la scheda Gestisci.
  5. Fai clic su Webhook.
  6. Fai clic su Crea.
  7. Completa i seguenti campi:
    • Nome visualizzato: shirts-agent-webhook
    • URL webhook: fornisci l'URL webhook che hai salvato. quando crei la funzione.
    • Sottotipo: standard.
    • Tutti gli altri campi utilizzano valori predefiniti.
  8. Fai clic su Salva.

Utilizzare il webhook

Ora che il webhook è disponibile per l'agente, userai il webhook in fulfillment. La pagina Conferma dell'ordine contiene un evasione degli ordini, che al momento ha una risposta testuale statica. Per aggiornare il fulfillment in modo da utilizzare il webhook:

  1. Seleziona la scheda Crea.
  2. Fai clic sulla pagina Conferma ordine per espanderla sul grafico dello strumento di creazione degli agenti.
  3. Fai clic sul campo Completamento inserimento nella pagina per aprire il riquadro di evasione degli ordini.
  4. Elimina il messaggio esistente sotto l'intestazione L'agente dice. Quando passi il mouse sopra il testo, Elimina .
  5. Fai clic su Attiva webhook.
  6. Seleziona l'opzione shirts-agent-webhook dal menu a discesa Webhook.
  7. Inserisci confirm nel campo Tag.
  8. Fai clic su Salva.
  9. Chiudi il riquadro di evasione degli ordini.

Screenshot del grafico dell'agente

Il codice del webhook di cui è stato eseguito il deployment invia una risposta che crea un parametro denominato cancel-period. Aggiorna l'agente in modo che faccia riferimento a questo parametro nella risposta finale dell'agente per la stessa pagina Conferma dell'ordine:

  1. Fai clic sulla condizione percorso mostrato con una condizione true per aprire il riquadro del percorso.
  2. Scorri verso il basso fino alla sezione Fulfillment del riquadro del percorso. e aggiungi la seguente risposta sotto l'intestazione L'agente dice: You can cancel your order within $session.params.cancel-period days. Goodbye.
  3. Fai clic su Salva.
  4. Chiudi il riquadro del percorso.

Screenshot del grafico dell'agente

Testa l'agente nel simulatore

L'agente e il webhook sono pronti per essere testati con simulatore:

  1. Fai clic su Test agent.
  2. Inserisci I want to buy a large red shirt e premi Invio.

Poiché hai specificato sia la taglia sia il colore, hai dato all'agente tutto il necessario per creare un ordine di camicie, in modo che passi direttamente alla pagina Conferma dell'ordine.

Screenshot del grafico dell'agente

Di seguito sono descritte le risposte dell'agente:

Risposta Spiegazione
Ok, iniziamo un nuovo ordine. Quando la pagina Nuovo ordine è diventata attiva, è stato chiamato il fulfillment della voce. La risposta è stata attivata da questo fulfillment.
Hai selezionato una camicia rossa di taglia L. Quando sono stati forniti tutti i parametri del modulo per la pagina Nuovo ordine, viene chiamato il controllo del percorso delle condizioni per la compilazione del modulo. La risposta è stata attivata dal completamento di questo percorso. Questo percorso passa anche alla pagina Conferma dell'ordine.
Puoi ritirare l'ordine per una camicia rossa L tra 5 giorni. Il completamento della voce per la pagina Conferma dell'ordine chiama il webhook. Vedi la funzione confirm nel codice webhook. La funzione crea la risposta di testo e utilizza i parametri forniti nella richiesta webhook.
Puoi annullare l'ordine entro 2 giorni. Arrivederci. La pagina Conferma dell'ordine include una route condizione con una condizione sempre vera. Questa risposta viene attivata dal completamento del percorso in questione. Tieni presente che la risposta utilizza il parametro impostato dal webhook nella risposta webhook.