Saltar al contenido

Chat integrado

El chat integrado pone AptiveAI Agents en un panel dentro de tu aplicación. La persona elige uno de sus agentes, inicia una tarea, la sigue, responde sus preguntas y aprueba sus pasos, y encuentra sus tareas anteriores, agrupadas por agente, todo sin salir de tu aplicación. Una tarea iniciada en el panel es una tarea normal: también aparece en AptiveAI Agents, a nombre de la misma persona.

Tu aplicación hace tres cosas:

  1. Inicia la sesión de la persona. Tu servidor responde por la persona que tiene la sesión iniciada en tu aplicación con un token firmado de corta duración. La persona nunca ve una pantalla de inicio de sesión de AptiveAI.
  2. Le dice al agente qué hay en pantalla (opcional): la página, el registro que la persona tiene abierto, para que “¿qué estoy viendo?” tenga respuesta.
  3. Ofrece acciones de pantalla (opcional), como abrir un registro, que el agente puede pedirle a tu página mientras responde.

El panel es una página de AptiveAI Agents mostrada en un <iframe> de tu página. No tiene vista en vivo de la computadora del agente: un paso que la necesita ofrece Abrir en AptiveAI, que abre el producto completo en una pestaña nueva.

Agrega el script de AptiveAI a tu página y monta el panel en un elemento tuyo:

<div id="assistant" style="height: 100%"></div>
<script src="https://console.aptiveai.io/embed/v1.js"></script>
<script>
const panel = AptiveAI.mount('#assistant', {
enterpriseId: 'YOUR-ENTERPRISE-ID',
// Your own server signs a token for the person signed in to your application.
getToken: async () => {
const res = await fetch('/aptiveai/token', { method: 'POST', credentials: 'same-origin' });
if (!res.ok) throw new Error('Could not get an AptiveAI token');
return res.text();
},
context: {
page: { title: 'Customers', url: location.href },
},
actions: [
{
name: 'open_customer',
description: "Open a customer's record on the person's screen.",
parameters: {
type: 'object',
properties: { customerId: { type: 'string' } },
required: ['customerId'],
},
run: async ({ customerId }) => {
await router.navigate(`/customers/${encodeURIComponent(customerId)}`);
return 'Opened';
},
},
],
onEvent: (event) => console.log('AptiveAI', event.type, event),
});
</script>

AptiveAI.mount(el, options) crea el frame del panel dentro de el (un elemento, o un selector que lo indique) y devuelve un objeto de control. Ajustes → Chat integrado muestra la etiqueta del script de tu cuenta, lista para copiar.

OpciónQué es
enterpriseIdEl id de tu empresa, de Ajustes → Chat integrado
getTokenUna función que devuelve un token (un string), o una promesa de uno, obtenido de tu propio servidor (El inicio de sesión, paso a paso). Se llama cuando el panel está listo y otra vez cada vez que la sesión vence
contextOpcional. Lo que la persona tiene abierto (Contexto de la página)
actionsOpcional. Acciones de pantalla que el agente puede pedirle a tu página: cada una { name, description, label, parameters, run(args) }. label y parameters (un JSON schema) son opcionales; run devuelve un resultado o lanza un error (Acciones de pantalla)
onEventOpcional. Recibe { type, … } para ready, signed-in, unavailable, session-expired, task y error (Solución de problemas)
originOpcional. La dirección de AptiveAI Agents, como https://console.aptiveai.io. Por defecto se toma de la dirección del propio script, así que solo la necesitas si cargas el script de otra forma
localeOpcional. 'en' o 'es': abre el panel en inglés o en español, y se mantiene en ese idioma mientras la persona se mueve por él. Cualquier otro valor hace que mount lance un error. Sin esta opción, el panel usa el idioma elegido por última vez dentro de él; si no, el del navegador; si no, inglés. Se lee al abrir el panel; para cambiarlo, llama a unmount() y vuelve a montarlo
themeOpcional. 'light' o 'dark': el modo de tu página, para que el panel coincida con él (Tema). Cualquier otro valor hace que mount lance un error. Sin esta opción, el panel sigue la configuración del sistema de quien lo visita
taskIdOpcional. El id de una tarea (un UUID): el panel se abre en esa tarea en lugar de en una nueva. Cualquier valor que no sea un UUID hace que mount lance un error. Una tarea que no existe, o que no es de la persona, aparece como no disponible
agentIdOpcional. El único agente con el que habla el panel (su id, un UUID); la persona no puede elegir — consulta Qué agente responde. Si también pasas taskId, se abre la tarea y este es el agente con el que empieza Nueva tarea. Cualquier valor que no sea un UUID hace que mount lance un error
defaultAgentIdOpcional. El agente en el que se abre el panel (su id, un UUID); la persona puede cambiarlo — consulta Qué agente responde. No junto con agentId. Cualquier valor que no sea un UUID hace que mount lance un error
Objeto de controlQué hace
setContext(context)Reemplaza el contexto de la página; llámalo cada vez que la persona abra otra página o registro
setActions(actions)Reemplaza la lista de acciones de pantalla; una lista vacía las retira
setTheme(mode)Cambia el panel a 'light' o 'dark' cuando tu página cambia, en vivo y sin recargar: una tarea abierta sigue abierta. Cualquier otro valor lanza un error
unmount()Quita el panel
iframeEl elemento <iframe> del panel, para darle tamaño o estilo

Eventos que recibe onEvent:

typeCamposSignificado
ready—El panel se cargó y pide un token
signed-in—La persona inició sesión
unavailablereasonEl panel no puede iniciar la sesión de la persona y muestra una frase que explica por qué (Solución de problemas). El script no pide más tokens hasta que el panel vuelva a cargarse
session-expired—La sesión del panel terminó; el script ya le está pidiendo un token nuevo a getToken: de inmediato tras una sesión que duró, o tras una pausa creciente (1 segundo, luego 2) cuando una terminó antes de 30 segundos de iniciarse
taskid, statusUna tarea empezó o se abrió, o cambió de estado (los estados)
errorcodeSe rechazó un mensaje; o token_failed: getToken falló tres veces seguidas; o session_not_kept: tres inicios de sesión seguidos terminaron antes de 30 segundos, así que este navegador no conserva la sesión del panel. Tras cualquiera de los dos últimos, el script deja de pedir tokens hasta que el panel vuelva a cargarse (Solución de problemas)

mount lanza un Error de inmediato cuando falta el elemento, falta enterpriseId, getToken no es una función, locale no es 'en' ni 'es', theme no es 'light' ni 'dark', taskId, agentId o defaultAgentId no es un UUID, o se pasan a la vez agentId y defaultAgentId; mount y setActions también lanzan un error ante una acción con un nombre no válido, un nombre repetido, sin descripción o sin run. El tamaño lo decides tú: el panel llena el elemento. Una columna fija de unos 400 píxeles de ancho funciona bien; el panel también funciona en el ancho de un teléfono.

Sin agentId, el panel funciona como AptiveAI Agents: la persona elige uno de los agentes que puede usar, o escribe sin ninguno. Con agentId, el panel se abre en ese agente, Nueva tarea dentro del panel lo conserva y no se ofrece ninguna lista de agentes, así que nadie inicia una tarea sin él. Si la persona no puede usar ese agente — no está compartido con ella, se eliminó o no es un agente normal —, el panel dice que no está disponible y tu página recibe unavailable con el motivo no_agents.

Con defaultAgentId, el panel se abre en ese agente pero no obliga a la persona a usarlo: el agente aparece como una etiqueta sobre el cuadro de mensaje, su ✕ lo quita y muestra los demás agentes de la persona, y Nueva tarea vuelve a abrirse en el agente por defecto. Un agente por defecto que la persona no puede usar se ignora, y el panel muestra sus agentes como lo haría sin la opción.

PasasEl panel se abre enLa persona puede cambiar de agente
agentIdEse agenteNo
defaultAgentIdEse agenteSí, entre los agentes compartidos con ella
NingunoLa lista de sus agentesSí

Cuando tu aplicación tiene un solo asistente, pasa el id de su agente como agentId: así todos hablan con el mismo agente y nadie tiene que elegir. Cuando tiene un asistente habitual y otros para trabajos concretos, pasa el habitual como defaultAgentId. Para usar otro agente, llama a unmount() y vuelve a montarlo con su id.

El panel te avisa de cada tarea con un evento task, { type: 'task', id, status }, cuando una tarea empieza, cuando se abre una tarea existente y cada vez que cambia su estado. Guarda el último id — en tu propia sesión o almacenamiento, por persona — y pásalo como taskId en el siguiente mount: el panel se abre en esa tarea en lugar de en una nueva. Desde ahí la persona puede iniciar una tarea nueva igualmente.

statusSignifica
runningEl agente está trabajando
awaiting_inputEl agente espera a la persona: una pregunta o una aprobación
idleAbierta para otro mensaje
completed, partial, failed, skipped, expired, stoppedLa tarea terminó

El script pone su API en window.AptiveAI. Si tu página ya usa ese nombre, o prefieres otro, agrega data-global a la etiqueta del script:

<script src="https://console.aptiveai.io/embed/v1.js" data-global="NorthwindAssistant"></script>
<script>
const panel = NorthwindAssistant.mount('#assistant', { /* the same options */ });
</script>

El nombre debe ser un identificador simple de JavaScript (letras, dígitos, _ y $, sin empezar por un dígito) que tu página no use ya. Si no lo es, el script usa window.AptiveAI en su lugar y la consola del navegador muestra una advertencia que explica por qué. El script nunca sobrescribe una variable global que no sea suya: si AptiveAI también está ocupada, no instala nada y registra un error con los nombres que no pudo usar. Si el script se carga dos veces, se conserva la primera copia.

El panel es un <iframe> que AptiveAI sirve desde su propio origen, https://console.aptiveai.io. En el navegador, tu página y el panel son dos sitios distintos, así que ninguno puede meterse en el otro: se comunican solo con window.postMessage, en la versión 1 de un pequeño protocolo donde cada mensaje es un objeto { type, v: 1, … }. El script — AptiveAI.mount — lo habla por ti; esta sección cuenta lo que hace en tu nombre. El protocolo completo está en Avanzado: el protocolo de mensajes.

  1. Tu página crea el frame (lo hace el script, en mount). AptiveAI deja que el navegador lo muestre solo en tus orígenes permitidos.
  2. El frame se carga y envía aptiveai:ready.
  3. Tu página le pide un token a TU servidor (getToken). Tu servidor firma uno para la persona que tiene la sesión iniciada en tu aplicación, válido como máximo 60 segundos y de un solo uso.
  4. Tu página envía aptiveai:session con ese token al frame.
  5. AptiveAI verifica el token y abre una sesión para esa persona, solo dentro del frame.
  6. El frame envía aptiveai:signed-in — o aptiveai:unavailable con un motivo, cuando no puede iniciar la sesión de la persona.
  7. A partir de ahí, tu página envía aptiveai:context, aptiveai:actions y aptiveai:theme cada vez que cambian. El frame envía aptiveai:task cuando las tareas empiezan y cambian, aptiveai:action cuando el agente pide una de tus acciones de pantalla — a la que tu página responde con aptiveai:action-result, con el mismo id —, aptiveai:session-expired cuando la sesión termina (vuelta al paso 3) y aptiveai:error cuando rechaza uno de tus mensajes.
Tu página → el panelEl panel → tu página
aptiveai:session — un token nuevoaptiveai:ready — escuchando; envía un token
aptiveai:context — lo que la persona tiene abiertoaptiveai:signed-in — la persona inició sesión
aptiveai:actions — las acciones de pantalla que ofrecesaptiveai:task — una tarea empezó, se abrió o cambió de estado
aptiveai:theme — el modo claro u oscuro de tu páginaaptiveai:action — el agente pide una acción de pantalla
aptiveai:action-result — tu respuesta a aptiveai:actionaptiveai:session-expired — envía un token nuevo
aptiveai:unavailable — no puede iniciar la sesión de esta persona, y por qué
aptiveai:error — se rechazó uno de tus mensajes
  • El secreto de firma se queda en tu servidor. Por tu página solo pasa un token firmado, válido 60 segundos y una sola vez.
  • Tu página no puede leer el panel: ni la conversación, ni las tareas, ni su cookie de sesión. Solo recibe los mensajes de la tabla anterior.
  • El panel no puede leer tu página: ni su DOM, ni sus cookies, ni su almacenamiento. El agente sabe solo lo que envías como contexto y lo que responden tus acciones de pantalla.
  • El frame se carga solo en tus orígenes permitidos (Ajustes → Chat integrado); el navegador se niega a mostrarlo en cualquier otro lugar.
  • El panel envía mensajes solo al origen de tu página y lee un mensaje solo cuando viene de la página que lo incrustó, en uno de tus orígenes permitidos.
  • Tu página envía mensajes al frame con su origen exacto como destino — nunca * — y acepta un mensaje solo cuando event.origin es el origen de la consola y event.source es el contentWindow del frame.

El script hace todo esto por ti: crea el frame, responde a cada aptiveai:ready y aptiveai:session-expired con un token de getToken, envía tu contexto, tus acciones y tu tema, ejecuta el run de tus acciones y aplica las comprobaciones de origen. Nunca pone un token en una URL, en el almacenamiento ni en un registro.

Antes de que el panel pueda iniciar la sesión de alguien, actívalo en AptiveAI Agents y agrega a tu servidor un endpoint de tokens: las dos secciones siguientes.

Un propietario de tu empresa configura el chat integrado en AptiveAI Agents, en Ajustes → Chat integrado.

  1. En Acceso, escribe los orígenes de tu aplicación en Orígenes permitidos: uno por línea, como https://host o https://host:puerto, sin ruta. Como máximo 10. Solo las páginas de estos orígenes pueden mostrar el panel; el navegador lo rechaza en cualquier otro lugar.

  2. En Secreto de firma, pulsa Generar un secreto. El secreto se muestra una sola vez: cópialo en la configuración de tu servidor (un almacén de secretos o una variable de entorno), nunca en tu página. Al lado se muestra el Id de la empresa: tu servidor firma con él como emisor, y tu página se lo pasa a AptiveAI.mount.

  3. Activa Chat integrado activado y pulsa Guardar. No se puede activar sin al menos un origen y un secreto.

  4. Si quieres, elige los colores del panel en Tema (Tema).

Generar un secreto nuevo reemplaza el secreto al instante: el anterior deja de funcionar de inmediato, así que actualiza tu servidor al mismo tiempo. Desactivar el chat integrado cierra todas las sesiones del panel: la siguiente solicitud de un panel abierto se rechaza, el panel le pide un token a tu página y la respuesta es unavailable con disabled. Un panel que se abre mientras está desactivado se carga igual en tus orígenes permitidos, pero no inicia la sesión de nadie y dice que el asistente está desactivado.

Cada persona que usa el panel necesita una cuenta de AptiveAI en tu empresa. La crea un propietario por invitación — consulta Usuarios y roles — o tu servidor con la API de Aprovisionamiento (PUT /members/{email}), que no le envía ningún correo a la persona ni le pone contraseña. El token responde por una persona que ya existe; nunca la crea. Quien no tiene cuenta ve El asistente aún no está configurado para usted. Pida a su administrador que lo invite.

En el panel una persona ve los agentes que ya puede usar en AptiveAI Agents, según las reglas de uso compartido de siempre, salvo que tu página indique uno con agentId (Qué agente responde). Los agentes independientes no se ofrecen. Quien no tiene ningún agente que usar ve Aún no tiene agentes con los que trabajar. Pida a su administrador que comparta uno con usted.

Una persona sin puesto cuenta como si no tuviera ningún agente que usar (no_agents), salvo en una cuenta que paga solo con su billetera — una donde nadie tiene puesto (Una cuenta que paga solo con su billetera). Ahí, las personas sin puesto usan el panel, y cada una de sus tareas se paga con la billetera a la misma tarifa que la API de Agentes. Una tarea se rechaza antes de empezar cuando la billetera tiene menos de $0.05, y el panel le dice a la persona que le pida a su administrador que agregue fondos.

  1. Tu página monta el panel. El frame del panel se carga desde AptiveAI Agents, que solo permite mostrarlo en tus orígenes permitidos.

  2. El panel avisa que está listo y el script llama a tu getToken.

  3. getToken le pide un token a tu propio servidor. Tu servidor comprueba que la persona tiene la sesión iniciada en tu aplicación, firma un token para el correo de esa persona con el secreto de firma y lo devuelve.

  4. El script le entrega el token al panel, que lo cambia en AptiveAI Agents por una sesión propia. Si getToken lanza un error, no devuelve un token o el panel no logra comunicarse con AptiveAI Agents, el script vuelve a intentarlo al cabo de un momento; tras tres fallos seguidos se detiene y onEvent recibe { type: 'error', code: 'token_failed' }.

  5. El panel se abre con la sesión iniciada. Cuando esa sesión termina, el panel vuelve a pedirlo y el script llama a getToken para obtener un token nuevo.

Un JSON Web Token firmado con HS256, con el secreto de firma como clave. El secreto se usa como texto plano, sus bytes UTF-8; no se decodifica de base64.

ClaimValor
issEl id de tu empresa
audaptiveai-embed
subEl correo de la persona. Se compara, sin distinguir mayúsculas, con una cuenta de tu empresa
iatCuándo se firmó, en segundos
expCuándo vence: como máximo 60 segundos después de iat
jtiUn id único. Un token se usa una sola vez: el mismo jti se rechaza mientras el token siga vigente

Se toleran hasta 30 segundos de diferencia entre el reloj de tu servidor y el de AptiveAI. Un token tiene como máximo 4.096 caracteres. Firma un token nuevo cada vez que el panel lo pida; nunca lo guardes para reutilizarlo.

Cada ejemplo de abajo es un endpoint completo y mínimo. Toma el correo de la sesión iniciada en tu propia aplicación, responde 401 cuando no la hay y devuelve el token como texto plano, que es lo que lee getToken en el inicio rápido. Cada uno lee el id de tu empresa y el secreto de las variables de entorno APTIVEAI_ENTERPRISE_ID y APTIVEAI_EMBED_SECRET.

// npm install express jose
import express from 'express';
import { SignJWT } from 'jose';
import { randomUUID } from 'node:crypto';
const ENTERPRISE_ID = process.env.APTIVEAI_ENTERPRISE_ID;
// La clave son los bytes UTF-8 del secreto: no lo decodifiques de base64.
const SECRET = new TextEncoder().encode(process.env.APTIVEAI_EMBED_SECRET);
export async function signEmbedToken(email, audience = 'aptiveai-embed') {
const now = Math.floor(Date.now() / 1000);
return new SignJWT({})
.setProtectedHeader({ alg: 'HS256', typ: 'JWT' })
.setIssuer(ENTERPRISE_ID)
.setAudience(audience)
.setSubject(email)
.setIssuedAt(now)
.setExpirationTime(now + 60)
.setJti(randomUUID())
.sign(SECRET);
}
const app = express();
// app.use(yourSession); — El inicio de sesión de tu propia aplicación, que debe identificar a la persona.
app.post('/aptiveai/token', async (req, res) => {
// La persona con sesión iniciada en TU aplicación; nunca un correo de la solicitud.
const email = req.user?.email;
if (!email) return res.sendStatus(401);
res.set('Cache-Control', 'no-store').type('text/plain').send(await signEmbedToken(email));
});
app.listen(3000);

También sirve cualquier otra biblioteca de JWT, en cualquier lenguaje, siempre que produzca los claims de arriba con HS256.

El token abre una sesión de 8 horas que existe solo dentro del panel de tu aplicación. No es la sesión normal de la persona en AptiveAI Agents: no inicia su sesión en console.aptiveai.io, solo llega a las páginas del propio panel y no puede cambiar una contraseña, la verificación en dos pasos ni otras sesiones. Abrir en AptiveAI abre el producto completo en una pestaña nueva, donde la persona inicia sesión de la forma habitual.

Cuando una persona cierra sesión en tu aplicación, o la desactivas, cierra también su sesión del panel; si no, sigue viva el resto de sus 8 horas. Tu servidor llama a:

POST https://console.aptiveai.io/api/embed/session/revoke
Content-Type: application/json
{ "token": "<a revoke token>" }

Es una llamada de servidor a servidor: sin cookie y sin navegador. El token de revocación se firma igual que el token de inicio de sesión — HS256 con el secreto de firma, iss el id de tu empresa, sub el correo de la persona, como máximo 60 segundos de vigencia, un jti de un solo uso — con una diferencia: aud es aptiveai-embed-revoke. Los dos no son intercambiables: aquí se rechaza un token de inicio de sesión, y un token de revocación nunca inicia la sesión de nadie.

RespuestaSignificado
200 { "ok": true, "ended": <n> }Todas las sesiones del panel de esa persona abiertas a través de tu empresa terminaron; n es cuántas. Es 0 cuando no había ninguna, y también cuando el correo no tiene cuenta contigo, así que la respuesta nunca revela quién tiene una. Las sesiones propias de la persona en AptiveAI Agents no se tocan
401 { "ok": false, "reason": "bad_token" }El token no se verificó: secreto o audiencia equivocados, vencido, de más de 60 segundos o ya usado
401 { "ok": false, "reason": "disabled" }El chat integrado está desactivado para tu empresa, así que todas las sesiones ya terminaron
429Más de 60 llamadas por minuto desde tu servidor; espera los segundos de Retry-After

Cada ejemplo reutiliza la función de firma del endpoint de tokens, con la audiencia de revocación, y lee la dirección de AptiveAI Agents de APTIVEAI_CONSOLE_URL, que por defecto es https://console.aptiveai.io.

// Usa signEmbedToken del endpoint de tokens de arriba.
const CONSOLE_URL = process.env.APTIVEAI_CONSOLE_URL ?? 'https://console.aptiveai.io';
export async function endEmbedSessions(email) {
const token = await signEmbedToken(email, 'aptiveai-embed-revoke');
const res = await fetch(`${CONSOLE_URL}/api/embed/session/revoke`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ token }),
});
return res.json(); // { ok: true, ended } o { ok: false, reason }
}

Llámalo:

  • cuando la persona cierra sesión en tu aplicación;
  • cuando desactivas o quitas a la persona en tu aplicación.

Un panel que sigue abierto cuando termina su sesión se da cuenta en su siguiente solicitud y le pide un token nuevo a tu página con getToken. Después del cierre de sesión o la desactivación, tu endpoint de tokens debe rechazar a esa persona, para que el panel siga sin sesión. En una computadora compartida, quita además el panel de la página al cerrar sesión (unmount()) y monta uno nuevo para la siguiente persona, para que no quede en pantalla nada del panel de la persona anterior.

El contexto le dice al agente qué tiene abierto la persona en tu aplicación, para que una pregunta como “¿qué cambió en este pedido?” no necesite explicación. Pásalo a AptiveAI.mount y actualízalo con setContext cada vez que la persona se mueva:

panel.setContext({
page: { title: 'Order 1042', url: location.href },
record: { type: 'order', id: '1042', label: 'Order 1042 — Jane Sample' },
note: 'Delivery was rescheduled this morning.',
});
CampoQué es
page{ title, url }: la página donde está la persona
record{ type, id, label }: el registro que tiene abierto
noteCualquier texto breve que valga la pena saber

Todos los campos son opcionales; setContext({}) o setContext(null) lo borra.

  • El panel lo muestra. Una línea sobre el cuadro de mensaje muestra la etiqueta del registro (o el título de la página), y la persona puede quitarlo de su próximo mensaje. Viaja con cada mensaje que la persona envía, y el mensaje lo muestra en la transcripción de la tarea.
  • Es una pista, no una instrucción. Al agente se le dice que viene de la aplicación que la persona tiene abierta, no de la persona, y lee los datos reales con sus propios conectores.
  • Que sea breve y sin secretos. El contexto completo tiene como máximo 4 KB de JSON; uno más grande se rechaza y el panel conserva el anterior.

Una acción de pantalla permite que el agente cambie lo que la persona ve en tu aplicación mientras responde: abrir un registro, cambiar de pestaña, ir a una página. Las declaras con actions; el agente ve cada una como una herramienta que puede llamar, descrita por tu description.

panel.setActions([
{
name: 'go_to',
description: 'Go to one of the main pages: "orders", "customers" or "schedule".',
parameters: {
type: 'object',
properties: { page: { type: 'string', enum: ['orders', 'customers', 'schedule'] } },
required: ['page'],
},
run: async ({ page }) => {
if (!['orders', 'customers', 'schedule'].includes(page)) throw new Error('Unknown page');
await router.navigate(`/${page}`);
return `Showing ${page}`;
},
},
]);

Cómo transcurre una llamada:

  1. El agente llama a una de tus acciones, y la transcripción de la tarea muestra el paso.

  2. El script llama a tu run(args) con los argumentos.

  3. Lo que devuelve run — o aquello con que se resuelve — le dice al agente el resultado, que también muestra la transcripción:

    runAl agente se le dice
    devuelve un string, o cualquier otra cosaSe hizo, con el string como mensaje breve
    devuelve falseNo se hizo
    devuelve { ok, message }Se hizo o no, según ok, con message
    lanza un errorNo se hizo, con la primera línea del mensaje de tu error

    Una acción que el agente nombra y que ya no ofreces se responde con Unknown action. Cada pedido del agente se responde una sola vez: run nunca se llama dos veces para el mismo pedido.

Las acciones de pantalla son de mejor esfuerzo:

  • El agente espera como máximo 10 segundos una respuesta y luego sigue como si la acción no se hubiera hecho.
  • Un tramo del trabajo del agente puede llamar como máximo 5 acciones de pantalla.
  • Si el panel está cerrado, o la persona salió de la página, la acción no se hace y la tarea sigue.
  • Una tarea a la que la persona le envía un mensaje desde el producto completo, fuera de tu aplicación, no tiene acciones de pantalla.
LímiteValor
Acciones declaradas a la vez20
nameLetras minúsculas, dígitos y _, empezando por una letra, como máximo 40 caracteres, sin repetir
descriptionObligatoria, como máximo 300 caracteres
parametersUn JSON schema de type: "object" con properties (y required opcional), como máximo 2 KB
El mensaje con que responde una acciónComo máximo 300 caracteres; lo que sobra se corta

Cuando el agente trabaja en el sistema de tu propia aplicación, dale un conector a tu servidor MCP y configúralo como Cada persona inicia sesión: así cada persona inicia sesión en tu servidor como ella misma, y cada acción que el agente hace ahí lleva el token de esa persona, nunca el de un administrador.

Un servidor MCP por Streamable HTTP que inicie la sesión de las personas con OAuth, como describe la especificación de autorización de MCP:

  • Una llamada sin autenticar responde 401, y tu servidor publica sus metadatos de recurso protegido (RFC 9728) con el nombre de su servidor de autorización.
  • El servidor de autorización publica sus metadatos (RFC 8414) y admite PKCE con S256, el parámetro resource (RFC 8707), tokens de actualización y el registro dinámico de clientes (RFC 7591). AptiveAI registra un cliente para cada inicio de sesión, con la URI de redirección https://console.aptiveai.io/api/embed/connect/callback (y https://console.aptiveai.io/api/connectors/oauth/callback para un inicio de sesión hecho dentro de AptiveAI Agents).
  • Emite un token para la persona que inicia sesión, y tu servidor MCP actúa como esa persona con él. Un token que actúa como una cuenta de servicio fija le quita todo el sentido.
  • Dice qué cuenta inició sesión, con un email de un endpoint de userinfo o dentro de un access token JWT (con email_verified: true cuando tu servidor lo ha verificado).

Un administrador conecta tu servidor una vez en AptiveAI Agents (Conectores → Servidor MCP personalizado, autenticación El inicio de sesión del propio servidor), le da la conexión al agente que monta tu panel y elige Cada persona inicia sesión en Quién inicia sesión. Esa primera conexión solo indica el servidor y las herramientas que el agente puede usar; sobre ella no se ejecuta el trabajo de nadie más.

Para una persona solo se usa su propia conexión a esa dirección exacta — el inicio de sesión del panel siempre la hace a esa dirección, envíe lo que envíe el navegador —, y no ofrece ninguna herramienta que no ofrezca la del administrador. Si no la tiene, la herramienta no se ejecuta.

  1. Cuando el agente necesita tu sistema por primera vez, el chat pregunta: host.example aún no está conectado para ti. Conéctalo para que pueda continuar. con Iniciar sesión en host.example y Ahora no.
  2. Iniciar sesión en host.example abre una pestaña nueva (el panel nunca sale de tu página; permite la pestaña si el navegador lo pregunta). Primero dice Vas a conectar host.example para Pat Example (pat@example.test) en Northwind Desk. Si no eres tú, cierra esta pestaña. — con el nombre de para quién es la conexión, y en qué cuenta — y un botón Continuar.
  3. Continuar lleva a la página de inicio de sesión de tu propio servidor.
  4. Después de iniciar sesión, la pestaña dice Ya estás conectado. Cierra esta pestaña y vuelve al chat. y la tarea continúa sola. La próxima vez no se pregunta nada.

La pestaña funciona sin ninguna sesión de AptiveAI: lleva un enlace de un solo uso, válido diez minutos, que solo puede hacer la conexión de esa persona a tu servidor, para la tarea que la pidió. Si tarda más, o el inicio de sesión falla, el chat lo dice y la persona puede volver a elegir Iniciar sesión. Ahora no deja que el agente continúe sin tu sistema.

Comprobar que nadie actúa como otra persona

Sección titulada «Comprobar que nadie actúa como otra persona»

Antes de abrir el panel a personas que no son administradoras, consulta GET /connectors con la API de Aprovisionamiento desde tu servidor: lista cada conexión a una dirección de servidor, de quién es y con quién está compartida, y cómo la usa cada agente. Para el agente que montas, su permiso en la dirección de tu servidor debe ser per_person, y ninguna conexión a esa dirección debe estar compartida.

Sin tema, el panel se ve como AptiveAI Agents. Para que combine con tu aplicación, abre Ajustes → Chat integrado → Tema y elige un Tema base, y luego los colores de Página, Barra lateral y tarjetas y Acento para Claro y Oscuro. Claro y oscuro decide si cada persona ve los colores que eligió para sí (Según cada persona) o un solo aspecto para todos (Siempre este aspecto). Desde una captura propone colores a partir de una imagen de tu aplicación. Los colores que se leen mal se marcan antes de que puedas guardar.

El modo de tu página elige cuál de los dos juegos de colores muestra el panel. Pasa theme: 'light' o 'dark' a mount y llama a setTheme cuando tu página cambie. Una empresa que eligió Siempre este aspecto conserva ese único aspecto, pase lo que pase tu página. Sin theme, el panel sigue la configuración del sistema de quien lo visita. Para seguir tú mismo al dispositivo:

const dark = window.matchMedia('(prefers-color-scheme: dark)');
const panel = AptiveAI.mount('#assistant', { /* … */ theme: dark.matches ? 'dark' : 'light' });
dark.addEventListener('change', (e) => panel.setTheme(e.matches ? 'dark' : 'light'));

La sesión del panel se guarda en una cookie de terceros particionada (SameSite=None; Secure; Partitioned): el navegador la conserva solo para el panel dentro de tu sitio, separada de cualquier otro sitio, y nunca se convierte en la sesión normal de la persona en AptiveAI Agents.

Cuando el panel no puede iniciar la sesión de la persona, le muestra una frase y tu onEvent recibe { type: 'unavailable', reason }. Cuando se rechaza un mensaje de tu página, recibe { type: 'error', code }.

SíntomaCausaSolución
El área del panel queda en blanco y la consola del navegador informa que se negó a mostrar la página en un frameEl origen de tu página no está en Orígenes permitidos, no hay ningún origen en la lista o el id de la empresa es incorrectoAgrega el origen exacto (esquema, host y puerto) en Ajustes → Chat integrado y revisa el id que pasas
unavailable, motivo disabledEl chat integrado está desactivado para la empresa. El panel se carga igual y lo indica, y se rechaza cualquier tokenUn propietario activa Chat integrado activado. No envíes más tokens hasta que tu página vuelva a cargarse
unavailable, motivo bad_tokenSe rechazó el token: secreto equivocado, iss o aud equivocados, vigencia de más de 60 segundos, vencido, reloj muy desfasado o un jti usado dos vecesFirma con el secreto actual y los claims de El token; firma un token nuevo en cada llamada a getToken; revisa el reloj de tu servidor
unavailable, motivo no_accountNinguna cuenta de tu empresa tiene el correo del tokenInvita a la persona — consulta Usuarios y roles — o comprueba que tu servidor firma el correo que la persona tiene en AptiveAI
unavailable, motivo account_unavailableLa empresa está pausada, bloqueada o cancelada, o la cuenta de la persona está suspendidaLa persona consulta a su administrador; un propietario revisa Facturación y puestos
unavailable, motivo no_agentsLa persona no tiene ningún agente que pueda usar o, con agentId, no puede usar ese agente (no está compartido con ella, se eliminó o no es un agente normal). Una persona sin puesto cuenta como si no tuviera ninguno, salvo en una cuenta que paga solo con su billeteraComparte el agente con la persona — consulta Compartir —, revisa el agentId que pasas o dale un puesto a la persona
error, código networkEl panel no pudo comunicarse con AptiveAI Agents al iniciar la sesiónEl script le pide por sí solo un token nuevo a getToken; si se repite, revisa la conexión de la persona
error, código token_failedgetToken falló tres veces seguidas: lanzó un error, no devolvió un token o el panel no logró comunicarse con AptiveAI AgentsRevisa tu endpoint de tokens y la conexión de la persona; el script vuelve a intentarlo cuando el panel se recarga
error, código session_not_keptTres inicios de sesión seguidos terminaron antes de 30 segundos: el navegador no conserva la sesión del panel, normalmente porque bloquea su cookie. Safari no se ha verificadoPrueba el panel en un navegador basado en Chromium o en Firefox y revisa si el navegador bloquea las cookies de terceros. El script deja de pedir tokens hasta que el panel vuelva a cargarse
error, código context_too_largeEl contexto pasa de 4 KBEnvía menos: una etiqueta y un id bastan
error, código too_many_actionsMás de 20 accionesDeclara menos
error, código invalid_actionUna acción incumple una regla de arriba: su nombre, su descripción, su schema parameters, un tamaño, o dos con el mismo nombreCorrige la acción; toda la lista se rechaza hasta que sea válida
error, código invalid_messageUn mensaje no tenía la forma esperadaRevisa lo que le pasas a setContext y setActions
El agente dice que la pantalla no respondiórun no respondió en 10 segundos, el panel estaba cerrado o la persona salió de la páginaHaz que run responda rápido; solo necesita iniciar la navegación

El script es una capa delgada sobre un pequeño protocolo de postMessage entre tu página y el frame del panel. Si no puedes usar el script, puedes hablar el protocolo directamente.

El frame. Créalo con el id de tu empresa. Agrega &lang=es o &lang=en a la dirección para elegir el idioma del panel, &theme=light o &theme=dark para que empiece en el modo de tu página, &agent=<agent id> para indicar el único agente con el que habla, o &default_agent=<agent id> para indicar el agente en el que se abre (Qué agente responde):

<iframe
src="https://console.aptiveai.io/embed?e=YOUR-ENTERPRISE-ID"
title="Assistant"
allow="clipboard-write"
></iframe>

Quién puede incrustarlo. Solo tus orígenes permitidos. Para una empresa desconocida, o sin ningún origen permitido, nadie puede. Una empresa que desactivó el chat integrado sigue permitiendo que sus orígenes permitidos incrusten el panel, para que el panel pueda decir que está desactivado: el frame se carga, envía aptiveai:ready y responde a tu aptiveai:session con aptiveai:unavailable y el motivo disabled. Deja entonces de enviar tokens hasta que tu página vuelva a cargarse; enviar uno en cada aptiveai:ready solo le pide a tu servidor tokens que se van a rechazar.

Reglas de seguridad para tu página:

  • Envía mensajes al frame con su origen exacto, https://console.aptiveai.io, como destino; nunca *.
  • Acepta un mensaje solo cuando event.origin sea https://console.aptiveai.io y event.source sea el contentWindow del frame.
  • Ignora los mensajes cuyo type no empiece por aptiveai:.

El frame acepta aptiveai:context y aptiveai:actions en cuanto ha enviado aptiveai:ready.

Cada mensaje es un objeto con un type y v: 1. Un mensaje con otro v se rechaza con aptiveai:error unsupported_version.

typeCamposSignificado
aptiveai:sessiontokenInicia la sesión de la persona. Envíalo en respuesta a aptiveai:ready y a aptiveai:session-expired, cada vez con un token nuevo
aptiveai:contextopcionales page: { title, url }, record: { type, id, label }, noteLo que la persona tiene abierto. Envíalo cada vez que cambie; sin campos, borra el contexto
aptiveai:actionsactions: [{ name, description, label?, parameters? }]Las acciones de pantalla que ofreces. Enviarlo de nuevo reemplaza la lista; una lista vacía las retira. label (como máximo 80 caracteres) es tu propia redacción del paso en la transcripción
aptiveai:action-resultid, ok, message opcionalTu respuesta a un aptiveai:action: ok: true cuando se hizo, ok: false con un mensaje breve cuando no
aptiveai:themetheme: light o darkEl modo de tu página. Envíalo después de aptiveai:ready (de nuevo tras cada aptiveai:ready) y cada vez que tu página cambie
typeCamposSignificado
aptiveai:ready—El frame está escuchando. Envía aptiveai:session
aptiveai:signed-in—La persona inició sesión. Envía ahora aptiveai:context y aptiveai:actions
aptiveai:session-expired—La sesión del panel terminó. Envía un aptiveai:session nuevo
aptiveai:unavailablereasonNo se puede iniciar la sesión de la persona: no_account, disabled, bad_token, account_unavailable o no_agents (Solución de problemas). No envíes más tokens hasta que tu página vuelva a cargarse
aptiveai:taskid, statusUna tarea empezó o se abrió, o cambió de estado (los estados)
aptiveai:actionid, name, argumentsEl agente te pide hacer una de tus acciones. Responde con aptiveai:action-result y el mismo id
aptiveai:errorcodeSe rechazó un mensaje tuyo (unsupported_version, invalid_message, context_too_large, too_many_actions, invalid_action), o network: el panel no logró comunicarse con AptiveAI Agents al iniciar la sesión; envía un token nuevo

Un mensaje que pasa un límite se rechaza con aptiveai:error y no tiene efecto.

LímiteValor
Un mensaje aptiveai:context completo4 KB de JSON
Acciones en un aptiveai:actions20
name de una acción^[a-z][a-z0-9_]{0,39}$, sin repetir en la lista
description de una acciónDe 1 a 300 caracteres
label de una acción80 caracteres
parameters de una acciónUn JSON schema de type: "object" con properties, como máximo 2 KB de JSON
message de aptiveai:action-result300 caracteres (lo que sobra se corta)
id de aptiveai:action-result100 caracteres
token de aptiveai:session4.096 caracteres