Custom channel: what it is and how to set it up
Connect your own system (app, platform or bespoke CRM) to Omnifox with the custom channel: how it works and how to set it up step by step.
The custom channel (listed in the channel picker as Custom Channel) connects any in-house system that has no native connector to Omnifox: your app, your booking platform, an internal chat, a ticketing system or a bespoke CRM. Messages from your users land in the Omnifox inbox like any other channel, and replies from your agents, your AI agent or your workflows go back to your system.
This article explains what the channel is and how to set it up on screen. For the development side (message format, signing, events and code samples), share the Custom channel technical integration guide with your developer.
Contents
- How it works
- Before you start
- Create the channel step by step
- Merge with existing contacts: when to turn it on
- What happens once the channel is live
- What the custom channel does not do
- Common issues
1. How it works
The channel uses two web addresses and one key:
- Incoming Webhook URL: generated by Omnifox. Your system sends every message from your users to it.
- Outgoing Webhook URL: provided by you. Omnifox sends replies there, plus notices about what happens in the conversation (assigned, closed, read…).
- Secret Key: a single key signs messages in both directions, so nobody can impersonate your system or Omnifox.
Every incoming message identifies the person with a contact ID (that user's ID in your system). Each distinct ID is a separate contact in Omnifox, with its own conversation.
2. Before you start
- The custom channel is included in the Escala and Exclusivo plans.
- Your system must be able to send HTTP requests with JSON and receive Omnifox's requests at a public HTTPS address. This is usually set up by your developer.
- Pick a clear name for the channel, such as Booking app or Customer portal.
3. Create the channel step by step
- Go to Settings → Channels → Connect New Channel and choose Custom Channel.
- Enter the Channel Name.
- Copy the Incoming Webhook URL with the copy button and give it to your developer. It is generated once and does not change when you edit the channel. It starts receiving messages as soon as you save the channel.
- In Outgoing Webhook URL, paste the address on your system where Omnifox should send replies, for example
https://your-system.com/omnifox. It is optional, but without it the channel only receives: replies from agents and the AI are marked as failed. - Copy the Secret Key and hand it to your developer through a secure channel. If it ever leaks, click Regenerate, save the channel and update the key in your system: the old one stops working.
- Under Merge with existing contacts, leave Merge by phone and Merge by email off unless you are sure you need them (see section 4).
- Under Events to send, choose which notices your system should receive in addition to messages (which are always sent): conversation created, assigned or transferred, closed, reopened, priority changed, tag added, AI handed the conversation to a human, agent read the conversation, and more. All of them are checked by default.
- Field Mappings (optional): use them only if your system cannot send Omnifox's standard format. Click Add and, in each row, type on the left the path of the value in your JSON (for example
data.user.id) and pick on the right the Omnifox field it fills. Details in Custom channel: field mapping. - Click Continue. If you entered an outgoing URL, Omnifox sends it a signed test message and expects a successful response (2xx status) within 5 seconds. If your system does not respond correctly, you will see the error and the channel is not saved until you fix it. If you left the outgoing URL empty, the channel is saved right away.
Tip: if your system is not ready to receive yet, create the channel without an outgoing URL, test incoming messages, and add the URL later by editing the channel.
4. Merge with existing contacts: when to turn it on
These two checkboxes decide what happens with the first message from a new contact ID:
- Off (recommended): every user of your system gets their own contact in Omnifox. If their phone number already belongs to another contact, the new one is created without a phone number so the two are not mixed up.
- Merge by phone: if a contact with that phone number already exists (for example, because they wrote to you on WhatsApp before), the user is linked to that contact.
- Merge by email: if there was no phone match, Omnifox looks for a contact with the same email.
Warning: with these options on, two different people who share a phone number or email (a family, an office, a shared inbox like info@) would end up in the same contact and the same conversation. Only turn them on if, in your system, each phone number or email belongs to a single person.
5. What happens once the channel is live
- Messages from your users arrive in the Inbox with text, images, video, audio or files.
- Everything works as in other channels: team assignment, the channel's AI agent, workflows and automations, tags and notifications.
- Your system can ask for a new conversation to go to a specific team or agent, and can update the contact's name, phone, email and custom fields.
- When someone replies, Omnifox sends the reply to your outgoing URL, stating who replied: a person, the AI agent or a workflow.
- Your system can report when your user received and read each reply, and the inbox shows the delivered and read ticks.
6. What the custom channel does not do
- It does not show a "typing…" indicator.
- It does not support editing or deleting messages, or reactions.
- It supports a single outgoing URL per channel.
- WhatsApp's 24-hour window does not apply: you can reply at any time.
7. Common issues
- An error about the webhook appears when you click Continue: your outgoing URL did not answer with a 2xx status within 5 seconds. Check that the address is correct and public, or leave it empty for now.
- No messages come in: confirm with your developer that they use the exact incoming URL and the current secret key (if you clicked Regenerate, the old one no longer works).
- Replies show in red as failed: the outgoing URL is missing, or your system is rejecting the requests.
- All messages land in the same contact: your system is sending the same contact ID for every user.
- A user showed up inside a contact that already existed: one of the Merge with existing contacts options is on.
Related articles
Related articles
-
WhatsApp (Meta) error codes: what they mean and what to do
A table of the most common Meta error codes when sending on WhatsApp (131026, 131047, 131049, 130497, 141006, 131031, 131056, 132000, 190, 368…) and how to fix each one.
-
How to connect Telegram
Connect a Telegram bot to your Omnifox inbox in minutes using BotFather.
-
Instagram and Facebook comments: reply and moderate from Omnifox
See and answer comments on your Facebook and Instagram posts and ads, publicly or privately, and set up automatic replies.
-
Sending and receiving videos on each channel: formats and size limits
Which videos you can send and receive on WhatsApp, Instagram, Messenger, Telegram, web chat and email, the real size limits, and what to do with a large video.
-
Move from WhatsApp QR to Coexistence or Cloud API
Once you're done testing with the QR code, move your number to the official connection: no caps, with templates and broadcasts, and no volume-based ban risk.