Omnifox Node.js SDK: installation and first calls

How to install @omnifox/sdk, create the client with its real options, and make your first calls to contacts and messages.

Aug 19, 2026

Watch this step in the video · Official SDKs: Node, Python and PHP

The Omnifox Node.js SDK is published on npm as @omnifox/sdk. It's written in TypeScript, ships its own types, is distributed as ESM and CommonJS, and has no runtime dependencies: it uses the native fetch, which is why it requires Node 20 or higher.

Installation

npm install @omnifox/sdk
# or: pnpm add @omnifox/sdk
# or: yarn add @omnifox/sdk

Create the client

The exported class is called OmnifoxClient (not Omnifox) and there is no default export.

import { OmnifoxClient } from '@omnifox/sdk';

const client = new OmnifoxClient({
  apiKey: process.env.OMNIFOX_API_KEY!,
  workspaceId: 1,
});

Constructor options

Option Required? Default Notes
apiKey Yes — Omnifox personal token. Without it, the constructor throws OmnifoxClient: apiKey is required.
workspaceId No — Numeric workspace id.
baseUrl No https://app.omnifox.io/api/v1 Only changed for test environments.
timeout No 30000 Maximum time per request, in milliseconds.
maxRetries No 3 Retries on 429 and 5xx. 0 disables them.
fetch No globalThis.fetch Alternative fetch implementation.
userAgent No omnifox-sdk-node/<version> User-Agent header.

The option is not called token or retries: they are apiKey and maxRetries. A wrong name is silently ignored.

About workspaceId

Keys issued on the API Keys screen are already pinned to a workspace and the server resolves it from the token. Even so, it's worth passing it, because four endpoints require the id inside the body no matter how the token is set up:

  • PUT /agents/{id}/status → client.users.setAgentStatus()
  • POST /teams → client.teams.create()
  • POST /channels → client.channels.create()
  • POST /broadcasts → client.broadcasts.create()

If you didn't configure workspaceId, those four methods fail immediately with an error from the SDK itself, before hitting the network. And if the token is pinned to one workspace and you pass a different one, the server responds 403 on purpose.

First calls

// Look up a contact by id, email, phone, or external id
const contact = await client.contacts.get('email:[email protected]');

// Send a WhatsApp message
await client.messages.send({
  contact: 'phone:+593987654321',
  channel_id: 5,
  text: 'Hello from the Omnifox SDK',
});

// Walk every contact, without handling pages
for await (const c of client.contacts.list()) {
  console.log(c.id, c.display_name);
}

Flexible identifiers

Wherever a contact is expected you can pass an integer or a type:value selector: id:42, email:[email protected], phone:+593987654321, external:abc.

One exception: contacts.merge() does not accept selectors. Both of its ids have to be numeric.

Verification

const me = await client.users.me();
console.log(me);

If it returns your data, the key and the base URL are correct.

If something doesn't work

  • OmnifoxClient: apiKey is required: you forgot the key or the environment variable arrived empty.
  • global fetch is unavailable: you're on Node 18 or lower. Upgrade to Node 20 or pass your own implementation in options.fetch.
  • 403 when creating a channel, team, or broadcast: the workspaceId you passed doesn't match the token's.
  • Creating a contact responds 422: display_name is required in contacts.create().

Tips

  • contacts.create() takes custom_fields as an array of {field, value}, while contacts.upsert() takes it as a flat object. They are not interchangeable.
  • To close a conversation, the fields the server reads are resolution and notes.

Related articles

Was this helpful?

Related articles

Message us on WhatsApp