SDK de Node.js da Omnifox: instalação e primeiras chamadas

Como instalar o @omnifox/sdk, criar o cliente com as opções reais dele e fazer as primeiras chamadas a contatos e mensagens.

Aug 19, 2026

Veja este passo no vídeo · SDKs oficiais: Node, Python e PHP

O SDK de Node.js da Omnifox é publicado no npm como @omnifox/sdk. Ele é escrito em TypeScript, traz os próprios tipos, é distribuído em ESM e CommonJS e não tem dependências de execução: usa o fetch nativo, por isso exige Node 20 ou superior.

Instalação

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

Criar o cliente

A classe exportada se chama OmnifoxClient (não Omnifox) e não existe exportação padrão.

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

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

Opções do construtor

Opção Obrigatória? Valor padrão Observações
apiKey Sim — Token pessoal da Omnifox. Sem ele, o construtor lança OmnifoxClient: apiKey is required.
workspaceId Não — Id numérico do espaço de trabalho.
baseUrl Não https://app.omnifox.io/api/v1 Só se muda para ambientes de teste.
timeout Não 30000 Tempo máximo por requisição, em milissegundos.
maxRetries Não 3 Novas tentativas diante de 429 e 5xx. 0 desativa.
fetch Não globalThis.fetch Implementação alternativa de fetch.
userAgent Não omnifox-sdk-node/<versão> Cabeçalho User-Agent.

A opção não se chama token nem retries: são apiKey e maxRetries. Um nome errado é ignorado em silêncio.

Sobre o workspaceId

As chaves emitidas na tela de API Keys já estão fixadas a um espaço de trabalho e o servidor resolve isso pelo token. Mesmo assim vale a pena passá-lo, porque quatro endpoints exigem o id dentro do corpo, não importa como o token esteja:

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

Se você não configurou o workspaceId, esses quatro métodos falham na hora com um erro do próprio SDK, antes de sair para a rede. E se o token está fixado a um espaço e você passa outro diferente, o servidor responde 403 de propósito.

Primeiras chamadas

// Buscar um contato por id, e-mail, telefone ou id externo
const contact = await client.contacts.get('email:[email protected]');

// Enviar uma mensagem de WhatsApp
await client.messages.send({
  contact: 'phone:+593987654321',
  channel_id: 5,
  text: 'Hola desde el SDK de Omnifox',
});

// Percorrer todos os contatos, sem lidar com páginas
for await (const c of client.contacts.list()) {
  console.log(c.id, c.display_name);
}

Identificadores flexíveis

Onde se pede um contato você pode passar um inteiro ou um seletor tipo:valor: id:42, email:[email protected], phone:+593987654321, external:abc.

Uma exceção: contacts.merge() não aceita seletores. Os dois ids dele precisam ser numéricos.

Verificação

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

Se retornar os seus dados, a chave e a URL base estão certas.

Se algo não funcionar

  • OmnifoxClient: apiKey is required: você esqueceu a chave ou a variável de ambiente chegou vazia.
  • global fetch is unavailable: você está no Node 18 ou inferior. Atualize para o Node 20 ou passe a sua própria implementação em options.fetch.
  • 403 ao criar um canal, equipe ou transmissão: o workspaceId que você passou não bate com o do token.
  • Ao criar um contato responde 422: display_name é obrigatório em contacts.create().

Dicas

  • contacts.create() recebe custom_fields como array de {field, value}, enquanto contacts.upsert() recebe como objeto plano. Não são intercambiáveis.
  • Para fechar uma conversa, os campos que o servidor lê são resolution e notes.

Artigos relacionados

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp