SDK de Python da Omnifox: cliente síncrono e assíncrono
Como instalar o pacote omnifox, criar os clientes Omnifox e AsyncOmnifox, e as diferenças que você precisa conhecer ao usar o assíncrono.
Veja este passo no vídeo · SDKs oficiais: Node, Python e PHP
O SDK de Python da Omnifox é publicado no PyPI como omnifox. Ele traz dois clientes com a mesma superfície: Omnifox (síncrono) e AsyncOmnifox (assíncrono). Exige Python 3.9 ou superior e depende de httpx e pydantic.
Instalação
pip install omnifox
Cliente síncrono
from omnifox import Omnifox
client = Omnifox("tu-token-aqui", workspace_id=1)
contacto = client.contacts.get("email:[email protected]")
client.messages.send(
contact="id:42",
channel_id=5,
text="Hola desde el SDK de Omnifox",
)
for c in client.contacts.list(pagination="cursor"):
print(c.id, c.display_name)
client.close()
Ele também funciona como gerenciador de contexto: with Omnifox("...") as client:.
Cliente assíncrono
import asyncio
from omnifox import AsyncOmnifox
async def main() -> None:
async with AsyncOmnifox("tu-token-aqui", workspace_id=1) as client:
async for contacto in client.contacts.list(pagination="cursor"):
print(contacto.id, contacto.email)
await client.messages.send(
contact="phone:+593987654321",
whatsapp_template={"name": "welcome_v2", "language": "es"},
)
asyncio.run(main())
Se você não usar async with, feche o cliente com await client.aclose().
Parâmetros do construtor
api_key é posicional e obrigatório; todo o resto vai por nome.
| Parâmetro | Valor padrão | Observações |
|---|---|---|
api_key |
— | Posicional. Vazio lança ValueError("api_key is required"). |
workspace_id |
None |
Id numérico do espaço de trabalho. |
base_url |
https://app.omnifox.io/api/v1 |
Só para ambientes de teste. |
timeout |
30.0 |
Em segundos (diferente do SDK de Node, que é em milissegundos). |
max_retries |
3 |
Novas tentativas diante de 429, 500, 502, 503, 504 e erros de conexão. |
backoff_base |
0.5 |
Segundos de espera inicial entre tentativas. |
backoff_max |
30.0 |
Teto de espera entre tentativas. |
user_agent |
— | Cabeçalho User-Agent. |
default_headers |
None |
Cabeçalhos extras em todas as chamadas. |
http_client |
None |
Seu próprio httpx.Client ou httpx.AsyncClient. Se você passar um, o SDK não o fecha. |
O SDK não lê variáveis de ambiente: a chave sempre é passada explicitamente.
O detalhe do assíncrono que mais confunde
Nem todos os list() são aguardados do mesmo jeito:
- As listagens paginadas (contatos, conversas, mensagens, canais, transmissões, campos personalizados, etiquetas, respostas rápidas, webhooks, fluxos, usuários, espaços, equipes, empresas, oportunidades e atividades de CRM) retornam um iterador. Você as percorre com
async for, semawait. - As listagens não paginadas (
pipelines.list(),boards.list(),appointments.list(),products.list(),orders.list(),quotes.list()) retornam uma lista e levamawait. - Todo o resto (
get,create,send, …) levaawait.
Espaço de trabalho obrigatório em quatro chamadas
Quatro endpoints exigem o id do espaço dentro do corpo, mesmo que o token já esteja fixado a um. No SDK de Python são:
client.users.update_status()client.teams.create()client.channels.connect()client.broadcasts.create()
Se você não passou workspace_id ao construtor, esses métodos lançam um ValueError local antes de sair para a rede.
Verificação
print(client.users.me())
Se algo não funcionar
ValueError: api_key is required: a chave chegou vazia.TypeErrorao chamar um método: revise o nome dos parâmetros nomeados; eles são diferentes dos do SDK de Node.- Um
httpx.ConnectErrorouhttpx.ReadTimeoutsem envolver: as novas tentativas se esgotaram. O SDK não converte essas exceções de rede em erros próprios. ValueErrorao pedir um relatório: opresetnão é válido. Os aceitos sãotoday,yesterday,7d,30d,90d,this_monthelast_month.
Dicas
- O parâmetro de data inicial dos relatórios se chama
from_, com underscore, porquefromé palavra reservada do Python. - Para mesclar contatos, os nomes exatos são
primary_contact_idemerged_contact_id, ambos numéricos e nomeados. - Para disparar um fluxo, a assinatura real é
trigger(workflow_id, context={...}, force=False).
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.