Registro de actividad con un webhook

Plus

Puede registrar la actividad efectuando una llamada a una aplicación o servicio externo cada vez que un cliente envíe una entrada al asistente.

Un webhook es un mecanismo que puede utilizar para llamar a un programa externo basado en eventos en su programa.

Esta función sólo está disponible para los usuarios de los planes Plus y Enterprise. El plan Plus no permite más de 5 webhooks de registro por instancia. Este límite no se aplica a las instancias del plan Enterprise.

Añada un webhook de registro a su asistente si desea utilizar un servicio externo para registrar la actividad. Puede registrar dos tipos de actividad:

Mensajes y respuestas: El webhook de registro se activa cada vez que el asistente responde a una entrada del cliente. Puede utilizar esta opción como alternativa a la característica de análisis incorporada para gestionar el registro por sí mismo. (Para obtener más información sobre el soporte de análisis incorporado, consulte Revisar todo el asistente de un vistazo).

Si utiliza un canal personalizado, el webhook de registro sólo funciona con la API v2 /message (con y sin estado). Para más información, consulte la referencia de la API. Todas las integraciones de canal incorporadas utilizan esta API.
Registros detallados de llamadas (CDR): El webhook de registro se activa después de cada llamada telefónica que un usuario realiza a su asistente que utiliza la integración telefónica. Un registro de detalles de llamadas (CDR) es un informe de resumen que documenta los detalles de una llamada telefónica, incluidos los números de teléfono, la duración de la llamada, la latencia y otra información de diagnóstico. Los registros CDR son sólo para los asistentes que utilizan la integración telefónica.

El webhook de registro no devuelve nada al asistente.

En entornos en los que se utilizan puntos finales privados, recuerde que el webhook envía tráfico a través de Internet.

Definición del webhook

Puede definir un URL de webhook que utilizar para registrar cada mensaje entrante o suceso de CDR.

La llamada mediante programa al servicio externo debe cumplir estos requisitos:

La llamada debe ser una solicitud POST HTTP.

Para añadir los detalles de webhook, complete los pasos siguientes:

En el asistente, abra el entorno en el que desea configurar el webhook.
Pulse el icono para abrir los valores de entorno.
En la página Configuración del entorno, haga clic en Registro webhook.
1. O, si está utilizando la experiencia clásica, abra la página Asistentes.
2. Para el asistente que desea configurar, pulse el icono y, a continuación, elija Valores.
3. Pulse Webhooks y, a continuación, pulse Registrar webhook.
Establezca el conmutador Webhook de registro en Habilitado.

Si no puede habilitar el webhook, es posible que tenga que actualizar el plan de servicio.
En el campo URL, añada el URL de la aplicación externa a la que desea enviar llamadas de solicitud POST de HTTP. Por ejemplo, https://example.com/my_log_service.

Debe especificar un URL que utilice el protocolo SSL, es decir, un URL que empiece por https.
En el campo Secreto, añada una señal que pasar con la solicitud y que se pueda utilizar para autenticarse en el servicio externo.

El secreto debe especificarse como una serie de texto, como, por ejemplo, purple unicorn. La longitud máxima es de 1.024 caracteres. No puede especificar una variable de contexto.

Es responsabilidad del servicio externo comprobar y verificar el secreto. Si el servicio externo no requiere un token, especifique cualquier cadena que desee. No puede dejar este campo vacío.

Si desea ver el secreto a medida que lo especifica, pulse el icono Mostrar contraseña antes de empezar a escribir. Después de guardar el secreto, la serie se sustituye por asteriscos y no se puede ver de nuevo.
Pulse los recuadros de selección adecuados para seleccionar los tipos de actividad que quiere registrar:
- Para registrar mensajes y respuestas, seleccione Suscribirse a registros de conversación.
- Para registrar sucesos de CDR para la integración telefónica, seleccione Suscribirse a CDR (registros de detalles de llamadas).
En la sección Headers, añada las cabeceras que quiera pasar al servicio de una en una, pulsando Añadir cabecera.

El servicio envía automáticamente una cabecera Authorization con una señal JWT; no es necesario añadir una. Si desea gestionar la autorización usted mismo, añada su propia cabecera de autorización y se utilizará en su lugar.

Después de guardar el valor de cabecera, la serie se sustituye por asteriscos y no se puede ver de nuevo.

Los detalles de su webhook se guardan de forma automática.

Eliminación del webhook

Si decide que no desea registrar mensajes con un webhook, siga estos pasos:

En el asistente, vaya a Entornos y abra el entorno donde desea configurar el webhook.
Pulse el icono para abrir los valores de entorno.
En la página Configuración del entorno, haga clic en Registro webhook.
1. O, si está utilizando la experiencia clásica, abra la página Asistentes.
2. Para el asistente que desea configurar, pulse el icono y, a continuación, elija Valores.
3. Pulse Webhooks y, a continuación, pulse Registrar webhook.
Realice una de las acciones siguientes:
- Para cambiar el webhook al que quiere llamar, pulse Suprimir webhook para suprimir el secreto y el URL especificados actualmente. A continuación, puede añadir una URL y otros detalles.
- Para dejar de llamar a un webhook que registre cada mensaje y cada respuesta, pulse el conmutador Webhook de registro para inhabilitar por completo el webhook.

Seguridad de webhook

Para autenticar la solicitud del webhook, verifique la señal web JSON (JWT) que se envía con la solicitud. El microservicio del webhook genera automáticamente una JWT y lo envía en la cabecera Authorization con cada llamada de webhook. Es responsabilidad del usuario añadir código al servicio externo que verifica la JWT.

Por ejemplo, si especifica purple unicorn en el campo Secreto, puede añadir código como:

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
}

Cuerpo de solicitud de webhook

El cuerpo de la petición que el webhook envía al servicio externo es un objeto JSON con la siguiente estructura:

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

donde {event_type} puede ser message_logged (para mensajes y respuestas) o cdr_logged (para sucesos de CDR).

El objeto payload contiene los datos de suceso que se van a registrar. La estructura del objeto payload depende del tipo de suceso.

Carga útil del suceso de mensaje

Para los eventos message_logged, el objeto payload contiene datos sobre una solicitud de mensaje que se envía al asistente y la respuesta de mensaje que se devuelve a la aplicación de integración o cliente. Para obtener más información sobre los campos que forman parte de las solicitudes y respuestas de mensajes, consulte la Referencia de API.

La carga útil del webhook del registro puede incluir datos que no estén soportados actualmente por la API. Los campos que no están definidos en la documentación de referencia de la API están sujetos a modificaciones.

Carga útil de sucesos de CDR

Para los sucesos cdr_logged, el objeto payload contiene datos sobre un suceso de CDR (Registro de detalles de llamadas) gestionado por la integración telefónica. La estructura del objeto payload para un suceso de CDR es la que se muestra en este ejemplo:

{
  "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": []
        }
      ]
    }
  ]
}

Para obtener más información sobre la estructura de la carga útil del evento CDR, consulte Referencia de eventos de registro CDR.