Usa esta guía para crear 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.
Recibir y verificar eventos de webhook de Contact Center AI Platform
Enviar mensajes de texto al chat
Manejar ramas opcionales, como la importación de transcripciones previas al chat, el enrutamiento de agentes virtuales con selección de filas, las derivaciones de derivaciones y los archivos adjuntos de medios
Finaliza el chat cuando se complete la conversación.
Esta guía es para los desarrolladores que crean un servicio de backend que conecta una experiencia de chat propiedad del cliente a CCAI Platform. Se supone que puedes crear credenciales de API en la plataforma de CCAI, 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 chat de la API de Apps. Usa la referencia de la API para obtener el esquema exhaustivo de solicitud y respuesta, y usa esta guía para conocer el flujo de implementación integral recomendado.
Terminología
Las siguientes definiciones se aplican a este documento:
Cliente: Es el cliente de la plataforma de CCAI que implementa la integración del chat en su propio software.
Consumidor: Es la aplicación del servidor propiedad del cliente que realiza solicitudes a la API de Apps y recibe eventos de webhook de la 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 del consumidor que recibe eventos de chat de la Plataforma de CCAI.
Antes de comenzar
Antes de comenzar, asegúrate de tener lo siguiente:
Credenciales de la API de Apps
Crea credenciales de API en la plataforma de la CCAI en Configuración > Configuración del desarrollador > Credenciales de API.
Almacena el secreto de credenciales de forma segura. No la expongas en el código del navegador ni del cliente móvil.
Detalles de la URL del arrendatario
Identifica tu subdominio y 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 la plataforma de CCAI.
Configura el extremo en la configuración del desarrollador de CCAI Platform.
Genera y almacena los secretos principal y secundario del webhook.
Configuración de la cola o el menú
Identifica la fila o el menú en el que ingresan los chats nuevos.
Si usas un agente virtual de selección de filas, configúralo y asígnale la fila 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 del límite de frecuencia
- CCAI Platform limita la cantidad de solicitudes a la API de Apps. Incorpora reintentos y una estrategia de espera a tu integración, y evita enviar ráfagas de solicitudes para un solo arrendatario.
Seguridad de la autenticación y los webhooks
Tu integración usa dos rutas de autenticación:
Autenticación de la API de Apps para solicitudes de tu servidor a CCAI Platform
Verificación de la firma del webhook para las solicitudes de CCAI Platform a tu servidor.
Autentica solicitudes a la API de Apps
Las solicitudes usan la autenticación HTTP básica. Crea un token de API en la plataforma de la CCAI en Configuración > Configuración para desarrolladores > Credenciales de API y pásalo en el campo contraseña (recomendado). Si tu organización usa 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 ver la configuración completa de la autenticación. En el siguiente ejemplo, se muestra cómo autenticar una solicitud a la API de Apps con 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 secreto 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
La plataforma de CCAI envía eventos de chat a tu extremo de webhook. Cada solicitud de webhook incluye lo siguiente:
X-SignatureX-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 el controlador de webhook, haz lo siguiente:
Lee
X-SignatureyX-Signature-Timestamp.Rechaza la solicitud si falta alguno de los encabezados.
Rechaza las marcas de tiempo obsoletas para reducir el riesgo de repetición.
Lee el cuerpo de la solicitud sin procesar antes de analizar el JSON.
Calcula la firma esperada con cada secreto de webhook activo.
Compara la firma recibida y la firma esperada con una comparación de tiempo constante.
Acepta la solicitud si coincide con algún secreto activo.
En el siguiente ejemplo de implementación en 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 rápidamente y procesa el evento de forma idempotente. Las respuestas de la API y la entrega de webhooks pueden llegar en diferentes órdenes, por lo que debes crear tu integración para que pueda recibir el mismo cambio de estado más de una vez sin crear registros duplicados.
El flujo de integración
El siguiente flujo crea un usuario final, inicia un chat, recibe eventos de la plataforma de CCAI, intercambia mensajes y finaliza el chat.
Crea o actualiza el usuario final
Objetivo: Asegúrate de que CCAI Platform tenga un registro del 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 un cuerpo de solicitud para crear o actualizar un usuario final:
{
"identifier": "customer-user-12345",
"email": "customer.user@example.com",
"name": "Customer User",
"phone": "+15551234567"
}
Qué almacenar
Almacena en tu sistema el ID de usuario final de CCAI Platform que se incluye en la respuesta. Usa ese ID cuando crees un chat.
Qué esperar
Si el usuario final no existe, la plataforma de la CCAI 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 nuevo chat:
POST /apps/api/v1/chats
Ejemplo de solicitud
En el siguiente ejemplo, se muestra un cuerpo de 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é fila recibe el chat.
Qué esperar
La API de Apps devuelve el recurso de chat.
La plataforma de CCAI envía un evento de webhook
chat_createdal extremo de webhook que configuraste.La respuesta de la API y el evento de webhook pueden llegar en cualquier orden. Ambos se tratan como actualizaciones del mismo registro de chat, con el ID de chat como clave.
Procesa eventos de webhook de chat
Objetivo: Mantener sincronizada la aplicación del consumidor con el estado del chat de CCAI Platform.
Tu extremo de webhook controla los eventos de ciclo de vida y mensajes del chat de CCAI Platform. Como mínimo, almacena lo siguiente:
ID del chat.
Es el tipo de evento.
Es la marca de tiempo del evento.
Remitente, tipo y contenido del mensaje cuando el evento contiene un mensaje.
Cualquier dato de derivación o desvío cuando el evento describe el comportamiento de enrutamiento.
Comportamiento recomendado
Verifica cada firma de webhook antes de procesar el evento.
Almacena 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 posteriores de forma asíncrona cuando sea posible.
Qué esperar
Tu aplicación actualiza su estado de chat cuando la plataforma de CCAI 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 del usuario final desde la aplicación del consumidor al chat de la plataforma de CCAI
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
La plataforma de CCAI 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 del agente o del agente virtual en la experiencia de chat propiedad del cliente
Cuando tu extremo de webhook recibe un evento de mensaje, sucede lo siguiente:
Verifica la firma del webhook.
Verifica si el evento es nuevo.
Identifica el chat por su ID.
Identifica el remitente y el tipo de mensaje.
Renderiza el mensaje en la IU de chat propiedad del cliente.
Persiste el evento para que las actualizaciones o los reintentos no pierdan el historial de conversación.
Qué esperar
La IU de chat propiedad del cliente muestra los mensajes enviados por los agentes, los agentes virtuales y el usuario final en el orden correcto. Si los eventos llegan desordenados, usa marcas de tiempo de eventos y tu propia capa de persistencia para conciliar el orden de visualización.
Cómo derivar de un agente virtual a un agente humano
Objetivo: Trasladar el chat del manejo del agente virtual a una fila humana cuando el usuario final necesita ayuda de un agente.
Si tu integración usa un agente virtual de selección de filas, configúralo para que dirija los chats a la fila de destino. Si tu servidor inicia la derivación directamente, usa el extremo de derivació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 dirige a la atención del agente.
Si la fila no está disponible debido a condiciones fuera de horario o de capacidad excedida, la plataforma de CCAI puede devolver o enviar opciones de desvío a través del flujo de chat.
Tu integración renderiza las opciones de desvío disponibles para el usuario final.
Registra una elección de desvío de derivación
Objetivo: Indicarle a CCAI Platform qué opción de desviación seleccionó el usuario final.
Cuando la plataforma de CCAI ofrece opciones para evitar derivaciones, 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 las desviaciones 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 de deflection_channel admitido a este endpoint.
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
La plataforma de CCAI actualiza el registro de derivación y hace la transición del chat según la opción seleccionada.
Cómo finalizar el chat
Objetivo: Cierra el chat cuando finalice 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
La plataforma de CCAI 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.
Flujos avanzados
Las siguientes ramas son opcionales. Implementa solo los flujos que se apliquen 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 la plataforma de CCAI, 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.
Cómo enrutar 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.
Crea un agente virtual para la selección de colas.
Asigna el agente virtual a la cola de entrada.
Incluye contexto cuando crees el chat.
Configura el agente virtual para que inspeccione el contexto y derive el chat a la cola correcta.
Controlar las opciones de desvío si la cola de destino no está disponible
Enviar archivos adjuntos de fotos o videos
Usa este flujo cuando el usuario final envíe contenido multimedia desde la IU de chat propiedad del cliente.
El flujo de medios tiene cuatro etapas.
Etapa 1: Solicita una URL de carga previa firmada
Usa los siguientes extremos para solicitar una URL firmada previamente para 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 devolvió
Incluye el archivo y los campos que CCAI Platform devuelve en la respuesta de carga previa firmada.
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 a los medios por su ID.
Etapa 4: Envía el contenido multimedia como 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 como adjunto:
{
"from_user_id": 456,
"message": {
"type": "photo",
"content": {
"media_id": 789
}
}
}
Usa el tipo de mensaje video y el video media_id para los mensajes de video.
Envía datos personalizados durante un chat
Usa el siguiente endpoint cuando tu integración necesite adjuntar 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 las claves reservadas.
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 endpoint 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 actualizada del usuario final.
Recopila datos de CSAT o de calificaciones
Usa los siguientes extremos de CSAT y clasificación del chat cuando tu integración sea propietaria de la experiencia de clasificació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 y las cargas útiles de clasificación exactas, consulta la referencia de la API de Apps.