Guía de integración de la API de la plataforma de chat

Usa esta guía para compilar una integración de chat del servidor con la API de Apps. Al final, tu integración podrá hacer lo siguiente:

• Autentícate en la API de Apps.

• Crea o actualiza un usuario final.

• Inicia un chat para ese usuario final.

• Recibe y verifica eventos de webhook de Contact Center AI Platform.

• Enviar mensajes de texto en el chat

• Controla las ramas opcionales, como la importación de transcripciones previas al chat, el enrutamiento de agentes virtuales de selección de colas, los desvíos de derivaciones y los archivos multimedia adjuntos.

• Finaliza el chat cuando termine la conversación.

Esta guía está dirigida a los desarrolladores que crean un servicio de backend que conecta una experiencia de chat propiedad del cliente con CCAI Platform. Se supone que puedes crear credenciales de API en CCAI Platform, alojar un extremo de webhook HTTPS, almacenar secretos de forma segura y realizar solicitudes HTTP desde tu servidor.

Esta guía complementa los extremos de la API de Apps para Chat. Usa la referencia de la API para el esquema exhaustivo de solicitud y respuesta, y usa esta guía para el flujo de implementación recomendado de extremo a extremo.

Terminología

Las siguientes definiciones se aplican a este documento:

• Cliente: Es el cliente de CCAI Platform que implementa la integración del chat en su propio software.

• Consumidor: Es la aplicación del servidor que pertenece al cliente y que realiza solicitudes a la API de Apps y recibe eventos de webhook de CCAI Platform.

• Usuario final: Es la persona que usa el software del cliente para iniciar o continuar un chat con un agente o un agente virtual.

• Chat: Es el recurso de conversación de CCAI Platform que crea la API de Apps.

• Extremo del webhook: Es el extremo HTTPS en la aplicación de consumidor que recibe eventos de chat de CCAI Platform.

Antes de comenzar

Antes de comenzar, asegúrate de tener lo siguiente:

• Credenciales de la API de Apps

  • Crea credenciales de API en CCAI Platform desde Configuración > Configuración para desarrolladores > Credenciales de API.

  • Almacena el secreto de la credencial de forma segura. No la expongas en el código del navegador ni del cliente móvil.

• Detalles de la URL del usuario

  • Identifica el subdominio y el dominio de CCAI Platform.

  • La URL base de la API de Apps es la siguiente: https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1

• Extremo del webhook

  • Aloja un extremo HTTPS público que pueda recibir solicitudes POST de CCAI Platform.

  • Configura el extremo en la configuración para desarrolladores de CCAI Platform.

  • Genera y almacena los secretos principal y secundario del webhook.

• Configuración de cola o menú

  • Identifica la cola o el menú al que ingresan los chats nuevos.

  • Si usas un agente virtual de selección de colas, configúralo y asígnalo a la cola de entrada antes de crear chats a través de la API.

• Identidad del usuario final

  • Decide qué identificador estable usará tu sistema para cada usuario final.

  • Almacena el ID de usuario final de CCAI Platform que devuelve la API de Apps.

• Control de límites de frecuencia

  • CCAI Platform limita la frecuencia de la API de Apps. Compila reintentos y retiradas en tu integración, y evita enviar ráfagas de solicitudes para un solo inquilino.

Autenticación y seguridad de webhooks

Tu integración usa dos rutas de autenticación:

• Autenticación de la API de Apps para las solicitudes de tu servidor a CCAI Platform.

• Verificación de firma de webhook para solicitudes de CCAI Platform a tu servidor.

Autentica solicitudes a la API de Apps

Las solicitudes usan la autenticación básica de HTTP. Crea un token de API en CCAI Platform en Configuración > Configuración para desarrolladores > Credenciales de la API y pásalo en el campo contraseña (recomendado). Si tu usuario utiliza la ruta de autenticación heredada, puedes pasar la clave de tu empresa como nombre de usuario y el secreto de tu empresa como contraseña. Consulta la referencia de la API de Apps para obtener la configuración de autenticación completa. En el siguiente ejemplo, se muestra cómo autenticar una solicitud a la API de Apps con la autenticación básica:

curl -X GET \
  https://YOUR_SUBDOMAIN.YOUR_DOMAIN/apps/api/v1/chats/{chat_id} \
  -u "YOUR_SUBDOMAIN:YOUR_API_TOKEN" \
  -H "Accept: application/json"

Almacena las credenciales en un almacén de secretos del servidor, rótalas según tu política de seguridad y nunca las envíes en apps para navegadores o dispositivos móviles.

Verifica las solicitudes de webhook

CCAI Platform envía eventos de chat a tu extremo de webhook. Cada solicitud de webhook incluye lo siguiente:

• X-Signature

• X-Signature-Timestamp

El encabezado X-Signature puede contener una firma principal, una secundaria o ambas:

primary=<primary_signature> secondary=<secondary_signature>

Cada firma es un resumen HMAC-SHA256 codificado en Base64. El valor firmado es el encabezado de marca de tiempo concatenado con el cuerpo de la solicitud JSON sin procesar:

X-Signature-Timestamp + raw_request_body

En tu controlador de webhook, haz lo siguiente:

1. Lee X-Signature y X-Signature-Timestamp.

2. Rechaza la solicitud si falta alguno de los encabezados.

3. Rechaza las marcas de tiempo obsoletas para reducir el riesgo de repetición.

4. Lee el cuerpo de la solicitud sin procesar antes de analizar el JSON.

5. Calcula la firma esperada con cada secreto de webhook activo.

6. Compara la firma recibida y la firma esperada con una comparación de tiempo constante.

7. Acepta la solicitud si coincide algún secreto activo.

En el siguiente ejemplo de implementación de Ruby, se muestra cómo verificar las firmas de webhook de UJET:

require "base64"
require "openssl"
require "active_support/security_utils"

def parse_ujet_signature(header)
  header.to_s.split(/\s+/).each_with_object({}) do |part, result|
    key, value = part.split("=", 2)
    result[key] = value if key && value
  end
end

def expected_signature(secret, timestamp, raw_body)
  Base64.strict_encode64(
    OpenSSL::HMAC.digest(
      OpenSSL::Digest.new("sha256"),
      secret,
      "#{timestamp}#{raw_body}"
    )
  )
end

def secure_match?(received, expected)
  return false if received.nil? || expected.nil?
  return false unless received.bytesize == expected.bytesize

  ActiveSupport::SecurityUtils.secure_compare(received, expected)
end

def verify_ujet_webhook!(request, primary_secret:, secondary_secret:)
  signature_header = request.headers["X-Signature"]
  timestamp = request.headers["X-Signature-Timestamp"]

  return false if signature_header.nil? || timestamp.nil?

  # Optional but recommended: reject stale requests.
  return false if (Time.now.utc - Time.at(timestamp.to_i).utc).abs > 5.minutes

  raw_body = request.body.read
  signatures = parse_ujet_signature(signature_header)

  expected = [
    expected_signature(primary_secret, timestamp, raw_body),
    expected_signature(secondary_secret, timestamp, raw_body)
  ].compact

  received = [
    signatures["primary"],
    signatures["secondary"]
  ].compact

  received.any? do |received_signature|
    expected.any? do |expected_signature_value|
      secure_match?(received_signature, expected_signature_value)
    end
  end
end

Si la verificación se realiza correctamente, devuelve una respuesta de éxito con rapidez y procesa el evento de forma idempotente. La entrega de webhooks y las respuestas de la API pueden llegar en diferentes órdenes, por lo que debes compilar tu integración para que tolere recibir el mismo cambio de estado más de una vez sin crear registros duplicados.

El flujo de integración

En el siguiente flujo, se crea un usuario final, se inicia un chat, se reciben eventos de CCAI Platform, se intercambian mensajes y se finaliza el chat.

Crea o actualiza el usuario final

Objetivo: Asegúrate de que CCAI Platform tenga un registro de usuario final antes de crear el chat.

Extremo

Usa el siguiente extremo para crear o actualizar un usuario final:

POST /apps/api/v1/end_users

Ejemplo de solicitud

En el siguiente ejemplo, se muestra el cuerpo de una solicitud para crear o actualizar un usuario final:

{
  "identifier": "customer-user-12345",
  "email": "[e-mail]",
  "name": "Customer User",
  "phone": "[phone]"
}

Qué almacenar

Almacena el ID de usuario final de CCAI Platform de la respuesta en tu sistema. Usa ese ID cuando crees un chat.

Qué esperar

• Si el usuario final no existe, CCAI Platform crea un registro nuevo.

• Si ya existe un usuario final con el mismo identificador, CCAI Platform actualiza el registro y devuelve la información del usuario final existente.

Crea el chat

Objetivo: Iniciar un nuevo chat de CCAI Platform para el usuario final.

Extremo

Usa el siguiente extremo para iniciar un chat nuevo:

POST /apps/api/v1/chats

Ejemplo de solicitud

En el siguiente ejemplo, se muestra el cuerpo de una solicitud para crear un chat:

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en"
  }
}

Contexto opcional para el enrutamiento de agentes virtuales

Si tu agente virtual de selección de colas necesita contexto de tu aplicación, incluye una carga útil de contexto cuando crees el chat, como se muestra en el siguiente ejemplo:

{
  "chat": {
    "menu_id": 123,
    "end_user_id": 456,
    "lang": "en",
    "context": {
      "value": {
        "customer_tier": "gold",
        "issue_type": "billing"
      }
    }
  }
}

Un agente virtual puede usar valores de ese contexto para decidir qué cola recibe el chat.

Qué esperar

• La API de Apps devuelve el recurso de chat.

• CCAI Platform envía un evento de webhook chat_created a tu extremo de webhook configurado.

• La respuesta de la API y el evento de webhook pueden llegar en cualquier orden. Trata ambos como actualizaciones del mismo registro de chat, con clave por ID de chat.

Procesa eventos de webhook de Chat

Objetivo: Mantener la aplicación para consumidores sincronizada con el estado del chat de CCAI Platform.

Tu extremo de webhook controla el ciclo de vida del chat y los eventos de mensajes de CCAI Platform. Como mínimo, almacena lo siguiente:

• ID del chat.

• Es el tipo de evento.

• Es la marca de tiempo del evento.

• El remitente, el tipo y el contenido del mensaje cuando el evento contiene un mensaje

• Cualquier dato de derivación o desvío cuando el evento describa el comportamiento de enrutamiento

Comportamiento recomendado

• Verifica cada firma de webhook antes de procesar el evento.

• Almacena los IDs de eventos procesados o una clave de evento determinística para que los reintentos no creen duplicados.

• Devuelve una respuesta 2xx después de aceptar el evento.

• Procesa los efectos secundarios downstream de forma asíncrona cuando sea posible.

Qué esperar

Tu aplicación actualiza su estado de chat cuando CCAI Platform envía eventos, como la creación de chats, los mensajes entrantes, los mensajes de agentes, los cambios de derivación y la finalización de chats.

Enviar un mensaje de texto

Objetivo: Enviar un mensaje de usuario final desde la aplicación para consumidores al chat de CCAI Platform.

Extremo

Usa el siguiente extremo para enviar un mensaje de texto al chat:

POST /apps/api/v1/chats/{chat_id}/message

Ejemplo de solicitud

En el siguiente ejemplo, se muestra el cuerpo de una solicitud para enviar un mensaje de texto:

{
  "from_user_id": 456,
  "message": {
    "type": "text",
    "content": "Hello, I need help with my order."
  }
}

Qué esperar

• CCAI Platform acepta el mensaje.

• El mensaje aparece en la conversación del agente o del agente virtual.

• Tu extremo de webhook recibe un evento de mensaje para el mensaje, incluidos los mensajes que tu propia aplicación envió a través de la API de Apps.

Recibe y muestra mensajes de CCAI Platform

Objetivo: Mostrar mensajes de agentes o agentes virtuales en la experiencia de chat del cliente.

Cuando tu extremo de webhook recibe un evento de mensaje, ocurre lo siguiente:

1. Verifica la firma del webhook.

2. Verifica si el evento es nuevo.

3. Identifica el chat por su ID.

4. Identifica el remitente y el tipo de mensaje.

5. Renderiza el mensaje en la IU de chat que pertenece al cliente.

6. Conservar el evento para que las actualizaciones o los reintentos no pierdan el historial de conversaciones

Qué esperar

La IU de chat que pertenece al cliente muestra los mensajes que envían los agentes, los agentes virtuales y el usuario final en el orden correcto. Si los eventos llegan desordenados, usa las marcas de tiempo de los eventos y tu propia capa de persistencia para conciliar el orden de visualización.

Deriva de un agente virtual a un agente humano

Objetivo: Mover el chat de la administración del agente virtual a una fila humana cuando el usuario final necesite ayuda del agente.

Si tu integración usa un agente virtual de selección de colas, configúralo para que enrute los chats a la cola de destino. Si tu servidor inicia la elevación directamente, usa el extremo de elevación de la API de Apps.

Extremo

Usa el siguiente extremo para derivar un chat de un agente virtual a un agente humano:

POST /apps/api/v1/chats/{chat_id}/escalations

Ejemplo de solicitud

En el siguiente ejemplo, se muestra el cuerpo de una solicitud para derivar un chat:

{
  "reason": "by_end_user_ask",
  "force_escalate": false
}

Qué esperar

• Si la cola de destino está disponible, el chat se mueve hacia la atención del agente.

• Si la cola no puede aceptar el chat y se configuran alternativas de desvío, la plataforma de CCAI mantiene el chat con el agente virtual y envía un evento de webhook escalation_deflected que contiene las alternativas disponibles para el usuario final. Las alternativas nunca llegan en la respuesta de elevación.

• Tu integración renderiza las opciones de desvío disponibles para el usuario final.

Registra una opción de desvío de derivación

Objetivo: Indicarle a CCAI Platform qué opción de desvío seleccionó el usuario final

Cuando CCAI Platform ofrece opciones de desvío de derivación, registra la elección del usuario final con el extremo de actualización de derivación.

Extremo

Usa el siguiente extremo para actualizar un registro de derivación con una opción de desvío:

PATCH /apps/api/v1/chats/{chat_id}/escalations/{escalation_id}

Valores de deflection_channel admitidos:

• email: El usuario final elige la opción de desvío de correo electrónico.

• virtual_agent: El usuario final elige continuar con un agente virtual.

• human_agent: El usuario final elige seguir esperando a un agente humano. Este valor solo se aplica a los desvíos por exceso de capacidad.

Ejemplo de solicitud

En el siguiente ejemplo, se muestra el cuerpo de una solicitud para registrar una opción de desvío:

{
  "deflection_channel": "email"
}

Envía solo un valor deflection_channel admitido a este extremo. external_link no es un valor válido para el extremo de actualización de derivación. Cuando el usuario final sigue un vínculo de desvío externo, el chat finaliza.

Qué esperar

CCAI Platform registra la elección en la derivación. Registrar una elección no enruta el chat: tu integración actúa en función de la selección, por ejemplo, cerrando el chat para un desvío de correo electrónico o enviando un nuevo escalamiento con force_escalate: true para una opción de seguir esperando.

Cómo finalizar la conversación

Objetivo: Cerrar el chat cuando se complete la conversación.

Extremo

Usa el siguiente extremo para finalizar un chat activo:

PATCH /apps/api/v1/chats/{chat_id}/end

Ejemplo de solicitud

En el siguiente ejemplo, se muestra el cuerpo de una solicitud para finalizar un chat:

{
  "ended_by_user_id": 456
}

Qué esperar

• CCAI Platform finaliza el chat.

• Tu extremo de webhook recibe el evento final de estado del chat.

• Tu aplicación marca el chat como completado y deja de aceptar mensajes nuevos del usuario final para ese chat.

Si el chat finaliza porque el usuario final seleccionó una opción de desvío, no uses este extremo en lugar de registrar esa selección. Primero, registra la elección en la derivación o regístrala y cierra el chat en una sola solicitud con PATCH /apps/api/v1/chats/{chat_id}, proporcionando escalation_id y deflection_channel junto con el estado. Un chat que finaliza sin una elección registrada deja la elección sin registrar en la derivación y ausente de los informes de resultados de desvío.

Flujos avanzados

Las siguientes ramas son opcionales. Implementa solo los flujos que se aplican a tu integración.

Importa una transcripción previa al chat

Usa este flujo cuando el usuario final ya haya tenido una conversación en tu sistema antes de que crearas el chat de CCAI Platform, como una conversación de chatbot.

Agrega la carga útil de la transcripción cuando crees el chat. La transcripción le brinda contexto al agente para que el usuario final no tenga que repetir la información.

La referencia de la API de Apps incluye el esquema exacto de la transcripción.

Enruta chats con un agente virtual de selección de colas

Usa este flujo cuando tu aplicación envíe todos los chats nuevos a una cola de entrada y permita que un agente virtual decida la cola de destino final.

1. Crear un agente virtual para la selección de colas

2. Asigna el agente virtual a la cola de entrada.

3. Incluye contexto cuando crees el chat.

4. Configura el agente virtual para que inspeccione el contexto y derive el chat a la cola correcta.

5. Controla las opciones de desvío si la cola de destino no está disponible.

Cómo enviar fotos o videos como archivos adjuntos

Usa este flujo cuando el usuario final envíe contenido multimedia desde la IU de chat que pertenece al cliente.

El flujo de medios tiene cuatro etapas.

Etapa 1: Solicita una URL de carga firmada previamente

Usa los siguientes extremos para solicitar una URL firmada previamente y subir una foto o un video:

POST /apps/api/v1/chats/{chat_id}/photos/upload
POST /apps/api/v1/chats/{chat_id}/videos/upload

Etapa 2: Sube el archivo a la URL de almacenamiento que se muestra

Incluye el archivo y los campos que devuelve CCAI Platform en la respuesta de carga con firma previa.

Etapa 3: Agrega el archivo subido al chat

Usa los siguientes extremos para agregar una foto o un video subidos al chat:

POST /apps/api/v1/chats/{chat_id}/photos
POST /apps/api/v1/chats/{chat_id}/videos

Almacena el media_id que devuelve CCAI Platform. Las cargas útiles de los mensajes de Chat hacen referencia al contenido multimedia por ID.

Etapa 4: Envía el contenido multimedia como un mensaje

Usa el siguiente extremo para enviar un mensaje multimedia al chat:

POST /apps/api/v1/chats/{chat_id}/message

Ejemplo de solicitud

En el siguiente ejemplo, se muestra el cuerpo de una solicitud para enviar una foto adjunta:

{
  "from_user_id": 456,
  "message": {
    "type": "photo",
    "content": "Photo of the damaged item",
    "media_id": 789
  }
}

El extremo acepta type, content y media_id como valores planos; se descarta un objeto anidado proporcionado en content y se pierde la referencia de medios. Usa el tipo de mensaje video y el video media_id para los mensajes de video. media_id es un elemento del mismo nivel que content.

Envía datos personalizados durante un chat

Usa el siguiente extremo cuando tu integración necesite adjuntar un contexto definido por el cliente a un chat activo:

POST /apps/api/v1/chats/{chat_id}/custom_data

La referencia de la API de Apps define la forma exacta de la carga útil y el comportamiento de la clave reservada.

Actualiza la identidad del usuario final durante un chat

Usa el siguiente extremo cuando la identidad del usuario final cambie o se conozca después de que comience el chat:

POST /apps/api/v1/chats/{chat_id}/end_user

Por ejemplo, usa este extremo cuando un usuario final anónimo accede durante un chat activo y tu integración necesita que CCAI Platform asocie el chat con la identidad del usuario final actualizada.

Recopila datos de CSAT o de calificaciones

Usa los siguientes extremos de CSAT y calificación de chat cuando tu integración sea propietaria de la experiencia de calificación posterior al chat:

GET /apps/api/v1/chats/{chat_id}/csat
GET /apps/api/v1/chats/{chat_id}/rating
PATCH /apps/api/v1/chats/{chat_id}/rating

Para conocer las reglas de elegibilidad exactas y las cargas útiles de las calificaciones, consulta la referencia de la API de Apps.