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.

Nov 05, 2026

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

  1. Ve a Integraciones → Apps del panel y pulsa Nueva app.
  2. Pulsa Usar la app de demostración. Se rellenan el nombre, el ícono, la URL y todas las acciones.
  3. 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.
  4. Pulsa Guardar. Copia el secreto de firma que aparece: se muestra una sola vez.
  5. 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: { ... } } con window.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.custom trae 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: DENY ni SAMEORIGIN en 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 cookies Lax). Mejor aún: identifica al usuario con el omnifox_token y 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.

¿Te fue útil?

Artículos relacionados

Escríbenos por WhatsApp