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.

Jul 11, 2026

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

  1. How it works
  2. Before you start
  3. Create the channel step by step
  4. Merge with existing contacts: when to turn it on
  5. What happens once the channel is live
  6. What the custom channel does not do
  7. 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

  1. Go to Settings → Channels → Connect New Channel and choose Custom Channel.
  2. Enter the Channel Name.
  3. 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.
  4. 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.
  5. 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.
  6. Under Merge with existing contacts, leave Merge by phone and Merge by email off unless you are sure you need them (see section 4).
  7. 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.
  8. 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.
  9. 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

Was this helpful?

Related articles

Message us on WhatsApp