Registrazione dell'attività con un webhook

Plus

Puoi registrare l'attività effettuando una chiamata a un servizio o un'applicazione esterna ogni volta che un cliente inoltra l'input all'assistente.

Un webhook è un meccanismo che si può usare per chiamare un programma esterno in base a eventi del proprio programma.

Questa funzione è disponibile solo per gli utenti dei piani Plus ed Enterprise. Il piano Plus non consente più di 5 webhook di log per istanza. Questo limite non si applica alle istanze del piano Enterprise.

Aggiungi un webhook di log al tuo assistente se vuoi utilizzare un servizio esterno per registrare l'attività. È possibile registrare due tipi di attività:

Messaggi e risposte: il webhook di log viene attivato ogni volta che l'assistente risponde all'input del cliente. È possibile utilizzare questa opzione come alternativa alla funzione di analisi integrata per gestire la registrazione. (Per ulteriori informazioni sul supporto di analisi integrato, vedi Rivedi il tuo intero assistente a colpo d'occhio.)

Se stai usando un canale personalizzato, il webhook di log funziona solo con l'API v2 /message (stateless e stateful). Per ulteriori informazioni, consultare il riferimento API. Tutte le integrazioni del canale integrate utilizzano questa API.
CDR (Call detail records): il webhook di log viene attivato dopo ogni chiamata telefonica effettuata da un utente al tuo assistente che utilizza l'integrazione telefonica. Un CDR (Call Detail Record) è un report di riepilogo che documenta i dettagli di una chiamata telefonica, inclusi i numeri di telefono, la lunghezza della chiamata, la latenza e altre informazioni diagnostiche. I record CDR sono solo per gli assistenti che utilizzano l'integrazione telefonica.

Il webhook di log non restituisce nulla al tuo assistente.

Per gli ambienti in cui si utilizzano endpoint privati, tenere presente che un webhook invia traffico su Internet.

Definizione del webhook

Puoi definire un URL webhook da utilizzare per la registrazione di ogni messaggio in entrata o evento CDR.

La chiamata programmatica al servizio esterno deve soddisfare questi requisiti:

La chiamata deve essere una richiesta POST HTTP.

Per aggiungere i dettagli webhook, completa i seguenti passi:

Nel tuo assistente, apri l'ambiente in cui vuoi configurare il webhook.
Fare clic sull'icona per aprire le impostazioni di ambiente.
Nella pagina Impostazioni di ambiente, fai clic su Log webhook.
1. In alternativa, se stai utilizzando l'esperienza classica, apri la pagina Assistants.
2. Per l'assistente che desideri configurare, fai clic sull'icona e scegli Impostazioni.
3. Fai clic su Webhooks, quindi su Log webhook.
Imposta lo switch Log webhook su Enabled.

Se non puoi abilitare il webhook, potresti dover eseguire l'upgrade del tuo piano di servizio.
Nel campo URL, aggiungi l'URL per l'applicazione esterna a cui vuoi inviare i callout della richiesta POST HTTP. Ad esempio, https://example.com/my_log_service.

È necessario specificare un URL ( URL ) che utilizzi il protocollo SSL, quindi specificare un URL ( URL ) che inizi con https.
Nel campo Segreto, aggiungi un token da passare con la richiesta che puoi utilizzare per l'autenticazione con il servizio esterno.

Il segreto deve essere specificato come una stringa di testo, ad esempio purple unicorn. La lunghezza massima è di 1.024 caratteri. Non è possibile specificare una variabile di contesto.

È responsabilità del servizio esterno controllare e verificare il segreto. Se il servizio esterno non richiede un token, specificare la stringa desiderata. Non è possibile lasciare vuoto questo campo.

Se si desidera visualizzare il segreto mentre lo si immette, fare clic sull'icona Mostra password prima di iniziare a digitare. Dopo aver salvato il segreto, la stringa viene sostituita da asterischi e non può più essere visualizzata.
Fare clic sulle caselle di spunta appropriate per selezionare i tipi di attività che si desidera registrare:
- Per registrare messaggi e risposte, selezionare Sottoscrivi ai log di conversazione.
- Per registrare gli eventi CDR per l'integrazione telefonica, selezionare Sottoscrivi a CDR (Call Detail Records).
Nella sezione Headers, aggiungi le intestazioni che vuoi passare al servizio una alla volta facendo clic su Add header.

Il servizio invia automaticamente un'intestazione Authorization con un JWT; non è necessario aggiungerne una. Se si desidera gestire l'autorizzazione da soli, aggiungere la propria intestazione di autorizzazione e verrà utilizzata.

Dopo aver salvato il valore di intestazione, la stringa viene sostituita da asterischi e non può più essere visualizzata.

I dettagli del tuo webhook vengono salvati automaticamente.

Rimozione del webhook

Se decidi di non voler registrare i messaggi con un webhook, completa la seguente procedura:

Nel tuo assistente, vai a Ambienti e apri l'ambiente in cui vuoi configurare il webhook.
Fare clic sull'icona per aprire le impostazioni di ambiente.
Nella pagina Impostazioni di ambiente, fai clic su Log webhook.
1. In alternativa, se stai utilizzando l'esperienza classica, apri la pagina Assistants.
2. Per l'assistente che desideri configurare, fai clic sull'icona e scegli Impostazioni.
3. Fai clic su Webhooks, quindi su Log webhook.
Effettua una delle operazioni riportate di seguito:
- Per modificare il webhook che si desidera richiamare, fare clic su Elimina webhook per eliminare l' URL e il segreto attualmente specificati. È quindi possibile aggiungere un URL e altri dettagli.
- Per interrompere la chiamata di un webhook per registrare ogni messaggio e risposta, fai clic sullo switch Log webhook per disabilitare completamente il webhook.

Sicurezza webhook

Per autenticare la richiesta webhook, verificare il JWT (JSON Web Token) inviato con la richiesta. Il microservizio webhook genera automaticamente un JWT e lo invia nell'intestazione Authorization con ogni chiamata webhook. È responsabilità dell'utente aggiungere del codice al servizio esterno che verifica il JWT.

Ad esempio, se si specifica purple unicorn nel campo Segreto, è possibile aggiungere codice come:

const jwt = require('jsonwebtoken');
...
const token = request.headers.authentication; // grab the "Authentication" header
try {
  const decoded = jwt.verify(token, 'purple unicorn');
} catch(err) {
  // error thrown if token is invalid
}

Corpo della richiesta webhook

Il corpo della richiesta che il webhook invia al servizio esterno è un oggetto JSON con la struttura seguente:

{
  "event": {
    "name": "{event_type}"
   },
  "payload": {
    ...
  }
}

dove {event_type} è message_logged (per messaggi e risposte) o cdr_logged (per eventi CDR).

L'oggetto payload contiene i dati evento da registrare. La struttura dell'oggetto payload dipende dal tipo di evento.

Payload evento messaggio

Per gli eventi message_logged, l'oggetto payload contiene i dati relativi a una richiesta di messaggio che viene inviata all'assistente e la risposta del messaggio che viene restituita all'applicazione client o di integrazione. Per ulteriori informazioni sui campi che fanno parte delle richieste e risposte dei messaggi, vedi la Guida di riferimento API.

Il payload del webhook di log potrebbe includere dati che non sono attualmente supportati dall'API. Tutti i campi non definiti nella documentazione di riferimento API sono soggetti a modifiche.

Payload evento CDR

Per gli eventi cdr_logged, l'oggetto payload contiene i dati relativi a un evento CDR (Call Detail Record) gestito dall'integrazione telefonica. La struttura dell'oggetto payload per un evento CDR è il seguente esempio:

{
  "primary_phone_number": "+18005550123",
  "global_session_id": "9caa8bad-aaa8-4a5a-a4b5-62bccc703d15",
  "failure_occurred": false,
  "transfer_occurred": false,
  "active_calls": 0,
  "warnings_and_errors": [
    {
      "code": "CWSMR0033W",
      "message": "CWSMR0033W: The inbound RTP audio stream jitter of 43 ms exceeds the maximum jitter threshold of 30 ms."
    },
    {
      "code": "CWSMR0070W",
      "message": "CWSMR0070W: A request to the Watson Speech To Text service failed for the following reason = Unexpected server response: 403, response headers = {\"strict-transport-security\":\"max-age=31536000; includeSubDomains;\",\"content-length\":\"157\",\"content-type\":\"application/json\",\"x-dp-watson-tran-id\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"x-request-id\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"x-global-transaction-id\":\"6c764df3-81db-41bb-a14f-62384facffca\",\"server\":\"watson-gateway\",\"x-edgeconnect-midmile-rtt\":\"1\",\"x-edgeconnect-origin-mex-latency\":\"28\",\"date\":\"Thu, 13 May 2021 20:31:12 GMT\",\"connection\":\"keep-alive\"}, response body = {\"code\":403,\"trace\":\"23860083-88b6-41d7-9130-30bbfebe647e\",\"error\":\"Forbidden\",\"more_info\":\"[https://cloud.ibm.com/docs/watson?topic=watson-forbidden-error](https://cloud.ibm.com/docs/watson?topic=watson-forbidden-error)\"}, x-global-transaction-id = 6c764df3-81db-41bb-a14f-62384facffca. The Media Relay will reattempt to send the request."
    }
  ],
  "realtime_transport_network_summary": {
    "inbound_stream": {
      "average_jitter": 4,
      "canonical_name": "b74f3689-1ae8-4a0a-bde3-adf5b488553e",
      "maximum_jitter": 18,
      "packets_lost": 0,
      "packets_transmitted": 952,
      "tool_name": ""
    },
    "outbound_stream": {
      "average_jitter": 0,
      "canonical_name": "voice.gateway",
      "maximum_jitter": 0,
      "packets_lost": 0,
      "packets_transmitted": 838,
      "tool_name": "IBM Voice Gateway/1.0.7.0"
    }
  },
  "call": {
    "start_timestamp": "2021-10-12T20:54:02.591Z",
    "stop_timestamp": "2021-10-12T20:54:20.375Z",
    "milliseconds_elapsed": 17784,
    "outbound": false,
    "end_reason": "assistant_hangup",
    "security": {
      "media_encrypted": false,
      "signaling_encrypted": false,
      "sip_authenticated": false
    }
  },
  "session_initiation_protocol": {
    "invite_arrival_time": "2021-10-12T20:54:00.565Z",
    "setup_milliseconds": 2026,
    "headers": {
      "call_id": "17465345_115257202@10.90.150.99",
      "from_uri": "sip:+18885550456@pstn.twilio.com",
      "to_uri": "sip:+18005550123@public.voip.us-south.assistant.test.watson.cloud.ibm.com"
    }
  },
  "max_response_milliseconds": {
    "assistant": 339,
    "text_to_speech": 535,
    "speech_to_text": 0
  },
  "assistant_interaction_summaries": [
    {
      "session_id": "7874ec3a-1330-4180-afe1-46bfb220af5b",
      "assistant_id": "97f16ba4-ad94-41af-aa6c-33cd56ad5e7e",
      "turns": [
        {
          "assistant": {
            "log_id": "58bebfd1-0118-419b-a555-b152a1efbbe8",
            "response_milliseconds": 339,
            "start_timestamp": "2021-10-12T20:54:00.722Z"
          },
          "request": {
            "type": "start"
          },
          "response": [
            {
              "barge_in_occurred": true,
              "streaming_statistics": {
                "response_milliseconds": 301,
                "start_timestamp": "2021-10-12T20:54:00.722Z",
                "stop_timestamp": "2021-10-12T20:54:01.023Z",
                "transaction_id": "3dce431c-fb2f-4b62-9fce-585f4e06fe00"
              },
              "type": "text_to_speech"
            }
          ]
        },
        {
          "assistant": {
            "log_id": "38f36bfb-c2aa-4600-9418-6ab422664e31",
            "response_milliseconds": 158,
            "start_timestamp": "2021-10-12T20:54:05.621Z"
          },
          "request": {
            "type": "dtmf"
          },
          "response": [
            {
              "type": "disable_speech_barge_in"
            },
            {
              "type": "text_to_speech",
              "barge_in_occurred": false,
              "streaming_statistics": {
                "transaction_id": "af4c47c3-5cc4-43c8-9b9c-81d6f997c52f",
                "start_timestamp": "2021-10-12T20:54:06.321Z",
                "stop_timestamp": "2021-10-12T20:54:14.338Z",
                "response_milliseconds": 535
              }
            },
            {
              "type": "enable_speech_barge_in"
            },
            {
              "type": "text_to_speech",
              "barge_in_occurred": true,
              "streaming_statistics": {
                "transaction_id": "eafdd846-2829-4e1a-8068-b1035510b1e1",
                "start_timestamp": "2021-10-12T20:54:14.795Z",
                "stop_timestamp": "2021-10-12T20:54:20.388Z",
                "response_milliseconds": 447
              }
            }
          ]
        },
        {
          "assistant": {
            "log_id": "07d74b35-0205-43e4-923c-1e43e1cb429c",
            "response_milliseconds": 0,
            "start_timestamp": "2021-10-12T20:54:20.377Z"
          },
          "request": {
            "type": "hangup"
          },
          "response": []
        }
      ]
    }
  ]
}

Per ulteriori informazioni sulla struttura del payload eventi CDR, vedi Riferimento agli eventi di log CDR.