Omnifox Python SDK: sync and async clients
How to install the omnifox package, create the Omnifox and AsyncOmnifox clients, and the differences you need to know when using the async one.
Watch this step in the video · Official SDKs: Node, Python and PHP
The Omnifox Python SDK is published on PyPI as omnifox. It ships two clients with the same surface: Omnifox (sync) and AsyncOmnifox (async). It requires Python 3.9 or higher and depends on httpx and pydantic.
Installation
pip install omnifox
Sync client
from omnifox import Omnifox
client = Omnifox("your-token-here", workspace_id=1)
contact = client.contacts.get("email:[email protected]")
client.messages.send(
contact="id:42",
channel_id=5,
text="Hello from the Omnifox SDK",
)
for c in client.contacts.list(pagination="cursor"):
print(c.id, c.display_name)
client.close()
It also works as a context manager: with Omnifox("...") as client:.
Async client
import asyncio
from omnifox import AsyncOmnifox
async def main() -> None:
async with AsyncOmnifox("your-token-here", workspace_id=1) as client:
async for contact in client.contacts.list(pagination="cursor"):
print(contact.id, contact.email)
await client.messages.send(
contact="phone:+593987654321",
whatsapp_template={"name": "welcome_v2", "language": "es"},
)
asyncio.run(main())
If you don't use async with, close the client with await client.aclose().
Constructor parameters
api_key is positional and required; everything else is keyword-only.
| Parameter | Default | Notes |
|---|---|---|
api_key |
— | Positional. Empty raises ValueError("api_key is required"). |
workspace_id |
None |
Numeric workspace id. |
base_url |
https://app.omnifox.io/api/v1 |
Test environments only. |
timeout |
30.0 |
In seconds (unlike the Node SDK, which uses milliseconds). |
max_retries |
3 |
Retries on 429, 500, 502, 503, 504, and connection errors. |
backoff_base |
0.5 |
Initial wait between retries, in seconds. |
backoff_max |
30.0 |
Cap on the wait between retries. |
user_agent |
— | User-Agent header. |
default_headers |
None |
Extra headers on every call. |
http_client |
None |
Your own httpx.Client or httpx.AsyncClient. If you pass it, the SDK does not close it. |
The SDK does not read environment variables: the key is always passed explicitly.
The async detail that confuses people most
Not every list() is awaited the same way:
- Paginated lists (contacts, conversations, messages, channels, broadcasts, custom fields, tags, quick replies, webhooks, workflows, users, workspaces, teams, companies, deals, and CRM activities) return an iterator. You walk them with
async for, with noawait. - Non-paginated lists (
pipelines.list(),boards.list(),appointments.list(),products.list(),orders.list(),quotes.list()) return a list and do takeawait. - Everything else (
get,create,send, …) takesawait.
Workspace required in four calls
Four endpoints require the workspace id inside the body, even when the token is already pinned to one. In the Python SDK they are:
client.users.update_status()client.teams.create()client.channels.connect()client.broadcasts.create()
If you didn't pass workspace_id to the constructor, those methods raise a local ValueError before hitting the network.
Verification
print(client.users.me())
If something doesn't work
ValueError: api_key is required: the key arrived empty.TypeErrorwhen calling a method: check the keyword parameter names; they differ from the Node SDK's.- An unwrapped
httpx.ConnectErrororhttpx.ReadTimeout: the retries ran out. The SDK does not convert those network exceptions into its own errors. ValueErrorwhen requesting a report: thepresetis not valid. The accepted ones aretoday,yesterday,7d,30d,90d,this_month, andlast_month.
Tips
- The start-date parameter for reports is called
from_, with an underscore, becausefromis a reserved word in Python. - To merge contacts, the exact names are
primary_contact_idandmerged_contact_id, both numeric and keyword-only. - To trigger a workflow, the real signature is
trigger(workflow_id, context={...}, force=False).
Related articles
Related articles
-
How to connect integrations and external apps
Connect Omnifox with your favorite tools from the integrations catalog in just a few steps.
-
Integrations and API complete guide
Integrations and API in depth, in 30 chapters: API keys, real calls, signed webhooks, n8n, MCP and SDKs, all really working.
-
Connecting Omnifox to Azur, Siigo, Alegra, QuickBooks or another accounting system or ERP
Omnifox doesn't have a native connector for accounting systems or ERPs today. Here's how to connect them anyway with workflows, the HTTP node, n8n, Make, Zapier or the API, with examples.
-
Generate and use API keys and webhooks
Create API keys to access Omnifox programmatically and set up webhooks to receive real-time events.
-
Getting started with integrations (webhook / OAuth / API key)
Connect Omnifox with your other tools: what's available today, what's coming soon, and when to use a webhook, an OAuth connection or an API key.