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.
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 inoptions.fetch.403when creating a channel, team, or broadcast: theworkspaceIdyou passed doesn't match the token's.- Creating a contact responds
422:display_nameis required incontacts.create().
Tips
contacts.create()takescustom_fieldsas an array of{field, value}, whilecontacts.upsert()takes it as a flat object. They are not interchangeable.- To close a conversation, the fields the server reads are
resolutionandnotes.
Related articles
Related articles
-
How to connect integrations and external apps
Connect Omnifox with your favorite tools from the integrations catalog in just a few steps.
-
Integrations and API complete guide
Integrations and API in depth, in 30 chapters: API keys, real calls, signed webhooks, n8n, MCP and SDKs, all really working.
-
Connecting Omnifox to Azur, Siigo, Alegra, QuickBooks or another accounting system or ERP
Omnifox doesn't have a native connector for accounting systems or ERPs today. Here's how to connect them anyway with workflows, the HTTP node, n8n, Make, Zapier or the API, with examples.
-
Generate and use API keys and webhooks
Create API keys to access Omnifox programmatically and set up webhooks to receive real-time events.
-
Getting started with integrations (webhook / OAuth / API key)
Connect Omnifox with your other tools: what's available today, what's coming soon, and when to use a webhook, an OAuth connection or an API key.