Guía de la API de la plataforma de chat

En esta página, se muestra cómo usar los extremos de chat, como se describe en Extremos de la API de la plataforma de chat.

Terminología

Para mayor claridad, aquí tienes algunas definiciones que son importantes tener en cuenta cuando uses este documento.

  • Cliente: Es el cliente de Contact Center AI Platform (CCAI Platform) que implementa la API de la plataforma de chat en su software.

  • Consumidor: Es el software que realiza solicitudes a la API de la plataforma de chat.

  • Usuario final: Es el usuario del software del cliente que intenta realizar un chat con un agente.

Autenticación de webhook

La API de la plataforma de chat comunica los eventos que tienen lugar durante el chat al consumidor mediante el envío de solicitudes de webhook al servidor del consumidor. Las cargas útiles y los tipos de webhook se definen en la especificación de la API. Cada solicitud de webhook contiene dos encabezados: X-Signature y X-Signature-Timestamp.

X-Signature contiene una firma de webhook con el siguiente formato: primary=<primary_signature> secondary=<secondary_signature>

Las firmas primarias y secundarias son un resumen sha256 codificado en base64 de los secretos de webhook primarios o secundarios, respectivamente, con una cadena concatenada del encabezado X-Signature-Timestamp y la carga útil JSON de la solicitud.

El siguiente es un ejemplo de implementación de autorización para las solicitudes de webhook en una app de muestra de Ruby on Rails:

def authorize_webhook
    # In a real consumer use case, these webhook secrets would be
    # stored/retrieved along with other application secrets, however the application chooses to do that
    primary_secret = @company.primary_webhook_secret
    secondary_secret = @company..secondary_webhook_secret

    signature_header = request.headers['X-Signature']
    timestamp_header = request.headers['X-Signature-Timestamp']

    if signature_header.present? && timestamp_header.present?

      # Header will be in the format "primary=abcdefg12341234 secondary=qwertyuiop567890" if a tenant has both webhook
      # secrets generated in Contact Center AI Platform, otherwise it will be in the format ""primary=abcdefg12341234"
      primary_signature, secondary_signature = signature_header.scan(/primary=(.*)\ssecondary=(.*)/).flatten

      # Optional: check age of request timestamp to protect against replays
      # raise UnauthorizedException unless Time.now - timestamp_header.to_time < 1.minute

      # String value of the request body JSON
      payload = request.body.read

      expected_primary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, primary_secret, "#{timestamp_header}#{payload}"))
      expected_secondary_signature = Base64.strict_encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA256.new, secondary_secret, "#{timestamp_header}#{payload}"))

      # Only one signature needs to be valid, this allows for easier rotation of secrets in the Contact Center AI Platform developer portal
      if primary_signature == expected_primary_signature || primary_signature == expected_secondary_signature ||
        secondary_signature == expected_primary_signature || secondary_signature == expected_secondary_signature
        true
      else
        head :unauthorized
      end

    else
      head :bad_request
    end
  end

Descripción general

En general, el flujo básico de una conversación de la API de la plataforma de chat debería ser el siguiente. Los puntos clave están numerados y se proporcionan notas para obtener contexto adicional. Ten en cuenta que el cliente solo es responsable de implementar el lado "Cliente" del diagrama, mientras que Contact Center AI Platform controla los lados de nuestro sistema y del agente del diagrama. Su inclusión en el diagrama solo tiene como objetivo brindar al lector contexto para el flujo general de un chat.

Se muestra el flujo de una conversación de la API de la plataforma de chat.

Crea usuarios finales

  • Los chats requieren un ID de usuario final válido cuando se crean, lo que significa que un usuario final debe existir en el sistema de Contact Center AI Platform antes de que se cree un chat.

  • Los usuarios finales se identifican de forma única por su atributo identifier, que es un valor de cadena proporcionado por el consumidor. Es posible que un usuario final ya exista en el sistema si usó los SDKs para Web o para dispositivos móviles. El extremo POST /end_users se implementa como una inserción o actualización idempotente, por lo que, en el caso de un usuario final existente, si intentas crearlo de nuevo, se actualizarán los datos modificados y se mostrará la información del usuario final.

Crea chats

Para crear chats con la API de la plataforma de chat, sigue estos pasos:

  1. Manejo de cargas útiles de chats nuevos: El proceso de inicialización del chat se realiza de forma asíncrona desde la solicitud POST /chats. Debido a esto, es posible que se reciba el evento chat_created antes o después de la respuesta de la API del extremo de creación POST /chats. Se recomienda controlar el evento chat_created y la respuesta de la API de creación de chat de forma idempotente para evitar errores en el consumidor.

  2. Creación de chats con transcripciones: La API de la plataforma de chat admite la creación de un chat con una transcripción de una conversación existente, para una situación en la que se produce un chat dentro de la plataforma de un cliente, por ejemplo, con un chatbot, antes de enviarlo a Contact Center AI Platform. Esto proporciona al agente que responde el chat información adicional sobre la sesión de chat y ayuda a evitar que el usuario final se repita. Para obtener el formato de carga útil de la transcripción, consulta chat_platform_openapi.yaml.

El agente virtual de selección de colas

Para optimizar la selección de menú para los consumidores de la API, la API de la plataforma de chat está diseñada para usarse junto con un agente virtual de Dialogflow para ayudar a la ubicación de la cola para chats nuevos.

Se deben seguir los siguientes pasos para configurar el agente virtual:

  1. Crea un agente virtual designado para este propósito y asígnalo a una cola. Todos los chats nuevos creados por la API de la plataforma de chat deben crearse en esta cola. La creación y configuración de un agente virtual nuevo no están dentro del alcance de este documento.

  2. Cuando crees un chat nuevo con el extremo POST o chats, incluye una carga útil de contexto personalizado que incluya algo de contexto sobre el chat creado que el agente virtual pueda usar para determinar a qué cola se debe enrutar el chat. La carga útil de contexto puede contener cualquier dato personalizado según lo defina el cliente, pero debe tener el siguiente formato para que el agente virtual asignado a la cola pueda acceder a los datos.

    • Ejemplo: "context": {"value": {"foo": "bar" } } permitiría que el agente virtual leyera $session.params.context.foo con un valor de bar.

  3. Con los datos contenidos en el campo de contexto, el agente virtual (según la configuración del cliente) aumenta el chat a la cola seleccionada. Si no hay ningún agente disponible en la cola de destino (como una situación en la que una cola está fuera de horario o supera la capacidad), se desvía el aumento y el consumidor recibe un webhook que indica el motivo de la desviación y las opciones de desviación disponibles.

Desviaciones de aumento: Los aumentos de chat en la API de la plataforma de chat admiten las siguientes opciones de desviación, si están configuradas en el portal de Contact Center AI Platform portal:

  • Correo electrónico: Haz que el usuario final envíe un correo electrónico al equipo de asistencia y finalice el chat. Cuando un usuario final selecciona esta opción, después de que se envía el correo electrónico, el cliente deberá marcar el chat como desviado y finalizado con el PATCH /chats/:id extremo con los siguientes parámetros en el cuerpo de la solicitud: "status": "finished" , "escalation_id": &lt;id of escalation> , y "deflection_channel": "email"

  • Continuar con el agente virtual: Técnicamente, esta es una opción de desviación válida , pero no tiene sentido usar el VA de selección de colas, ya que el VA volvería a intentar aumentar el chat.

  • Seguir esperando al agente humano: Esta opción solo se puede usar para aumentos con un motivo de over_capacity. Si el usuario final elige esta opción, actualiza la desviación de aumento con PATCH chats/:id/escalations/:id with deflection_channel=human_agent.

    • Vínculo externo de desviación: Advierte al usuario final que, si selecciona un vínculo proporcionado en la desviación, se finalizará el chat. Si se selecciona un vínculo, finaliza el chat y usa external_link para el parámetro deflection_channel.

Envía y recibe mensajes

Para enviar o recibir mensajes, sigue estos pasos:

  1. Contenido de texto: Para enviar mensajes de texto, usa el POST /chats/:id/message extremo como se define en el documento de la API. Para recibir mensajes, escucha el message_received evento de webhook. Ten en cuenta que el consumidor de la API recibirá un evento message_received para todos los mensajes enviados con la API, incluidos los mensajes enviados por el usuario final.

  2. Contenido de fotos y videos: El contenido de fotos y videos se envía recuperando una URL de carga previamente firmada para un servicio de Cloud Storage configurado desde Contact Center AI Platform, subiendo al servicio de almacenamiento y, luego, enviando la URL de almacenamiento en una carga útil de mensaje a Contact Center AI Platform.

    1. Recuperación de la URL previamente firmada: Recupera una URL de carga previamente firmada de Contact Center AI Platform con los extremos POST /v1/chats/:chat_id/photos/upload o POST /v1/chats/:chat_id/videos/upload endpoints. Este extremo muestra una URL previamente firmada, junto con una colección de campos para reenviar al servicio de almacenamiento cuando se sube el archivo. Las cargas previamente firmadas tienen las siguientes restricciones:

      • El tipo de contenido es image/jpeg para fotos y video/mp4 para videos.

      • El tamaño máximo de la foto es de 2 MB. El tamaño máximo del video es de 20 MB.

      • El tiempo de vencimiento es de 5 minutos.

      • El cliente debe cambiar el tamaño y ajustar la orientación de la foto antes de subirla.

      • Cada URL previamente firmada es para una sola foto o video. Para enviar varios archivos adjuntos, debes solicitar una URL previamente firmada para cada uno.

    2. Subida del archivo multimedia: Para subir el archivo multimedia, realiza una solicitud POST a la URL previamente firmada recuperada en 2a con lo siguiente en el cuerpo de la solicitud:

      • "file": el archivo que se subirá

      • Todos los campos que se muestran en el objeto de campos en la solicitud de URL previamente firmada.

    3. Agrega el archivo multimedia al chat: Para agregar el archivo multimedia al chat, usa el extremo POST /chats/:id/photos o POST /chats/:id/videos. Ten en cuenta que el extremo de fotos admite el envío de un array de fotos, mientras que el extremo de video solo admite un video a la vez.

      • El parámetro del cuerpo de la solicitud s3_path debe tener el mismo valor que el campo key de la respuesta de la URL previamente firmada.

      • La solicitud mostrará dos campos si se realiza correctamente. Se recomienda guardar o almacenar en caché una asignación de media_id a la URL en el consumidor de la API, ya que se hará referencia a todo el contenido multimedia en los mensajes de chat solo por media_id.

        • url: la URL de S3 o Cloud Storage de solo lectura en la que se encuentra el archivo.

        • media_id: el ID del archivo multimedia en Contact Center AI Platform. Este es el ID por el que se hará referencia al contenido multimedia en las cargas útiles de chat.

    4. Envía el archivo multimedia como un mensaje de chat: Para enviar el archivo multimedia como un mensaje de chat, envía la siguiente carga útil a POST /chats/:id/message endpoint:

    {
  "from_user_id": <id of end user>,
  "message": {
    "type": <"photo" or "video">,
    "media_id": < media_id returned as described in 2.c >
  }
}

Espera claves JSON no reconocidas en las respuestas de la API

Todas las actualizaciones de la API son retrocompatibles. Nos reservamos el derecho de introducir nuevas claves JSON en las respuestas de la API existentes en cualquier momento. Te recomendamos que manejes las respuestas de forma defensiva y que ignores las claves no reconocidas para mantener la funcionalidad continua.