Panel apps: show your system inside the chat
Load your ERP, invoicing or any web system next to the chat and in the CRM, with the customer already identified by a signed token, and let it insert text, send messages, add notes and tags.
Panel apps let you show your own system (ERP, invoicing, orders, medical records, bookings…) inside Omnifox: next to the chat, in the contact sidebar, and in the CRM 360 profile. Your app receives who the customer is, which conversation is open and which agent is handling it, with a signed token your server can verify. It can also ask Omnifox to insert text in the reply, send a message, add an internal note or a tag.
Other platforms call this Dashboard Apps or sidebar plugins. It works with any web system: it does not need to come from a specific vendor.
What you need
- Permission to manage the account settings (owner or admin).
- A web page of yours served over HTTPS that can be shown inside an Omnifox iframe (see “Allow Omnifox to show your page”).
Step 1: try the demo app
- Go to Integrations → Panel apps and click New app.
- Click Use the demo app. The name, icon, URL and every action are filled in.
- Click Test in the inbox: you will see the app with a sample contact, the context it receives and a log of every message. In the preview, actions are simulated: nothing is sent or saved.
- Click Save. Copy the signing secret that appears: it is shown only once.
- Open any conversation in the Inbox: the app shows up in the contact sidebar. Try “Internal note” or “Add tag” and you will see the result right away.
When you are done testing, you can pause or delete it.
Step 2: add your own app
| Field | What it is for |
|---|---|
| Name and icon | What the agent sees in the panel header. The icon is an emoji. |
| App URL | Your page, with https://. Supports placeholders (below). The domain must be fixed. |
| Where it shows | Inbox (contact sidebar, next to the chat) and/or CRM (contact 360 profile). |
| Workspaces | All or only some. |
| Who sees it | All roles or only some (admin, supervisor, agent). Owners always see it. |
| Channels | All or only some (WhatsApp, Instagram, email…). Applies to the inbox only. |
| Panel height | Automatic (your app can adjust it) or fixed. |
| What the app can ask | The allowed actions (below). Sending messages is off by default. |
Change the order of the apps with the arrows in the list. Active / Paused hides an app without deleting it.
URL placeholders
They are replaced with the real value, URL-encoded. When there is no value (for example, there is no conversation in the CRM) they are left empty.
| Placeholder | Value |
|---|---|
{contact.id} {contact.name} {contact.phone} {contact.email} {contact.external_id} |
Contact data |
{contact.custom.<key>} |
A contact custom field, by its internal key (for example {contact.custom.tax_id}). Each contact uses its workspace's fields. Your account's fields show up as buttons while editing the URL |
{conversation.id} {channel.id} {channel.type} |
Open conversation and its channel (whatsapp, instagram, email…) |
{agent.id} {agent.email} {agent.name} |
Agent who is looking |
{org.id} {workspace.id} |
Your account and the workspace |
{locale} |
Agent language (es, en, pt) |
Example: https://erp.mycompany.com/omnifox?customer={contact.phone}&lang={locale}
With a custom field: https://erp.mycompany.com/omnifox?tax_id={contact.custom.tax_id}&name={contact.name}
Omnifox always appends the omnifox_token parameter.
Do not rely on placeholders to decide what data to show: anyone can type a URL. Use the
omnifox_token, which is signed.
Step 3: verify the token on your server
omnifox_token is a JWT HS256 signed with your app secret. It expires after 10 minutes; Omnifox renews it while the panel is open and on every conversation change.
Claims:
| Claim | Content |
|---|---|
aud |
panel_app:<app id> |
iss |
https://omnifox.io |
iat, nbf, exp, jti |
Issued at, not before, expiry and unique id |
org_id, workspace_id |
Account and workspace |
agent_id, agent_email |
Agent |
contact_id, conversation_id, channel_type |
Contact, conversation and channel (may be null) |
location |
inbox or crm |
locale |
Agent language |
contact_custom |
Contact custom fields ({"tax_id": "0991234567001", …}; only if the contact has fields; up to 30, each value cut to 200 characters) |
Always check: the signature, that alg is HS256, that it has not expired (exp) and that aud is your app’s.
PHP (with firebase/php-jwt):
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
$secret = getenv('OMNIFOX_PANEL_SECRET'); // the app secret
JWT::$leeway = 30;
$claims = (array) JWT::decode($_GET['omnifox_token'] ?? '', new Key($secret, 'HS256'));
if (($claims['aud'] ?? null) !== 'panel_app:12') { http_response_code(403); exit; }
$contactId = $claims['contact_id'];
$agent = $claims['agent_email'];
Node.js (with jsonwebtoken):
const jwt = require('jsonwebtoken');
app.get('/omnifox', (req, res) => {
try {
const claims = jwt.verify(req.query.omnifox_token, process.env.OMNIFOX_PANEL_SECRET, {
algorithms: ['HS256'],
audience: 'panel_app:12',
clockTolerance: 30,
});
// claims.contact_id, claims.conversation_id, claims.agent_email…
res.render('panel', { claims });
} catch (e) {
res.status(403).send('Invalid token');
}
});
If your page is JavaScript only (no server of its own), send the token to your API on every request and verify it there. Never put the secret in the browser.
If the secret leaks, use Regenerate secret in the list: the old one stops working immediately.
Step 4: talk to Omnifox from your page (postMessage)
Load the Omnifox kit in your page:
<script src="https://app.omnifox.io/panel-apps/sdk.js"></script>
<script>
OmnifoxPanel.onContext(function (ctx) {
// Called on load and every time the agent switches conversation.
console.log(ctx.contact, ctx.conversation, ctx.agent, ctx.token);
});
document.querySelector('#use').onclick = function () {
OmnifoxPanel.insertText('Your order #123 ships today.')
.then(function () { OmnifoxPanel.toast('Text ready in the reply', 'success'); })
.catch(function (err) { console.warn(err.code, err.message); });
};
OmnifoxPanel.autoHeight(); // keeps the panel height in sync with the content
</script>
Kit functions (all return a promise):
| Function | Message | What it does |
|---|---|---|
onContext(cb) |
omnifox:context |
Receives the context now and on every change |
requestContext() |
omnifox:request_context |
Asks for the context again |
insertText(text) |
omnifox:insert_text |
Puts the text in the agent’s reply. It does not send it |
sendMessage(text) |
omnifox:send_message |
Sends a message to the customer (with agent confirmation, if enabled) |
addNote(text) |
omnifox:add_note |
Internal note in the conversation (in the CRM, a note on the profile) |
addTag(name) |
omnifox:add_tag |
Tag on the contact; created if it does not exist |
toast(text, kind) |
omnifox:toast |
Short notice to the agent (info, success, error) |
openUrl(url) |
omnifox:open_url |
Opens an http/https link in another tab |
setHeight(px) |
omnifox:set_height |
Changes the height (automatic height only) |
If you prefer not to use the kit, the protocol is simple:
- Your page posts to the parent:
{ type: 'omnifox:<action>', id: '<your id>', payload: { ... } }withwindow.parent.postMessage(message, '*'). - Omnifox answers:
{ type: 'omnifox:result', id: '<your id>', ok: true, data: { ... } }or{ ok: false, error: { code, message } }. - Omnifox sends the context:
{ type: 'omnifox:context', payload: { app, location, locale, org, workspace, agent, contact, conversation, channel, allowed_actions, token, token_expires_at } }.contact.customholds the contact's custom fields (key → value). - When your page is ready, post
{ type: 'omnifox:ready' }and you will receive the context.
Common error codes: action_not_allowed (the action is not enabled for the app or the agent lacks permission), cancelled (the agent did not confirm the message), conversation_closed, text_required, tag_invalid.
Security
- Omnifox only accepts messages that come from your app’s iframe and from the domain of the configured URL. If your page navigates to another domain, Omnifox stops listening to it.
- Each action must be enabled for the app and the agent must have permission to do it. Omnifox checks again on the server.
- The conversation and contact an action applies to are always the ones the agent has open; your page cannot pick others.
- Everything that changes data (messages, notes, tags) and every configuration change is recorded in the audit log.
- Apps and their secrets belong to your account: no other Omnifox account can see or use them.
- The iframe is loaded with
sandbox(scripts, forms, popups and downloads allowed) and without sending the Omnifox path as referrer.
Allow Omnifox to show your page
If your system blocks iframes, the panel will be blank. Check on your server:
- Do not send
X-Frame-Options: DENYorSAMEORIGINon that page. - If you use Content-Security-Policy, add:
frame-ancestors https://app.omnifox.io - If your page uses session cookies, mark them
SameSite=None; Secure(inside a cross-site iframe, browsers do not sendLaxcookies). Better yet: identify the user with theomnifox_tokenand do not depend on cookies.
FAQ
Does it cost extra? For now, panel apps are included in every plan.
How many apps can I have? As many as you need. With several, each one is a collapsible section; the agent can open or close each one and Omnifox remembers it.
The panel is blank. Open the demo app: if it works, the problem is in your page headers (see above). Also check the URL is https://.
My app does not receive the context. Messages only arrive if your page is on the same domain you set in the app URL (for example, if it redirects from mycompany.com to www.mycompany.com, configure the URL with www).
sendMessage returns cancelled. The agent clicked Cancel in the confirmation. You can turn confirmation off for the app, but we recommend keeping it.
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.