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.
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 emoptions.fetch.403ao criar um canal, equipe ou transmissão: oworkspaceIdque você passou não bate com o do token.- Ao criar um contato responde
422:display_nameé obrigatório emcontacts.create().
Dicas
contacts.create()recebecustom_fieldscomo array de{field, value}, enquantocontacts.upsert()recebe como objeto plano. Não são intercambiáveis.- Para fechar uma conversa, os campos que o servidor lê são
resolutionenotes.
Artigos relacionados
Artigos relacionados
-
Como conectar integrações e apps externos
Conecte o Omnifox às suas ferramentas favoritas a partir do catálogo de integrações em poucos passos.
-
Integrar o Omnifox com Azur, Siigo, Alegra, QuickBooks ou outro sistema contábil ou ERP
O Omnifox não tem hoje um conector nativo com sistemas contábeis ou ERP. Veja como fazer essa conexão mesmo assim com fluxos de trabalho, o nó HTTP, n8n, Make, Zapier ou a API, com exemplos.
-
Guia completo de integrações e API
Integrações e API a fundo, em 30 capítulos: chaves de API, chamadas reais, webhooks assinados, n8n, MCP e SDKs, tudo funcionando de verdade.
-
Gerar e usar API keys e webhooks
Crie chaves de API para acessar o Omnifox por código e configure webhooks para receber eventos em tempo real.
-
Introdução às integrações (webhook / OAuth / chave de API)
Conecte o Omnifox às suas outras ferramentas: o que está disponível hoje, o que chega em breve e quando usar um webhook, uma conexão OAuth ou uma chave de API.