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.

Nov 02, 2026

This is the complete guide to integrations and the API, in 30 chapters: API keys with scopes, the documentation, real calls (contacts, conversations, CRM, calendar), errors and pagination, signed webhooks with their history, the integration cards, n8n, the MCP server and the Node, Python and PHP SDKs. The PDF manual has the same chapters with screenshots and examples.

1. The ways to connect Omnifox

Everything for developers is in Settings, in the Development section: Webhooks, API keys and Integrations.

The idea is simple. With the REST API your system talks to Omnifox: it creates contacts, replies to conversations, books appointments. Webhooks are the other way around: Omnifox notifies your system every time something happens, for example when a message comes in.

And on top of that there are shortcuts: the n8n nodes, the MCP server so an AI can operate Omnifox, and the SDKs for Node, Python and PHP. They all use the same API key.

2. Requirements: plan and permissions

The API and webhooks come with the Crece, Escala and Enterprise plans. On a plan without API, the API replies that your plan doesn't include it.

To create API keys you need to be able to manage the workspace settings, and webhooks can only be created by an administrator. Each key is tied to one workspace.

3. Create an API key

We go to API keys. There are none yet. We press New API key.

We give it a name that says what it's for, in this case Tienda en línea, the online store, and choose the workspace. The key can only work in that workspace, which is why you'll almost never have to type the workspace number in your calls.

Expires on is optional: if you leave it empty, the key doesn't expire. For an external provider or a test, it's worth setting a date.

And Service token, or bot, is for integrations: what you send with this key isn't assigned to your user, doesn't change your online status and doesn't send notifications to your phone. We tick it.

4. Scopes: what the key can do

Now the permissions, called scopes. They're grouped by module: contacts, messages, channels, CRM, projects, calendar and webhooks, each with read and write.

If you don't tick any, the key has full access. The recommendation is to give it only what it needs. For our store we tick read and write contacts, read and send messages, CRM and calendar, and manage webhooks. On purpose we don't give it channels.

Write includes read in the same module. And Admin equals all scopes, so use it carefully.

5. Copy the key only once

We press Create key and Omnifox shows it only once. Copy it and keep it somewhere safe, like your server's secrets manager: you can't see it again afterwards. In this guide the key appears blurred for security.

If you lose it, no problem: it's regenerated and the previous one stops working.

6. The key list: edit, regenerate and delete

In the list you see each key with its type, user or bot, the workspace, its scopes, when it was last used and when it expires. At the top you can filter by type.

With the pencil you change the name, scopes or expiry without breaking the integration. Regenerate creates a new token with the same permissions, ideal if you suspect it leaked. And delete revokes it on the spot: any system using it is locked out.

7. The API documentation

The full documentation is at omnifox.io slash docs. At the top you have shortcuts to the n8n nodes, the MCP server and the SDKs.

Below is the reference for every endpoint, grouped by module: contacts, conversations, messages, CRM, calendar, webhooks and much more. Each one shows its parameters, a sample response and the possible errors.

With Authorize you paste your key and can try any call from the same page. And if you use Postman or a code generator, download the openapi dot json file.

8. Your first call

Let's move to the terminal. We store the key in an environment variable, so it's never written in commands or code.

Every call carries the Authorization header with the word Bearer and your key. We ask who am I: the API replies with your user and your plan.

All responses have the same shape: success, message and data. Also notice the rate limit headers: how many calls per minute your plan gives you and how many you have left.

9. Contacts via API

We create a contact with a POST to contacts: name, phone, email and city. The response includes its identifier.

We search for it by name with contacts search, and update it with a PUT, for example to add the company. To avoid duplicating customers, there's also upsert, which creates or updates based on phone or email.

And here it is, in Omnifox Contacts, with the data we sent from the terminal.

10. Scopes in action: the 403 error

What happens if the key tries something it isn't allowed to? We didn't give our key channels. We ask for the channel list and the API replies 403, with the missing scope: read channels.

Errors always tell you what happened: 401 if the key doesn't exist, expired or was revoked; 403 if a scope is missing or your plan doesn't include that feature; 422 if a value isn't valid, with the field and the reason; and 429 if you exceed the calls per minute limit.

11. Conversations and messages via API

Now, the most useful part: replying to a customer from your system. Gabriela wrote in the website chat asking whether they ship to Quito. We list the open conversations and there is hers.

We read her messages, and reply with a POST to conversations, its number, slash messages. Omnifox sends it through the same channel the customer wrote from.

And in the Omnifox inbox the reply appears, sent to Gabriela through the website chat. Before writing on WhatsApp, check window status: it tells you whether the twenty-four hour window is open or a template is needed.

12. CRM and calendar via API

The API reaches the whole platform. In the CRM, we create a deal for Gabriela in the wholesale sales pipeline, with its value.

In the calendar we ask for the free slots of the coffee tasting and book one. The appointment shows up in the Omnifox calendar as if it had been booked by hand, and it can also be rescheduled or cancelled via API.

The same goes for projects, catalog, orders, reports, teams, tags and broadcasts: it's all in the documentation.

13. Pagination and limits

Lists come in pages. With per page you choose how many items and with page which page. The response tells you the total and the last page.

Go through the pages to the end and don't ask for more than you need: if you hit the per-minute limit, the API replies 429; wait a few seconds and retry. The SDKs do both by themselves.

14. Webhooks: create a subscription

Now, webhooks. In Settings, Webhooks, we press New webhook.

We give it a name and your server's URL, which must be https. For this guide we use a small test receiver server that shows on screen everything it gets.

We choose the events: message received, message sent, conversation created and closed, contact created and updated, broadcast completed and the appointment ones, from booked to attended. We tick message received and conversation created.

15. Signing secret, retries and headers

The signing secret is the key Omnifox uses to sign each delivery. Copy it to your server to check that the notice really comes from Omnifox. Regenerate gives you a new one.

In the retry policy you choose the strategy: exponential, which is recommended and waits two, four, eight, sixteen seconds and so on up to five minutes; linear, every sixty seconds; or no retries. And the maximum number of retries.

The circuit breaker protects your server: after a number of consecutive failures, Omnifox stops sending for a while and then tries again. You can also add your own headers, for example a key on your side.

16. Test delivery

Before saving, Send test sends a test dot ping event to your URL and shows your server's response, the code and the time. It doesn't count toward the metrics or the circuit breaker.

We save the webhook and go to the receiver: there's the ping, signed and with a valid signature.

17. A real event

Now a real event. A new customer writes in the Café Montañero website chat.

Instantly, the receiver gets message dot received: the text, the contact, the conversation and the channel, all in JSON. And since the conversation is new, conversation dot created arrives too.

Each delivery carries headers: the event, a unique delivery identifier, so you don't process the same thing twice, the attempt number, the timestamp and the signature.

18. Verify the signature on your server

Verifying the signature takes ten lines. You join the timestamp, a dot and the exact body you received, compute an HMAC SHA two fifty-six with your secret, and compare it with the header, which starts with sha256 equals.

With the real delivery, the signature matches. If someone changes a single letter of the body, it no longer matches and your server must reject it. Also reject timestamps older than five minutes, to prevent replays.

19. Delivery history

In the webhook list you see each subscription with its status and events. When you open it, at the top you have the success rate for the last twenty-four hours and seven days, the average time and consecutive failures.

Below, the circuit breaker status and the history of each delivery: date, event, status, attempts and HTTP code, with filters. View payload shows you exactly what was sent and what your server replied.

If your server was down, failed deliveries are retried by themselves; and if the circuit was left open, you can close it by hand once you fix it.

20. The integrations page

Integrations has the ready-made connectors. n8n, Make, Zapier and Custom webhook work with webhooks in both directions. Azur connects Ecuador's electronic invoicing, and Cal.com your bookings.

The ones that say Coming soon, like HubSpot, Shopify, Google Sheets, Zoom or DocuSign, can't be connected yet. Meanwhile, almost all of that can be solved with the API, webhooks and n8n.

21. Custom webhook: inbound and outbound

We open Custom webhook. At the top is your inbound URL: your system sends it a POST with an action, like creating a contact, tagging it or sending a message, signed with the secret below.

Below goes your outbound URL and the events you want to receive. When you save, Omnifox creates the subscription and starts sending you those events, signed with the same secret.

Let's try it: from the terminal we send the create contact action, signed. Omnifox replies that it created it, and the contact is already in the list.

22. n8n: install the Omnifox node

n8n is an automation tool you can use in its cloud or install for free on your server. Here we have our own installation.

In Settings, Community nodes, we press Install, type n8n nodes omnifox, accept the notice and install it. Two nodes appear: Omnifox, with the actions, and Omnifox Trigger, which listens for events.

23. n8n: the Omnifox credential

We create the Omnifox API credential and paste an Omnifox API key. Here we use the one we created, which is a bot key; ideally use a separate key for each integration.

The base URL is Omnifox's, and you can leave the workspace at zero: it's taken from the key. When saving, n8n tests the connection and tells us it works.

24. n8n: reply only when they ask for the price

This workflow has three nodes. The first, Omnifox Trigger, listens for the message received event. When activated, it creates the webhook subscription in Omnifox by itself and verifies each notice's signature.

The second, an If, checks whether the message text contains the word precio, price. And the third, Omnifox, with the message resource and the send operation, replies in the same conversation with the price list.

We activate it. And in Omnifox, in Webhooks, the subscription n8n created already shows up.

And the acid test: a customer asks about the price in the website chat. In a couple of seconds the automatic reply arrives, and n8n logs the execution, step by step.

25. n8n: all the operations

The Omnifox node has a hundred and forty operations: conversations, contacts, messages, tags, campaigns, channels, teams, AI agents, CRM, boards, calendar, catalog and orders. Lists, like channels or tags, load by themselves from your account.

Two typical mistakes: a key from another workspace, which returns empty data or a 403, and the base URL with slash api at the end, which isn't needed: the node adds it.

26. MCP: let an AI operate Omnifox

MCP, the Model Context Protocol, is the standard for AI assistants like Claude, Cursor or ChatGPT to use tools. The Omnifox MCP server gives them seventy-two tools: contacts, conversations, calendar, catalog, orders, workflows, broadcasts and more.

It's installed with npx, and it only needs two variables: your API key and the API URL. The AI can only do what that key's scopes allow.

27. Test the MCP server with the Inspector

To see what it does without connecting an assistant yet, we use MCP Inspector, the official testing tool. We connect and list the tools, each with its description and parameters.

We choose search contacts, search for Gabriela and the response brings her real record. Now create contact, with a new customer: we run it and it's created in Omnifox, just as if an assistant had done it.

To connect it to Claude Desktop or Cursor, paste this block into their MCP configuration: the npx command, the package and the two variables. And for a remote server, MCP also works over HTTP.

28. Official SDKs: Node, Python and PHP

If you code, the SDKs save you work: they handle authentication, pagination, retries and errors. With Node, you install at omnifox slash sdk.

This script creates a client with the key, goes through the contacts from Loja and tags one of them as a wholesale customer. We run it and that's it.

In Python it's the same, with pip install omnifox, and it also has an async version. And in PHP, with composer require omnifox slash sdk. All three have the same resources and names.

29. Security best practices

Some best practices: one key per integration, with minimum scopes and of bot type. Keep it in environment variables, never in code or in the browser. Give it an expiry if it's temporary, and regenerate it if someone who knew it leaves.

In your webhooks: always verify the signature, reply quickly with a 200 and process later in a queue, and use the delivery identifier so you don't process the same event twice.

30. Troubleshooting

A 401? The key was copied wrong, expired or was regenerated. A 403? Check the key's scopes and that your plan includes the API. Empty data? The key probably belongs to another workspace.

The webhook doesn't arrive? Look at the delivery history: if there are errors, the HTTP code tells you what your server replied; if the circuit is open, close it once you fix it; and confirm the URL is https and public.

Was this helpful?

Related articles

Message us on WhatsApp