Per utilizzare il fulfillment in un sistema di produzione, devi implementare e deployment un servizio webhook. Per gestire il fulfillment, il servizio webhook deve accettare le richieste JSON e restituire le risposte JSON come specificato in questa guida. Il flusso di elaborazione dettagliato per il fulfillment e i webhook è descritto nel documento Panoramica del fulfillment.
Requisiti del servizio webhook
Il servizio webhook deve soddisfare i seguenti requisiti:
- Gestire le richieste HTTPS. Il protocollo HTTP non è supportato. Se ospiti il servizio webhook su Google Cloud utilizzando una soluzione di calcolo Compute o Serverless, consulta la documentazione del prodotto per la pubblicazione con HTTPS. Per altre opzioni di hosting, consulta Ottenere un certificato SSL per il tuo dominio.
- Assicurati che l'URL del servizio webhook sia accessibile pubblicamente.
- Gestire le richieste POST con un corpo JSON
WebhookRequest. - Rispondere alle richieste
WebhookRequestcon un corpo JSONWebhookResponse.
Autenticazione
| X | Elemento |
|---|---|
| Nome utente e password di accesso | Per le impostazioni del webhook, puoi specificare valori facoltativi per il nome utente e la password di accesso. Se forniti, Dialogflow aggiunge un'intestazione HTTP di autorizzazione alle richieste webhook. Questa intestazione ha il seguente formato: "authorization: Basic <base 64 encoding of the string username:password>". |
| Intestazioni di autenticazione | Per le impostazioni del webhook, puoi specificare coppie chiave-valore di intestazioni HTTP facoltative. Se fornite, Dialogflow aggiunge queste intestazioni HTTP alle richieste webhook. È comune fornire una singola coppia con una chiave di authorization. |
| Autenticazione integrata di Cloud Run Functions | Puoi utilizzare l'autenticazione integrata quando utilizzi Cloud Run Functions. Per utilizzare questo tipo di autenticazione, non fornire intestazioni di nome utente, password o autorizzazione. Se fornisci uno di questi campi, non verrà utilizzato per l'autenticazione integrata. |
| Token di identità del servizio | Puoi utilizzare i token di identità del servizio per l'autenticazione. Se non fornisci il nome utente di accesso, la password di accesso o un'intestazione con una chiave di authorization, Dialogflow presuppone automaticamente che debbano essere utilizzati i token di identità del servizio e aggiunge un'intestazione HTTP di autorizzazione alle richieste webhook. Questa intestazione ha il seguente formato: "authorization: Bearer <identity token>". |
| Autenticazione TLS reciproca | Consulta la documentazione sull'autenticazione TLS reciproca. |
Richiesta webhook
Quando viene trovato un intent configurato per il fulfillment, Dialogflow invia una richiesta webhook POST HTTPS al tuo servizio webhook. Il corpo di questa richiesta è un oggetto JSON con informazioni sull'intent trovato.
Oltre alla query dell'utente finale, molte integrazioni inviano anche informazioni sull'utente finale. Ad esempio, un ID che identifica in modo univoco l'utente. È possibile accedere a queste informazioni utilizzando il campo originalDetectIntentRequest nella richiesta webhook, che contiene le informazioni inviate dalla piattaforma di integrazione.
Per saperne di più, consulta la
WebhookRequest
documentazione di riferimento.
Di seguito è riportato un esempio di richiesta:
{
"responseId": "response-id",
"session": "projects/project-id/agent/sessions/session-id",
"queryResult": {
"queryText": "End-user expression",
"parameters": {
"param-name": "param-value"
},
"allRequiredParamsPresent": true,
"fulfillmentText": "Response configured for matched intent",
"fulfillmentMessages": [
{
"text": {
"text": [
"Response configured for matched intent"
]
}
}
],
"outputContexts": [
{
"name": "projects/project-id/agent/sessions/session-id/contexts/context-name",
"lifespanCount": 5,
"parameters": {
"param-name": "param-value"
}
}
],
"intent": {
"name": "projects/project-id/agent/intents/intent-id",
"displayName": "matched-intent-name"
},
"intentDetectionConfidence": 1,
"diagnosticInfo": {},
"languageCode": "en"
},
"originalDetectIntentRequest": {}
}
Risposta webhook
Dopo aver ricevuto una richiesta, il webhook deve inviare una risposta. Il corpo di questa risposta è un oggetto JSON che contiene le seguenti informazioni:
- La risposta che Dialogflow restituisce all'utente finale.
- Aggiornamenti dei contesti attivi per la conversazione.
- Un evento di follow-up per attivare una corrispondenza dell'intent.
- Un payload personalizzato da inviare all'integrazione o al client di rilevamento dell'intent.
Alla risposta si applicano le seguenti limitazioni:
- Rispondi entro 10 secondi per le applicazioni dell'Assistente Google o 5 secondi per altre applicazioni; in caso contrario, la richiesta va in timeout.
- Mantieni le dimensioni della risposta a 64 KiB o meno.
Per saperne di più, consulta la
WebhookResponse
documentazione di riferimento.
Messaggio di risposta
Di seguito è riportato un esempio di messaggio di risposta:
{
"fulfillmentMessages": [
{
"text": {
"text": [
"Text response from webhook"
]
}
}
]
}
Risposta della scheda
Di seguito è riportato un esempio di risposta della scheda:
{
"fulfillmentMessages": [
{
"card": {
"title": "card title",
"subtitle": "card text",
"imageUri": "https://example.com/images/example.png",
"buttons": [
{
"text": "button text",
"postback": "https://example.com/path/for/end-user/to/follow"
}
]
}
}
]
}
Risposta dell'Assistente Google
Di seguito è riportato un esempio di risposta dell' Assistente Google:
{
"payload": {
"google": {
"expectUserResponse": true,
"richResponse": {
"items": [
{
"simpleResponse": {
"textToSpeech": "this is a Google Assistant response"
}
}
]
}
}
}
}
Contesto
Di seguito è riportato un esempio che imposta il contesto di output:
{
"fulfillmentMessages": [
{
"text": {
"text": [
"Text response from webhook"
]
}
}
],
"outputContexts": [
{
"name": "projects/project-id/agent/sessions/session-id/contexts/context-name",
"lifespanCount": 5,
"parameters": {
"param-name": "param-value"
}
}
]
}
Evento
Di seguito è riportato un esempio che richiama un evento personalizzato:
{
"followupEventInput": {
"name": "event-name",
"languageCode": "en-US",
"parameters": {
"param-name": "param-value"
}
}
}
Entità di sessione
Di seguito è riportato un esempio che imposta un' entità di sessione:
{
"fulfillmentMessages": [
{
"text": {
"text": [
"Choose apple or orange"
]
}
}
],
"sessionEntityTypes":[
{
"name":"projects/project-id/agent/sessions/session-id/entityTypes/fruit",
"entities":[
{
"value":"APPLE_KEY",
"synonyms":[
"apple",
"green apple",
"crabapple"
]
},
{
"value":"ORANGE_KEY",
"synonyms":[
"orange"
]
}
],
"entityOverrideMode":"ENTITY_OVERRIDE_MODE_OVERRIDE"
}
]
}
Payload personalizzato
Di seguito è riportato un esempio che fornisce un payload personalizzato:
{
"fulfillmentMessages": [
{
"payload": {
"facebook": { // for Facebook Messenger integration
"attachment": {
"type": "",
"payload": {}
}
},
"slack": { // for Slack integration
"text": "",
"attachments": []
},
"richContent": [ // for Dialogflow Messenger integration
[
{
"type": "image",
"rawUrl": "https://example.com/images/logo.png",
"accessibilityText": "Example logo"
}
]
],
// custom integration payload here
}
}
]
}
Abilitare e gestire il fulfillment
Per abilitare e gestire il fulfillment per l'agente con la console:
- Vai alla console di Dialogflow ES.
- Seleziona un agente.
- Seleziona Fulfillment nel menu laterale.
- Imposta il campo Webhook su Abilitato.
- Fornisci i dettagli del servizio webhook nel modulo. Se il webhook non richiede l'autenticazione, lascia vuoti i campi di autenticazione.
- Fai clic su Salva.
Per abilitare e gestire il fulfillment per l'agente con l'API, consulta il
riferimento dell'agente. I metodi getFulfillment e updateFulfillment consentono di gestire le impostazioni di fulfillment.
Per abilitare il fulfillment per un intent con la console:
- Seleziona Intent nel menu laterale a sinistra.
- Seleziona un intent.
- Vai alla sezione Fulfillment.
- Imposta l'opzione Abilita chiamata webhook per questo intent su On.
- Fai clic su Salva.
Per abilitare il fulfillment per un intent con l'API, consulta il
riferimento degli intent e imposta il
webhookState campo su WEBHOOK_STATE_ENABLED.
Errori webhook
Se il servizio webhook rileva un errore, deve restituire uno dei seguenti codici di stato HTTP:
400: richiesta errata401: non autorizzato403: accesso negato404: non trovato500: errore interno del server503: servizio non disponibile
In una delle seguenti situazioni di errore, Dialogflow risponde all'utente finale con la risposta integrata configurata per l'intent trovato:
- È stato superato il timeout della risposta.
- È stato ricevuto un codice di stato di errore.
- La risposta non è valida.
- Il servizio webhook non è disponibile.
Inoltre, se una chiamata API detect intent
attiva la corrispondenza dell'intent, il campo status nella risposta detect intent
contiene le informazioni sull'errore del webhook. Ad esempio:
"status": {
"code": 206,
"message": "Webhook call failed. <details of the error...>"
}
Nuovi tentativi automatici
Dialogflow ES include meccanismi interni che eseguono automaticamente nuovi tentativi in caso di determinati errori webhook per migliorare la robustezza. Vengono ritentati solo gli errori non terminali, come gli errori di timeout o di connessione.
Per ridurre la probabilità di chiamate duplicate:
- Imposta soglie di timeout del webhook più lunghe.
- Supporta l'idempotenza nella logica del webhook o deduplica le richieste.
Utilizzo di Cloud Run Functions
Puoi utilizzare Cloud Run Functions per il fulfillment in diversi modi. L'editor in linea di Dialogflow si integra con Cloud Run Functions. Quando utilizzi l'editor in linea per creare e modificare il codice del webhook, Dialogflow stabilisce una connessione sicura alla tua Cloud Function.
Puoi anche utilizzare una Cloud Function non creata dall'editor in linea. Se la Cloud Function si trova nello stesso progetto dell'agente, l'agente può chiamare il webhook senza richiedere alcuna configurazione speciale.
Tuttavia, devi configurare manualmente questa integrazione nelle seguenti due situazioni:
- Per il progetto dell'agente deve esistere il service account
Agente di servizio Dialogflow
con il seguente indirizzo:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
- Crea un nuovo agente per il progetto.
- Esegui questo comando:
gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
- Se la funzione webhook si trova in un progetto diverso da quello dell'agente, devi fornire il ruolo IAM Cloud Functions Invoker al account di servizio Agente di servizio Dialogflow nel progetto della funzione.
Token di identità del servizio
Quando Dialogflow chiama un webhook, fornisce un
token di identità Google
con la richiesta. Qualsiasi webhook può facoltativamente convalidare il token utilizzando le librerie client di Google
o le librerie open source come
github.com/googleapis/google-auth-library-nodejs.
Ad esempio, puoi verificare l'email del token ID come segue:
service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Esempi
Gli esempi seguenti mostrano come ricevere una WebhookRequest e inviare una WebhookResponse. Questi esempi utilizzano gli intent creati nella
guida rapida.
Go
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
import (
"encoding/json"
"fmt"
"log"
"net/http"
)
type intent struct {
DisplayName string `json:"displayName"`
}
type queryResult struct {
Intent intent `json:"intent"`
}
type text struct {
Text []string `json:"text"`
}
type message struct {
Text text `json:"text"`
}
// 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://godoc.org/google.golang.org/genproto/googleapis/cloud/dialogflow/v2#WebhookRequest
type webhookRequest struct {
Session string `json:"session"`
ResponseID string `json:"responseId"`
QueryResult queryResult `json:"queryResult"`
}
// 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://godoc.org/google.golang.org/genproto/googleapis/cloud/dialogflow/v2#WebhookResponse
type webhookResponse struct {
FulfillmentMessages []message `json:"fulfillmentMessages"`
}
// welcome creates a response for the welcome intent.
func welcome(request webhookRequest) (webhookResponse, error) {
response := webhookResponse{
FulfillmentMessages: []message{
{
Text: text{
Text: []string{"Welcome from Dialogflow Go Webhook"},
},
},
},
}
return response, nil
}
// getAgentName creates a response for the get-agent-name intent.
func getAgentName(request webhookRequest) (webhookResponse, error) {
response := webhookResponse{
FulfillmentMessages: []message{
{
Text: text{
Text: []string{"My name is Dialogflow Go Webhook"},
},
},
},
}
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)
// Call intent handler
switch intent := request.QueryResult.Intent.DisplayName; intent {
case "Default Welcome Intent":
response, err = welcome(request)
case "get-agent-name":
response, err = getAgentName(request)
default:
err = fmt.Errorf("Unknown intent: %s", intent)
}
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
}
}
Java
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Node.js
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Python
Per eseguire l'autenticazione in Dialogflow CX, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.