SDK de Node.js de Omnifox: instalación y primeras llamadas
Cómo instalar @omnifox/sdk, crear el cliente con sus opciones reales y hacer las primeras llamadas a contactos y mensajes.
Mira este paso en el video · SDK oficiales: Node, Python y PHP
El SDK de Node.js de Omnifox se publica en npm como @omnifox/sdk. Está escrito en TypeScript, trae sus propios tipos, se distribuye en ESM y CommonJS y no tiene dependencias de ejecución: usa el fetch nativo, por eso pide Node 20 o superior.
Instalación
npm install @omnifox/sdk
# o: pnpm add @omnifox/sdk
# o: yarn add @omnifox/sdk
Crear el cliente
La clase exportada se llama OmnifoxClient (no Omnifox) y no hay exportación por defecto.
import { OmnifoxClient } from '@omnifox/sdk';
const client = new OmnifoxClient({
apiKey: process.env.OMNIFOX_API_KEY!,
workspaceId: 1,
});
Opciones del constructor
| Opción | ¿Obligatoria? | Valor por defecto | Notas |
|---|---|---|---|
apiKey |
Sí | — | Token personal de Omnifox. Sin él, el constructor lanza OmnifoxClient: apiKey is required. |
workspaceId |
No | — | Id numérico del espacio de trabajo. |
baseUrl |
No | https://app.omnifox.io/api/v1 |
Solo se cambia para entornos de prueba. |
timeout |
No | 30000 |
Tiempo máximo por petición, en milisegundos. |
maxRetries |
No | 3 |
Reintentos ante 429 y 5xx. 0 los desactiva. |
fetch |
No | globalThis.fetch |
Implementación alternativa de fetch. |
userAgent |
No | omnifox-sdk-node/<versión> |
Encabezado User-Agent. |
La opción no se llama token ni retries: son apiKey y maxRetries. Un nombre equivocado se ignora en silencio.
Sobre workspaceId
Las claves emitidas en la pantalla de API Keys ya están fijadas a un espacio de trabajo y el servidor lo resuelve del token. Aun así conviene pasarlo, porque cuatro endpoints exigen el id dentro del cuerpo sin importar cómo esté el token:
PUT /agents/{id}/status→client.users.setAgentStatus()POST /teams→client.teams.create()POST /channels→client.channels.create()POST /broadcasts→client.broadcasts.create()
Si no configuraste workspaceId, esos cuatro métodos fallan de inmediato con un error del propio SDK, antes de salir a la red. Y si el token está fijado a un espacio y pasas otro distinto, el servidor responde 403 a propósito.
Primeras llamadas
// Buscar un contacto por id, correo, teléfono o id externo
const contact = await client.contacts.get('email:[email protected]');
// Enviar un mensaje de WhatsApp
await client.messages.send({
contact: 'phone:+593987654321',
channel_id: 5,
text: 'Hola desde el SDK de Omnifox',
});
// Recorrer todos los contactos, sin manejar páginas
for await (const c of client.contacts.list()) {
console.log(c.id, c.display_name);
}
Identificadores flexibles
Donde se pide un contacto puedes pasar un entero o un selector tipo:valor: id:42, email:[email protected], phone:+593987654321, external:abc.
Una excepción: contacts.merge() no acepta selectores. Sus dos ids tienen que ser numéricos.
Verificación
const me = await client.users.me();
console.log(me);
Si devuelve tus datos, la clave y la URL base están bien.
Si algo no funciona
OmnifoxClient: apiKey is required: olvidaste la clave o la variable de entorno llegó vacía.global fetch is unavailable: estás en Node 18 o menor. Actualiza a Node 20 o pasa tu propia implementación enoptions.fetch.403al crear un canal, equipo o difusión: elworkspaceIdque pasaste no coincide con el del token.- Al crear un contacto responde
422:display_namees obligatorio encontacts.create().
Consejos
contacts.create()recibecustom_fieldscomo arreglo de{field, value}, mientras quecontacts.upsert()lo recibe como objeto plano. No son intercambiables.- Para cerrar una conversación, los campos que el servidor lee son
resolutionynotes.
Artículos relacionados
Artículos relacionados
-
Cómo conectar integraciones y apps externas
Conecta Omnifox con tus herramientas favoritas desde el catálogo de integraciones en pocos pasos.
-
Guía completa de integraciones y API
Integraciones y API a fondo, en 30 capítulos: claves API, llamadas reales, webhooks firmados, n8n, MCP y SDK, todo funcionando de verdad.
-
Integrar Omnifox con Azur, Siigo, Alegra, QuickBooks u otro sistema contable o ERP
Omnifox no tiene hoy un conector nativo con sistemas contables o ERP. Te explicamos cómo conectarlos igual con workflows, el nodo HTTP, n8n, Make, Zapier o la API, con ejemplos.
-
Generar y usar API keys y webhooks
Crea claves de API para acceder a Omnifox por código y configura webhooks para recibir eventos en tiempo real.
-
Introducción a las integraciones (webhook / OAuth / API key)
Conecta Omnifox con tus otras herramientas: qué está disponible hoy, qué llega pronto y cuándo usar un webhook, una conexión OAuth o una clave de API.