Webhook

I webhook sono servizi che ospitano la logica di business o chiamano altri servizi. Durante una sessione, i webhook consentono di utilizzare i dati estratti dall'elaborazione del linguaggio naturale di Dialogflow per generare risposte dinamiche, convalidare i dati raccolti o attivare azioni sul backend.

Un webhook può essere un web webhook standard o un webhook flessibile. Con un webhook standard, i campi di richiesta e risposta sono definiti da Dialogflow. Con un webhook flessibile, definisci i campi di richiesta e risposta.

Webhook standard

Con i webhook standard, utilizzi i messaggi di richiesta e risposta definiti da Dialogflow. Il messaggio di richiesta fornisce molti dettagli sulla sessione. Ad esempio, sono inclusi la pagina attiva corrente, l'intent con corrispondenza recente, i valori dei parametri di sessione e le risposte definite dall'agente.

Richiesta webhook standard

Quando viene chiamato un fulfillment con un webhook, Dialogflow invia una richiesta webhook POST HTTPS al tuo servizio webhook. Il corpo di questa richiesta è un oggetto JSON WebhookRequest con informazioni sulla sessione.

Alcune integrazioni compilano il campo WebhookRequest.payload con informazioni aggiuntive. Ad esempio, l'integrazione del gateway telefonico Dialogflow CX fornisce l'ID chiamante dell'utente finale.

Per maggiori dettagli, consulta la documentazione di riferimento WebhookRequest(V3) o WebhookRequest(V3Beta1).

Risposta webhook standard

Quando il servizio webhook riceve una richiesta di webhook, deve inviare una risposta webhook. Alla tua risposta si applicano le seguenti limitazioni:

  • La risposta deve avvenire entro un timeout che configuri durante la creazione della risorsa webhook, altrimenti la richiesta scadrà.
  • La risposta deve essere inferiore o uguale a 64 KiB.

Per maggiori dettagli, consulta la documentazione di riferimento WebhookResponse(V3) o WebhookResponse(V3Beta1).

Impostazioni delle risorse webhook standard

Di seguito vengono descritte le impostazioni delle risorse webhook per i webhook standard:

Termine Definizione
Nome visualizzato Il nome visualizzato nella console per il webhook.
Timeout webhook Quando Dialogflow invia una richiesta webhook al tuo servizio webhook, questa potrebbe scadere in attesa di una risposta. Questa impostazione controlla il timeout in secondi. Se si verifica un timeout, Dialogflow richiama un evento webhook.error.timeout.
Tipo Imposta Service Directory se utilizzi Service Directory per l'accesso alla rete privata, altrimenti impostalo su Generic web service (Servizio web generico).
URL webhook Fornisci l'indirizzo URL del servizio webhook.
Sottotipo Imposta su Standard
Webhook specifico per l'ambiente Puoi fornire webhook specifici per l'ambiente.
Autenticazione Consulta la sezione sull'autenticazione.
Certificato CA personalizzato Questo viene utilizzato per caricare i certificati CA personalizzati.

Webhook flessibili

Con i webhook flessibili, devi definire il metodo HTTP della richiesta, i parametri URL della richiesta e i campi dei messaggi di richiesta e risposta. La richiesta può fornire solo i valori dei parametri selezionati e la risposta può fornire solo i valori di override dei parametri. Questa limitazione è davvero vantaggiosa, perché semplifica l'interfaccia tra l'agente e il webhook. Raramente è necessario comunicare qualcosa di diverso dai valori dei parametri di sessione tra un agente e un webhook. Semplifica inoltre l'implementazione del webhook, perché i messaggi di richiesta e di risposta contengono solo ciò di cui hai bisogno e puoi fornire messaggi webhook univoci per vari scenari.

Richiesta webhook flessibile

Quando crei la risorsa webhook per l'agente, puoi specificare quanto segue per le richieste webhook:

  • Il metodo HTTP utilizzato per le richieste di webhook inviate al tuo servizio webhook.
  • Valori dei parametri di sessione che Dialogflow deve inviare al tuo servizio webhook utilizzando l'URL.
  • Se scegli POST, PUT o PATCH come metodo, puoi specificare i valori dei parametri di sessione che Dialogflow deve inviare al tuo servizio webhook tramite il corpo JSON della richiesta.

Per inviare i valori dei parametri di sessione utilizzando l'URL della richiesta o il corpo JSON, utilizza i riferimenti dei parametri come faresti normalmente. Non è necessario eseguire l'escape dell'URL del riferimento al parametro e non aggregarlo tra virgolette. In fase di esecuzione, Dialogflow esegue l'escape dell'URL delvalore parametroo in base alle esigenze. Un elenco o un valore composito verrà fornito in formato JSON.

Quando utilizzi un riferimento a un parametro nel corpo JSON, devi aggregarlo tra virgolette, indipendentemente dal tipo di parametro. Se il parametro è in realtà un valore scalare, elenco o composto numerico, Dialogflow rimuoverà le virgolette durante l'invio della richiesta in fase di runtime per conservare il tipo di dati del parametro. I tipi scalari delle stringhe rimarranno tra virgolette. Se all'interno di un valore stringa viene fatto riferimento a un valore scalare, elenco o composto numerico (ad esempio: "Questo è un numero: $session.params.size"), il parametro verrà considerato come una stringa ("Questo è un numero: 3").

Ad esempio, puoi fornire i valori dei parametri di sessione fruit e size all'URL della richiesta in questo modo:

https://your-webhook-service.com/handler?f=$session.params.fruit&s=$session.params.size

E al corpo JSON della richiesta in questo modo:

{
  "fruitParameter": "$session.params.fruit",
  "sizeParameter": "$session.params.size"
}

Risposta webhook flessibile

Quando crei la risorsa webhook per l'agente, puoi specificare i parametri di sessione che Dialogflow deve impostare in campi specifici della risposta webhook al runtime.

Alla tua risposta si applicano le seguenti limitazioni:

  • La risposta deve avvenire entro un timeout che configuri durante la creazione della risorsa webhook, altrimenti la richiesta scadrà.
  • La risposta deve essere inferiore o uguale a 64 KiB.

Utilizza il seguente formato per specificare un campo scalare, elenco o composto:

$.fully.qualified.path.to.field

Ad esempio, considera la seguente risposta JSON:

{
  "routes" : [
    {
      "legs" : [
        {
          "distance" : {
            "text" : "2,064 mi",
            "value" : 3321004
          }
        }
      ]
    }
  ]
}

Per specificare il campo "value", utilizza quanto segue:

$.routes[0].legs[0].distance.value

Impostazioni delle risorse webhook flessibili

Di seguito vengono descritte le impostazioni delle risorse per i webhook flessibili:

Termine Definizione
Nome visualizzato Il nome visualizzato nella console per il webhook.
Timeout webhook Quando Dialogflow invia una richiesta webhook al tuo servizio webhook, questa potrebbe scadere in attesa di una risposta. Questa impostazione controlla il timeout in secondi. Se si verifica un timeout, Dialogflow richiama un evento webhook.error.timeout.
Tipo Imposta Service Directory se utilizzi Service Directory per l'accesso alla rete privata, altrimenti impostalo su Generic web service (Servizio web generico).
URL webhook Fornisci l'indirizzo URL per il servizio webhook, che può includere riferimenti ai parametri di sessione.
Sottotipo Imposta su Flessibile
Metodo Imposta il metodo HTTP per la richiesta webhook.
Corpo della richiesta Fornisci il corpo JSON della richiesta come descritto sopra.
Configurazione della risposta Fornisci i parametri di sessione che devono essere impostati nei campi di risposta come descritto sopra.
Webhook specifico per l'ambiente Puoi fornire webhook specifici per l'ambiente.
Autenticazione Consulta la sezione sull'autenticazione.
Certificato CA personalizzato Questo viene utilizzato per caricare i certificati CA personalizzati.

Utilizza un modello personalizzato predefinito

Dialogflow offre modelli personalizzati predefiniti che puoi utilizzare per integrare webhook flessibili con il CRM di Salesforce.

  1. Nella scheda Gestisci, fai clic su Webhook, quindi su + Crea.

  2. In Sottotipo, seleziona Flessibile.

  3. Fai clic su Configura utilizzando un modello predefinito per attivare la funzionalità.

  4. Nel menu a discesa Tipo di integrazione, seleziona Salesforce.

  5. Nel menu a discesa Nome API, seleziona un nome API. Il modello compila automaticamente il modulo webhook in base al nome dell'API che scegli.

    1. Se applicabile, puoi configurare manualmente i seguenti campi in base ai tuoi parametri:

      • URL webhook
      • Metodo
      • JSON del corpo della richiesta
      • Configurazione della risposta

    2. I campi OAuth obbligatori verranno evidenziati nella sezione Autenticazione.

  6. Fai clic su Salva per creare il webhook.

Requisiti del servizio webhook

Il servizio webhook deve soddisfare i seguenti requisiti:

Autenticazione

È importante proteggere il servizio webhook, in modo che solo tu o l'agente Dialogflow siate autorizzati a effettuare richieste. Questo valore viene configurato durante la creazione di una risorsa webhook. Dialogflow CX supporta i seguenti meccanismi per l'autenticazione:

Termine Definizione
Intestazioni di autenticazione Per le impostazioni del webhook, puoi specificare coppie chiave-valore facoltative dell'intestazione HTTP. Se fornite, Dialogflow aggiunge queste intestazioni HTTP alle richieste webhook. È comune fornire una singola coppia con una chiave authorization. I valori di intestazione supportano i riferimenti dei parametri di sessione e l'analisi delle funzioni di sistema come nei messaggi di risposta statici.
Autorizzazione di base con nome utente e password Per le impostazioni webhook, puoi specificare valori facoltativi per nome utente e password di accesso. Se fornita, Dialogflow aggiunge un'intestazione HTTP di autorizzazione alle richieste webhook. Questa intestazione è nel modulo: "authorization: Basic <base 64 encoding of the string username:password>".
OAuth di terze parti Puoi specificare la configurazione OAuth di terze parti in modo che Dialogflow scambi un token di accesso dal provider OAuth e lo aggiunga nell'intestazione HTTP di autorizzazione. È supportato solo il flusso di credenziali client.
Token di accesso dell'agente di servizio Puoi selezionare il token di accesso nell'autenticazione dell'agente di servizio per utilizzare i token di accesso dell'agente di servizio per l'autenticazione. Può essere utilizzato per accedere ad altre API Google Cloud.
Token ID agente di servizio Puoi selezionare il token ID nell'autenticazione dell'agente di servizio per utilizzare i token ID dell'agente di servizio per l'autenticazione. Può essere utilizzato per accedere ai servizi della funzione Cloud Function e Cloud Run. Se non vengono utilizzate altre opzioni di autenticazione, l'opzione è abilitata per impostazione predefinita.
Autenticazione TLS reciproca Consulta la documentazione sull'autenticazione TLS reciproca.

Verifica del certificato HTTPS

Dialogflow utilizza per impostazione predefinita l'archivio di attendibilità predefinito di Google per verificare i certificati HTTPS. Se intendi utilizzare certificati non riconosciuti dall'archivio di attendibilità predefinito di Google per il tuo server HTTPS, ad esempio certificati autofirmati o certificati radice personalizzati, consulta la pagina relativa ai certificati CA personalizzati.

Webhook specifici dell'ambiente

Se utilizzi ambienti per isolare i sistemi di produzione dai sistemi di sviluppo (opzione consigliata), puoi configurare i webhook in modo che siano specifici dell'ambiente. Per ogni risorsa webhook che definisci, puoi fornire impostazioni di autenticazione e URL univoci per ogni ambiente che hai definito per l'agente.

Ciò consente di sviluppare e testare in modo sicuro gli aggiornamenti del codice dei webhook prima di eseguirne il deployment in produzione.

Crea o modifica risorse webhook

Quando è in esecuzione un servizio webhook, devi creare una risorsa webhook nell'agente che contenga informazioni su connettività e autenticazione. Dopo la creazione, puoi anche modificare le impostazioni delle risorse webhook in qualsiasi momento.

Per creare o modificare una risorsa webhook:

Console

  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 o fai clic su una risorsa webhook nell'elenco da modificare.
  7. Inserisci le impostazioni delle risorse webhook standard o le impostazioni delle risorse webhook flessibili.
  8. Fai clic su Salva.

API

Per creare una risorsa webhook, consulta il metodo create per il tipo Webhook. Per modificare una risorsa webhook (tranne le impostazioni specifiche dell'ambiente), vedi il metodo patch o update per il tipo Webhook.

Seleziona un protocollo e una versione per il riferimento webhook:

Protocollo V3 V3beta1
REST Risorsa webhook Risorsa webhook
RPC Interfaccia webhook Interfaccia webhook
C++ WebhooksClient Non disponibile
C# WebhooksClient Non disponibile
Go WebhooksClient Non disponibile
Java WebhooksClient WebhooksClient
Node.js WebhooksClient WebhooksClient
PHP Non disponibile Non disponibile
Python WebhooksClient WebhooksClient
Ruby Non disponibile Non disponibile

Per modificare le impostazioni specifiche dell'ambiente per un webhook, consulta il metodo patch o update per il tipo Environment.

Seleziona un protocollo e una versione per il riferimento Ambiente:

Protocollo V3 V3beta1
REST Risorsa dell'ambiente Risorsa dell'ambiente
RPC Interfaccia dell'ambiente Interfaccia dell'ambiente
C++ EnvironmentsClient Non disponibile
C# EnvironmentsClient Non disponibile
Go EnvironmentsClient Non disponibile
Java EnvironmentsClient EnvironmentsClient
Node.js EnvironmentsClient EnvironmentsClient
PHP Non disponibile Non disponibile
Python EnvironmentsClient EnvironmentsClient
Ruby Non disponibile Non disponibile

Errori webhook

Se il servizio webhook rileva un errore durante la gestione di una richiesta webhook, il codice webhook deve restituire uno dei seguenti codici di stato HTTP:

  • 400 Richiesta non valida
  • 401 non autorizzato
  • 403 Vietato
  • 404 non trovato
  • 500 Errore del server
  • 503 Servizio non disponibile

In una delle seguenti situazioni di errore, Dialogflow richiama un errore del webhook o un evento integrato di timeout e continua l'elaborazione come di consueto:

  • Timeout risposta superato.
  • Codice di stato di errore ricevuto.
  • La risposta non è valida.
  • Il servizio webhook non è disponibile.

Inoltre, se la chiamata di servizio webhook è stata attivata da una chiamata API di rilevamento dell'intent, il campo queryResult.webhookStatuses nella risposta di rilevamento dell'intent contiene le informazioni sullo stato del webhook.

Utilizzo di Cloud Functions

Dialogflow si integra con Cloud Functions per consentirti di creare facilmente un webhook serverless e sicuro. Se crei una funzione che risiede nello stesso progetto del tuo agente, quest'ultimo può chiamare in modo sicuro il webhook senza bisogno di una configurazione speciale.

Tuttavia, esistono due situazioni in cui è necessario configurare manualmente questa integrazione:

  1. Per il progetto dell'agente deve esistere l'account di servizio dell'agente di servizio Dialogflow con il seguente indirizzo: 
    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
    Questo account di servizio speciale e la chiave associata vengono solitamente creati automaticamente quando crei il primo agente per un progetto. Se il tuo agente è stato creato prima del 1° novembre 2020, puoi attivare la creazione di questo account di servizio speciale:
    1. Crea un nuovo agente per il progetto.
    2. Esegui questo comando: 
      gcloud beta services identity create --service=dialogflow.googleapis.com --project=agent-project-id
  2. Se la funzione webhook si trova in un progetto diverso dall'agente, devi fornire il ruolo IAM Invoker di Cloud Functions all'account di servizio dell'agente di servizio Dialogflow nel progetto della funzione.

Utilizzo di webhook containerizzati e del framework Go ezcx

Se vuoi implementare un webhook containerizzato utilizzando Go, consulta il framework Go ezcx. Questo framework può semplificare molti dei passaggi necessari per creare un webhook.

Utilizzo di Service Directory per l'accesso alla rete privata

Dialogflow si integra con l'accesso alla rete privata di Service Directory per potersi connettere a destinazioni webhook all'interno della tua rete VPC. In questo modo il traffico viene mantenuto all'interno della rete Google Cloud e vengono applicati IAM e Controlli di servizio VPC.

Per impostare un webhook che abbia come target una rete privata:

  1. Segui la configurazione della rete privata di Service Directory per configurare la rete VPC e l'endpoint di Service Directory.

  2. Per il progetto dell'agente deve esistere l'account di servizio dell'agente di servizio Dialogflow con il seguente indirizzo: 

    service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
    Concedi all'account di servizio dell'agente di servizio Dialogflow i seguenti ruoli IAM:

    • servicedirectory.viewer del progetto Service Directory
    • servicedirectory.pscAuthorizedService del progetto di rete

  3. fornisci il servizio Service Directory insieme all'URL e alle informazioni di autenticazione facoltative durante la creazione del webhook.

    Console

    Screenshot del webhook Service Directory.

    API

    Controlla il campo serviceDirectory per il tipo Webhook.

    Seleziona un protocollo e una versione per il riferimento webhook:

    Protocollo V3 V3beta1
    REST Risorsa webhook Risorsa webhook
    RPC Interfaccia webhook Interfaccia webhook
    C++ WebhooksClient Non disponibile
    C# WebhooksClient Non disponibile
    Go WebhooksClient Non disponibile
    Java WebhooksClient WebhooksClient
    Node.js WebhooksClient WebhooksClient
    PHP Non disponibile Non disponibile
    Python WebhooksClient WebhooksClient
    Ruby Non disponibile Non disponibile

Per risolvere i problemi, puoi impostare un controllo di uptime privato per verificare che Service Directory sia configurato correttamente.

Autorizzazione agente di servizio

Dialogflow può generare un token ID o un token di accesso utilizzando l'agente di servizio Dialogflow.

Il token viene aggiunto nell'intestazione HTTP di autorizzazione quando Dialogflow chiama un webhook.

Token ID

Un token ID può essere utilizzato per accedere ai servizi della funzione Cloud Function e Cloud Run dopo aver concesso il ruolo Invoker a 

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com
Se la funzione Cloud Function e i servizi Cloud Run si trovano nello stesso progetto di risorse, non è necessaria un'autorizzazione IAM aggiuntiva per chiamarli.

Il segmento di pubblico utilizzato per generare il token ID sarà l'intero URL webhook, tranne eventuali parametri di ricerca. Se utilizzi Cloud Run, assicurati che questo URL sia supportato dai segmenti di pubblico Cloud Run. Ad esempio, se l'URL webhook è

https://myproject.cloudfunctions.net/my-function/method1?query=value

il seguente URL deve trovarsi in segmenti di pubblico personalizzati.

https://myproject.cloudfunctions.net/my-function/method1

Qualsiasi webhook può anche convalidare il token utilizzando librerie client di Google o librerie open source come github.com/googleapis/google-auth-library-nodejs.

Token di accesso

Un token di accesso può essere utilizzato per accedere ad altre API Google Cloud dopo aver concesso i ruoli richiesti a 

service-agent-project-number@gcp-sa-dialogflow.iam.gserviceaccount.com

Esempi e risoluzione dei problemi

Consulta la guida illustrativa del webhook.

Indietro
Fulfillment
Avanti
Modelli vocali