Guía de la API de la plataforma de chat

En la 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, a continuación, se incluyen algunas definiciones importantes que debes 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 chatear 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 enviando solicitudes de webhook al servidor del consumidor. Los tipos y las cargas útiles 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 principal y secundaria son un resumen sha256 codificado en base64 de los secretos de webhook principal o secundario, respectivamente, con una cadena concatenada del encabezado X-Signature-Timestamp y la carga útil json de la solicitud.

A continuación, se muestra un ejemplo de implementación de la autorización para las solicitudes de webhook en una app de Ruby on Rails de muestra:

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 brindar contexto adicional. Ten en cuenta que el cliente solo es responsable de implementar el lado del "cliente" del diagrama, mientras que Contact Center AI Platform se encarga de los lados del sistema y del agente del diagrama. Su inclusión en el diagrama solo tiene el objetivo de brindar al lector contexto sobre el flujo general de un chat.

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

Cómo crear usuarios finales

Los chats requieren un ID de usuario final válido cuando se crean, lo que significa que debe existir un usuario final 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 web o para dispositivos móviles. El extremo POST /end_users se implementa como una inserción idempotente, por lo que, en el caso de un usuario final existente, intentar crearlo de nuevo actualizará los datos modificados y devolverá la información del usuario final.

Crear chats

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

Cómo controlar cargas útiles de chat nuevas: El proceso de inicialización del chat se produce de forma asíncrona a partir de la solicitud POST /chats. Por lo tanto, es posible que el evento chat_created se reciba antes o después de la respuesta de la API del extremo de creación de 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.
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 un caso en el que se produce un chat dentro de la plataforma de un cliente, por ejemplo, con un chatbot, antes de enviarse a Contact Center AI Platform. Esto le proporciona al agente que responde el chat información adicional sobre la sesión y ayuda a evitar que el usuario final repita lo que ya dijo. Para conocer el formato de la 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ús para los consumidores de la API, la API de la plataforma de chat está diseñada para usarse en conjunto con un agente virtual de Dialogflow para ayudar a colocar en la fila los chats nuevos.

Para configurar el agente virtual, debes seguir estos pasos:

Crea un agente virtual designado para este propósito y asígnalo a una cola. Todas las conversaciones nuevas creadas 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 se incluyen en el alcance de este documento.
Cuando crees un chat nuevo con el extremo POST o chats, incluye una carga útil de contexto personalizada 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 del 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 fila 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.
Con los datos incluidos en el campo de contexto, el agente virtual (según la configuración del cliente) deriva el chat a la fila seleccionada. Si no hay agentes disponibles en la cola de destino (por ejemplo, en un caso en el que la cola está fuera de horario o con capacidad excedida), se desvía la derivación y el cliente recibe un webhook que indica el motivo del desvío y las opciones de desvío disponibles.

Desvíos de derivaciones: Las derivaciones de chat en la API de la plataforma de chat admiten las siguientes opciones de desvío, si se configuran en el portal de Contact Center AI Platform:

Correo electrónico: Pídele al usuario final que 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 extremo PATCH /chats/:id y los siguientes parámetros en el cuerpo de la solicitud: "status": "finished" , "escalation_id": <id of escalation> , y "deflection_channel": "email".
Continuar con el agente virtual: Técnicamente, esta es una opción de desvío válida. Sin embargo, no tiene sentido usar el AV de selección de filas, ya que el AV solo intentaría derivar el chat nuevamente.
Seguir esperando al agente humano: Esta opción solo se puede usar para derivaciones con el motivo over_capacity. Si el usuario final elige esta opción, actualiza la desviación de la derivación 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.

Enviar y recibir mensajes

Para enviar o recibir mensajes, sigue estos pasos:

Contenido de texto: Para enviar mensajes de texto, usa el extremo POST /chats/:id/message, como se define en la documentación de la API. Para recibir mensajes, escucha el evento de webhook message_received. Ten en cuenta que el consumidor de la API recibirá un evento message_received para todos los mensajes enviados a través de la API, incluidos los mensajes enviados por el usuario final.
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, subiéndolo al servicio de almacenamiento y, luego, enviando la URL de almacenamiento en una carga útil de mensaje a Contact Center AI Platform.
1. Recupera la URL previamente firmada: Recupera una URL de carga previamente firmada de Contact Center AI Platform con POST /v1/chats/:chat_id/photos/upload o POST /v1/chats/:chat_id/videos/upload endpoints. Este extremo devuelve una URL firmada previamente, junto con una colección de campos para reenviar al servicio de almacenamiento cuando se suba el archivo. Las cargas previas firmadas tienen las siguientes restricciones:
  - El tipo de contenido es image/jpeg para las fotos y video/mp4 para los 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 firmada previamente es para una sola foto o video. Para enviar varios archivos adjuntos, debes solicitar una URL firmada previamente para cada uno.
2. Sube el archivo multimedia: Para subir el archivo multimedia, realiza una solicitud POST a la URL firmada previamente que se recuperó en el paso 2a con lo siguiente en el cuerpo de la solicitud:
  - "file": Es el archivo que se subirá.
  - Todos los campos que se muestran en el objeto fields de la solicitud de URL firmada previamente.
3. Cómo agregar 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 videos 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 firmada previamente.
  - Si la solicitud se realiza correctamente, se mostrarán dos campos. Se recomienda guardar o almacenar en caché una asignación de media_id a la URL en el consumidor de la API, ya que solo se hará referencia a todos los medios en los mensajes de chat por medio de media_id.
    - url: Es la URL de solo lectura de S3 o Cloud Storage en la que se encuentra el archivo.
    - media_id: Es el ID del archivo multimedia en Contact Center AI Platform. Es el ID con el que se hará referencia al contenido multimedia en las cargas útiles del 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">,
    "content": {
      "media_id": < media_id returned as described in 2.c >
    }
}
```

Se esperan 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 ignorando las claves no reconocidas para mantener la funcionalidad continua.

Guía de la API de la plataforma de chat Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.