ARIA en tu portal

Puedes ofrecer las consultas de ARIA dentro de tu propio portal, sin que tus usuarios entren al panel de artificialic. Esta integración requiere habilitación individual y trabajo de tu equipo de desarrollo; no se activa al crear una clave REST común.

Qué necesitas habilitar

Solicita una habilitación dedicada y elige al miembro de tu organización con cuya identidad consultará ARIA. El asistente respeta el acceso actual de esa persona; cambiarle permisos o quitarla del equipo puede impedir la conexión. La clave de esta integración no concede por sí misma permisos de la API REST.

El portal funciona en solo lectura: consulta y responde, sin enviar mensajes a clientes ni modificar datos de artificialic. Los turnos y el dictado consumen créditos o cuota de IA de la organización según los servicios utilizados. Revisa los orígenes autorizados y autentica a los usuarios en tu propio portal.

Preparar la conexión

Usa un cliente de Socket.IO, con el namespace /aria y el path /ws. Un WebSocket sin el protocolo Socket.IO no sirve para este contrato. Tu integración debe proporcionar auth.apiKey con la clave dedicada y auth.externalUserId con un identificador estable del usuario de tu portal.

import { io } from "socket.io-client";

// Ejemplo del lado del servidor de tu portal.
const socket = io("https://TU-DOMINIO/aria", {
  path: "/ws",
  extraHeaders: { Origin: "https://TU-PORTAL" },
  auth: {
    apiKey: process.env.ARTIFICIALIC_ARIA_KEY,
    externalUserId: usuarioAutenticado.id,
  },
});

Tu servidor conserva la clave y conecta el chat con el usuario autenticado. No uses una clave REST general en el código del navegador. El identificador externo separa conversaciones e historiales, pero no sustituye el inicio de sesión de tu portal. Si la clave restringe orígenes, envía el origen autorizado también desde tu servidor.

Enviar y mostrar una respuesta

1. Espera ready para habilitar el chat. Informa la organización y el modo de escritura permitido.
2. Envía message con { text, clientMessageId }. Conserva el mismo identificador si reintentas ese mensaje.
3. Guarda el messageId recibido en turn_started.
4. Escucha turn_event. Su sobre contiene { event, data, ts }.

• token: agrega data.content al texto visible.
• tool_run y tool_done: muestran el avance de las consultas.
• pending_choice: presenta las opciones; envía la elección como un mensaje normal.
• done: termina el estado de carga y revisa el resultado o error del turno.

Gestiona también error y los errores de conexión. Distingue una clave inválida de una integración deshabilitada, un origen rechazado o límites de uso; repetir la conexión no corrige esos requisitos.

Reconectar o detener

Tras reconectar, envía resume con { messageId, since? }para recuperar eventos del turno que siga disponible. El evento stopsolicita detener la respuesta. Reanudar un turno y volver a enviar un mensaje son operaciones diferentes: no crees otro envío para recuperar el texto que faltó.

Consultar herramientas de tu sistema

Puedes habilitar conexiones MCP para el asistente del portal desde Complementos → Servidores MCP, con su política de acceso. Si la integración usa un token del usuario de tu sistema, puede enviarlo en auth.userToken para las herramientas correspondientes. Revisa las credenciales y permisos de esa conexión antes de publicarla a tus usuarios.

El evento opcional host_tools informa cuántas herramientas quedaron disponibles y cuáles se omitieron. No lo uses como condición para abrir el chat: el evento que confirma la conexión es ready.

Agregar dictado por voz

Desde tu servidor, envía POST /api/aria-portal/transcribe con Authorization: Bearer CLAVE_DEDICADA y un formulario multipart/form-data cuyo archivo se llame audio. La respuesta correcta contiene { "text": "contenido transcrito" }. Después envía ese texto por el socket como un mensaje; transcribir no inicia el turno.

Si hay una restricción de origen, reenvía Origin con el dominio autorizado. Puedes identificar al usuario con x-aria-external-user-id para aplicar los límites individuales. Ante un límite de uso, respeta Retry-After; ante un archivo rechazado, revisa su formato y tamaño.

Para operar con recursos de artificialic desde tu sistema, consulta la API REST. Para usar un cliente externo de IA, consulta Servidor MCP.