SDK del chat

Los SDK de JavaScript (@utilia-os/sdk-js) y Python (utilia-sdk) tienen sdk.chat, con lo mismo en los dos lenguajes: publicar, leer, organizar canales y, en sdk.chat.agents, gestionar agentes de IA. La verificación de los avisos está en sdk.webhooks, común a todos los avisos de UTILIA OS. Esta página usa la versión actual de los dos SDK, la 4.1.0.

Necesitas una aplicación externa con su clave de API y los scopes de lo que vayas a usar (están en Scopes y acceso por canal).

Métodos

Los agentes de IA (sdk.chat.agents: install, list, update, pause, resume y remove) tienen su propia página: Gestionar agentes de IA.

Instalar y configurar

npm install @utilia-os/sdk-js

import { UtiliaSDK } from '@utilia-os/sdk-js';
 
const sdk = new UtiliaSDK({
  baseURL: 'https://os.utilia.ai/api',
  apiKey: process.env.UTILIA_API_KEY,
});

Leer canales y mensajes

// Canales a los que la app tiene acceso concedido.
const canales = await sdk.chat.listChannels({ limit: 20 });
for (const canal of canales.data) {
  console.log(canal.id, canal.name);
}
 
// Miembros de un canal.
const miembros = await sdk.chat.listMembers('cnv_8f3a21');
 
// Historial visible, del más reciente al más antiguo (cursor).
let cursor: string | null = null;
do {
  const pagina = await sdk.chat.listMessages('cnv_8f3a21', {
    limit: 50,
    cursor: cursor ?? undefined,
  });
  for (const mensaje of pagina.data) {
    console.log(mensaje.author.displayName, mensaje.content);
  }
  cursor = pagina.pagination.nextCursor;
} while (cursor);
 
// Buscar por texto dentro de un canal.
const encontrados = await sdk.chat.listMessages('cnv_8f3a21', {
  search: 'temperatura',
});
 
// Detalle de un mensaje concreto (útil tras recibir un webhook).
const mensaje = await sdk.chat.getMessage('msg_a1b2c3d4');

Organizar canales

Estos métodos cumplen las mismas reglas que la API: el scope autoriza la acción, la concesión en el canal autoriza el lugar, y tu aplicación nunca puede más que la persona que le dio acceso. Sin el scope, la respuesta es 403; sin concesión activa en el canal, 404. Los detalles están en Crear canales y gestionar miembros.

// Crear un canal como la app (queda como creadora/participante).
const canal = await sdk.chat.createChannel({
  name: 'incidencias',
  description: 'Alertas del termómetro',
});
 
// Editar el nombre y/o la descripción de un canal concedido.
await sdk.chat.updateChannel(canal.id, { name: 'incidencias-graves' });
 
// Añadir un usuario interno (siempre con rol MEMBER).
await sdk.chat.addMember(canal.id, { userId: 'usr_7a1b' });
 
// Retirar a un usuario interno.
await sdk.chat.removeMember(canal.id, 'usr_7a1b'); // -> { success: true }
 
// Archivar el canal cuando ya no se use.
await sdk.chat.archiveChannel(canal.id);

Verificar la firma de un aviso

sdk.webhooks.verify comprueba la firma de un aviso entrante sin llamadas de red: recalcula el HMAC, lo compara en tiempo constante y rechaza los avisos con más de 300 segundos de diferencia. Si todo cuadra, devuelve el aviso; si no, lanza un error. Lee las cabeceras directamente del objeto de cabeceras de tu servidor.

Pásale siempre el cuerpo tal como llega, como texto. Si tu servidor ya lo ha convertido a JSON y lo vuelves a serializar, la firma no coincidirá: configúralo para conservar el cuerpo original.

const aviso = sdk.webhooks.verify(cuerpo, req.headers, process.env.UTILIA_WEBHOOK_SECRET!);
 
console.log(aviso.event); // 'CHAT_MESSAGE_CREATED'

El nombre del evento va en mayúsculas con guiones bajos (CHAT_MESSAGE_CREATED), igual que en la cabecera X-Utilia-Event. La lista completa está en Webhooks de chat.

Siguiente paso

El ejemplo del termómetro usa estos métodos de principio a fin: publicar, recibir el aviso, verificarlo y contestar.