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.

Aug 19, 2026

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 en options.fetch.
  • 403 al crear un canal, equipo o difusión: el workspaceId que pasaste no coincide con el del token.
  • Al crear un contacto responde 422: display_name es obligatorio en contacts.create().

Consejos

  • contacts.create() recibe custom_fields como arreglo de {field, value}, mientras que contacts.upsert() lo recibe como objeto plano. No son intercambiables.
  • Para cerrar una conversación, los campos que el servidor lee son resolution y notes.

Artículos relacionados

¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp