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.

Aug 19, 2026

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, sem await.
  • As listagens não paginadas (pipelines.list(), boards.list(), appointments.list(), products.list(), orders.list(), quotes.list()) retornam uma lista e levam await.
  • Todo o resto (get, create, send, …) leva await.

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.
  • TypeError ao chamar um método: revise o nome dos parâmetros nomeados; eles são diferentes dos do SDK de Node.
  • Um httpx.ConnectError ou httpx.ReadTimeout sem envolver: as novas tentativas se esgotaram. O SDK não converte essas exceções de rede em erros próprios.
  • ValueError ao pedir um relatório: o preset não é válido. Os aceitos são today, yesterday, 7d, 30d, 90d, this_month e last_month.

Dicas

  • O parâmetro de data inicial dos relatórios se chama from_, com underscore, porque from é palavra reservada do Python.
  • Para mesclar contatos, os nomes exatos são primary_contact_id e merged_contact_id, ambos numéricos e nomeados.
  • Para disparar um fluxo, a assinatura real é trigger(workflow_id, context={...}, force=False).

Artigos relacionados

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp