SDK de Python de Omnifox: cliente síncrono y asíncrono

Cómo instalar el paquete omnifox, crear los clientes Omnifox y AsyncOmnifox, y las diferencias que hay que conocer al usar el asíncrono.

Aug 19, 2026

Mira este paso en el video · SDK oficiales: Node, Python y PHP

El SDK de Python de Omnifox se publica en PyPI como omnifox. Trae dos clientes con la misma superficie: Omnifox (síncrono) y AsyncOmnifox (asíncrono). Requiere Python 3.9 o superior y depende de httpx y pydantic.

Instalación

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()

También funciona como gestor de contexto: with Omnifox("...") as client:.

Cliente así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())

Si no usas async with, cierra el cliente con await client.aclose().

Parámetros del constructor

api_key es posicional y obligatorio; todo lo demás va por nombre.

Parámetro Valor por defecto Notas
api_key — Posicional. Vacío lanza ValueError("api_key is required").
workspace_id None Id numérico del espacio de trabajo.
base_url https://app.omnifox.io/api/v1 Solo para entornos de prueba.
timeout 30.0 En segundos (a diferencia del SDK de Node, que es en milisegundos).
max_retries 3 Reintentos ante 429, 500, 502, 503, 504 y errores de conexión.
backoff_base 0.5 Segundos de espera inicial entre reintentos.
backoff_max 30.0 Tope de espera entre reintentos.
user_agent — Encabezado User-Agent.
default_headers None Encabezados extra en todas las llamadas.
http_client None Tu propio httpx.Client o httpx.AsyncClient. Si lo pasas, el SDK no lo cierra.

El SDK no lee variables de entorno: la clave siempre se pasa explícitamente.

El detalle del asíncrono que más confunde

No todos los list() se esperan igual:

  • Los listados paginados (contactos, conversaciones, mensajes, canales, difusiones, campos personalizados, etiquetas, respuestas rápidas, webhooks, flujos, usuarios, espacios, equipos, empresas, oportunidades y actividades de CRM) devuelven un iterador. Se recorren con async for, sin await.
  • Los listados no paginados (pipelines.list(), boards.list(), appointments.list(), products.list(), orders.list(), quotes.list()) devuelven una lista y sí llevan await.
  • Todo lo demás (get, create, send, …) lleva await.

Espacio de trabajo obligatorio en cuatro llamadas

Cuatro endpoints exigen el id del espacio dentro del cuerpo, aunque el token ya esté fijado a uno. En el SDK de Python son:

  • client.users.update_status()
  • client.teams.create()
  • client.channels.connect()
  • client.broadcasts.create()

Si no pasaste workspace_id al constructor, esos métodos lanzan un ValueError local antes de salir a la red.

Verificación

print(client.users.me())

Si algo no funciona

  • ValueError: api_key is required: la clave llegó vacía.
  • TypeError al llamar un método: revisa el nombre de los parámetros con nombre; son distintos a los del SDK de Node.
  • Un httpx.ConnectError o httpx.ReadTimeout sin envolver: se agotaron los reintentos. El SDK no convierte esas excepciones de red a errores propios.
  • ValueError al pedir un reporte: el preset no es válido. Los aceptados son today, yesterday, 7d, 30d, 90d, this_month y last_month.

Consejos

  • El parámetro de fecha inicial de los reportes se llama from_, con guion bajo, porque from es palabra reservada de Python.
  • Para fusionar contactos los nombres exactos son primary_contact_id y merged_contact_id, ambos numéricos y por nombre.
  • Para disparar un flujo, la firma real es trigger(workflow_id, context={...}, force=False).

Artículos relacionados

¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp