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.
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, sinawait. - Los listados no paginados (
pipelines.list(),boards.list(),appointments.list(),products.list(),orders.list(),quotes.list()) devuelven una lista y sí llevanawait. - Todo lo demás (
get,create,send, …) llevaawait.
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.TypeErroral llamar un método: revisa el nombre de los parámetros con nombre; son distintos a los del SDK de Node.- Un
httpx.ConnectErrorohttpx.ReadTimeoutsin envolver: se agotaron los reintentos. El SDK no convierte esas excepciones de red a errores propios. ValueErroral pedir un reporte: elpresetno es válido. Los aceptados sontoday,yesterday,7d,30d,90d,this_monthylast_month.
Consejos
- El parámetro de fecha inicial de los reportes se llama
from_, con guion bajo, porquefromes palabra reservada de Python. - Para fusionar contactos los nombres exactos son
primary_contact_idymerged_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
Artículos relacionados
-
Cómo conectar integraciones y apps externas
Conecta Omnifox con tus herramientas favoritas desde el catálogo de integraciones en pocos pasos.
-
Guía completa de integraciones y API
Integraciones y API a fondo, en 30 capítulos: claves API, llamadas reales, webhooks firmados, n8n, MCP y SDK, todo funcionando de verdad.
-
Integrar Omnifox con Azur, Siigo, Alegra, QuickBooks u otro sistema contable o ERP
Omnifox no tiene hoy un conector nativo con sistemas contables o ERP. Te explicamos cómo conectarlos igual con workflows, el nodo HTTP, n8n, Make, Zapier o la API, con ejemplos.
-
Generar y usar API keys y webhooks
Crea claves de API para acceder a Omnifox por código y configura webhooks para recibir eventos en tiempo real.
-
Introducción a las integraciones (webhook / OAuth / API key)
Conecta Omnifox con tus otras herramientas: qué está disponible hoy, qué llega pronto y cuándo usar un webhook, una conexión OAuth o una clave de API.