Apps del panel: muestra tu sistema dentro del chat
Carga tu ERP, facturación o cualquier sistema web junto al chat y en el CRM, con el cliente ya identificado por un token firmado, y deja que inserte texto, envíe mensajes, agregue notas y etiquetas.
Las Apps del panel te permiten mostrar tu propio sistema (ERP, facturación, pedidos, historial clínico, reservas…) dentro de Omnifox: al lado del chat, en la barra lateral del contacto, y en la ficha 360 del CRM. Tu app recibe quién es el cliente, qué conversación está abierta y qué agente la atiende, con un token firmado que tu servidor puede verificar. Y puede pedirle a Omnifox que inserte texto en la respuesta, envíe un mensaje, agregue una nota interna o una etiqueta.
Es lo mismo que en otras plataformas se llama Dashboard Apps o plugins de barra lateral. Funciona con cualquier sistema web: no hace falta que sea de un proveedor en particular.
Qué necesitas
- Permiso para administrar la configuración de la cuenta (dueño o administrador).
- Una página web tuya servida por HTTPS que se pueda mostrar dentro de un iframe de Omnifox (ver «Permite que Omnifox muestre tu página»).
Paso 1: prueba la app de demostración
- Ve a Integraciones → Apps del panel y pulsa Nueva app.
- Pulsa Usar la app de demostración. Se rellenan el nombre, el ícono, la URL y todas las acciones.
- Pulsa Probar en la bandeja: verás la app con un contacto de ejemplo, el contexto que recibe y un registro de cada mensaje. En la vista previa las acciones se simulan: no se envía ni se guarda nada.
- Pulsa Guardar. Copia el secreto de firma que aparece: se muestra una sola vez.
- Abre cualquier conversación en la Bandeja: la app aparece en la barra lateral del contacto. Prueba «Nota interna» o «Agregar etiqueta» y verás el resultado al instante.
Cuando termines de probar, puedes pausarla o eliminarla.
Paso 2: agrega tu propia app
| Campo | Para qué sirve |
|---|---|
| Nombre e ícono | Lo que ve el agente en la cabecera del panel. El ícono es un emoji. |
| URL de la app | Tu página, con https://. Admite comodines (abajo). El dominio debe ser fijo. |
| Dónde se muestra | Bandeja (barra lateral del contacto, junto al chat) y/o CRM (ficha 360 del contacto). |
| Espacios de trabajo | Todos o solo algunos. |
| Quién la ve | Todos los roles o solo algunos (administrador, supervisor, agente). Los dueños siempre la ven. |
| Canales | Todos o solo algunos (WhatsApp, Instagram, correo…). Solo aplica en la bandeja. |
| Alto del panel | Automático (tu app puede ajustarlo) o fijo. |
| Qué puede pedirle la app | Las acciones permitidas (abajo). Enviar mensajes viene apagado. |
El orden de las apps en el panel se cambia con las flechas de la lista. Activa / Pausada la oculta sin borrarla.
Comodines de la URL
Se reemplazan por el valor real, codificado para URL. Si no hay valor (por ejemplo, en el CRM no hay conversación), quedan vacíos.
| Comodín | Valor |
|---|---|
{contact.id} {contact.name} {contact.phone} {contact.email} {contact.external_id} |
Datos del contacto |
{contact.custom.<clave>} |
Un campo personalizado del contacto, por su clave interna (por ejemplo {contact.custom.ruc}). Cada contacto usa los campos de su espacio de trabajo. Los de tu cuenta aparecen como botones al editar la URL |
{conversation.id} {channel.id} {channel.type} |
Conversación abierta y su canal (whatsapp, instagram, email…) |
{agent.id} {agent.email} {agent.name} |
Agente que está mirando |
{org.id} {workspace.id} |
Tu cuenta y el espacio de trabajo |
{locale} |
Idioma del agente (es, en, pt) |
Ejemplo: https://erp.miempresa.com/omnifox?cliente={contact.phone}&lang={locale}
Con un campo personalizado: https://erp.miempresa.com/omnifox?ruc={contact.custom.ruc}&nombre={contact.name}
Omnifox agrega siempre el parámetro omnifox_token al final.
No confíes en los comodines para decidir qué datos mostrar: cualquiera puede escribir una URL. Usa el
omnifox_token, que va firmado.
Paso 3: verifica el token en tu servidor
omnifox_token es un JWT HS256 firmado con el secreto de tu app. Vence a los 10 minutos; Omnifox lo renueva solo mientras el panel está abierto y en cada cambio de conversación.
Datos que trae (claims):
| Claim | Contenido |
|---|---|
aud |
panel_app:<id de la app> |
iss |
https://omnifox.io |
iat, nbf, exp, jti |
Emisión, validez, vencimiento e identificador único |
org_id, workspace_id |
Cuenta y espacio de trabajo |
agent_id, agent_email |
Agente |
contact_id, conversation_id, channel_type |
Contacto, conversación y canal (pueden ser null) |
location |
inbox o crm |
locale |
Idioma del agente |
contact_custom |
Campos personalizados del contacto ({"ruc": "0991234567001", …}; solo si el contacto tiene campos; hasta 30, cada valor recortado a 200 caracteres) |
Comprueba siempre: la firma, que alg sea HS256, que no esté vencido (exp) y que aud sea el de tu app.
PHP (con firebase/php-jwt):
use Firebase\JWT\JWT;
use Firebase\JWT\Key;
$secret = getenv('OMNIFOX_PANEL_SECRET'); // el secreto de la app
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; }
$contactoId = $claims['contact_id'];
$agente = $claims['agent_email'];
Node.js (con 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('Token inválido');
}
});
Si tu página es solo JavaScript (sin servidor propio), manda el token a tu API en cada petición y verifícalo allí. Nunca pongas el secreto en el navegador.
Si se filtra el secreto, usa Regenerar secreto en la lista: el anterior deja de servir al instante.
Paso 4: habla con Omnifox desde tu página (postMessage)
Carga el kit de Omnifox en tu página:
<script src="https://app.omnifox.io/panel-apps/sdk.js"></script>
<script>
OmnifoxPanel.onContext(function (ctx) {
// Se llama al cargar y cada vez que el agente cambia de conversación.
console.log(ctx.contact, ctx.conversation, ctx.agent, ctx.token);
});
document.querySelector('#usar').onclick = function () {
OmnifoxPanel.insertText('Su pedido #123 sale hoy.')
.then(function () { OmnifoxPanel.toast('Texto listo en la respuesta', 'success'); })
.catch(function (err) { console.warn(err.code, err.message); });
};
OmnifoxPanel.autoHeight(); // ajusta el alto del panel al contenido
</script>
Funciones del kit (todas devuelven una promesa):
| Función | Mensaje | Qué hace |
|---|---|---|
onContext(cb) |
omnifox:context |
Recibe el contexto ahora y en cada cambio |
requestContext() |
omnifox:request_context |
Pide el contexto otra vez |
insertText(texto) |
omnifox:insert_text |
Deja el texto en la respuesta del agente. No lo envía |
sendMessage(texto) |
omnifox:send_message |
Envía un mensaje al cliente (con confirmación del agente, si está activada) |
addNote(texto) |
omnifox:add_note |
Nota interna en la conversación (en el CRM, nota en la ficha) |
addTag(nombre) |
omnifox:add_tag |
Etiqueta al contacto; si no existe, se crea |
toast(texto, tipo) |
omnifox:toast |
Aviso corto al agente (info, success, error) |
openUrl(url) |
omnifox:open_url |
Abre un enlace http/https en otra pestaña |
setHeight(px) |
omnifox:set_height |
Cambia el alto (solo con alto automático) |
Si prefieres no usar el kit, el protocolo es simple:
- Tu página manda al padre:
{ type: 'omnifox:<acción>', id: '<tu id>', payload: { ... } }conwindow.parent.postMessage(mensaje, '*'). - Omnifox responde:
{ type: 'omnifox:result', id: '<tu id>', ok: true, data: { ... } }o{ ok: false, error: { code, message } }. - Omnifox manda el contexto:
{ type: 'omnifox:context', payload: { app, location, locale, org, workspace, agent, contact, conversation, channel, allowed_actions, token, token_expires_at } }.contact.customtrae los campos personalizados del contacto (clave → valor). - Al estar lista, manda
{ type: 'omnifox:ready' }y recibirás el contexto.
Códigos de error frecuentes: action_not_allowed (la acción no está activada en la app o el agente no tiene permiso), cancelled (el agente no confirmó el envío), conversation_closed, text_required, tag_invalid.
Seguridad
- Omnifox solo acepta mensajes que vienen del iframe de tu app y del dominio de la URL configurada. Si tu página navega a otro dominio, Omnifox deja de escucharla.
- Cada acción tiene que estar activada en la app y además el agente tiene que tener permiso para hacerla. Omnifox lo vuelve a comprobar en el servidor.
- La conversación y el contacto sobre los que se actúa son siempre los que el agente tiene abiertos; tu página no puede elegir otros.
- Todo lo que cambia datos (mensajes, notas, etiquetas) y cada cambio de configuración queda en el registro de auditoría.
- Las apps y sus secretos son de tu cuenta: ninguna otra cuenta de Omnifox puede verlas ni usarlas.
- El iframe se carga con
sandbox(scripts, formularios, ventanas emergentes y descargas permitidas) y sin enviar la ruta de Omnifox como referente.
Permite que Omnifox muestre tu página
Si tu sistema bloquea iframes, el panel se verá en blanco. Revisa en tu servidor:
- No envíes
X-Frame-Options: DENYniSAMEORIGINen esa página. - Si usas Content-Security-Policy, agrega:
frame-ancestors https://app.omnifox.io - Si tu página usa cookies de sesión, márcalas con
SameSite=None; Secure(dentro de un iframe de otro dominio, el navegador no envía las cookiesLax). Mejor aún: identifica al usuario con elomnifox_tokeny no dependas de cookies.
Preguntas frecuentes
¿Tiene costo? Por ahora, las Apps del panel están incluidas en todos los planes.
¿Cuántas apps puedo tener? Las que necesites. Si muestras varias, cada una es una sección plegable; el agente puede abrir o cerrar cada una y Omnifox lo recuerda.
El panel aparece en blanco. Abre la app de demostración: si ella funciona, el problema está en los encabezados de tu página (ver arriba). Revisa también que la URL sea https://.
Mi app no recibe el contexto. El mensaje solo llega si tu página está en el mismo dominio que pusiste en la URL de la app (por ejemplo, si redirige de miempresa.com a www.miempresa.com, configura la URL con www).
sendMessage devuelve cancelled. El agente pulsó Cancelar en la confirmación. Puedes quitar la confirmación en la app, pero lo recomendable es dejarla.
Artículos relacionados
-
Cómo conectar integraciones y apps externas
Conecta Omnifox con tus herramientas favoritas desde el catálogo de integraciones en pocos pasos.
-
Guía completa de integraciones y API
Integraciones y API a fondo, en 30 capítulos: claves API, llamadas reales, webhooks firmados, n8n, MCP y SDK, todo funcionando de verdad.
-
Integrar Omnifox con Azur, Siigo, Alegra, QuickBooks u otro sistema contable o ERP
Omnifox no tiene hoy un conector nativo con sistemas contables o ERP. Te explicamos cómo conectarlos igual con workflows, el nodo HTTP, n8n, Make, Zapier o la API, con ejemplos.
-
Generar y usar API keys y webhooks
Crea claves de API para acceder a Omnifox por código y configura webhooks para recibir eventos en tiempo real.
-
Introducción a las integraciones (webhook / OAuth / API key)
Conecta Omnifox con tus otras herramientas: qué está disponible hoy, qué llega pronto y cuándo usar un webhook, una conexión OAuth o una clave de API.