Apps do painel: mostre o seu sistema dentro do chat

Carregue o seu ERP, faturamento ou qualquer sistema web ao lado do chat e no CRM, com o cliente já identificado por um token assinado, e deixe-o inserir texto, enviar mensagens, adicionar notas e etiquetas.

Nov 05, 2026

Os Apps do painel permitem mostrar o seu próprio sistema (ERP, faturamento, pedidos, prontuário, agendamentos…) dentro do Omnifox: ao lado do chat, na barra lateral do contato, e na ficha 360 do CRM. O seu app recebe quem é o cliente, qual conversa está aberta e qual agente está atendendo, com um token assinado que o seu servidor pode verificar. E pode pedir ao Omnifox que insira texto na resposta, envie uma mensagem, adicione uma nota interna ou uma etiqueta.

Em outras plataformas isso se chama Dashboard Apps ou plugins de barra lateral. Funciona com qualquer sistema web: não precisa ser de um fornecedor específico.

O que você precisa

  • Permissão para administrar as configurações da conta (dono ou administrador).
  • Uma página web sua servida por HTTPS que possa ser exibida dentro de um iframe do Omnifox (veja «Permita que o Omnifox mostre a sua página»).

Passo 1: teste o app de demonstração

  1. Vá em Integrações → Apps do painel e clique em Novo app.
  2. Clique em Usar o app de demonstração. Nome, ícone, URL e todas as ações são preenchidos.
  3. Clique em Testar na caixa de entrada: você verá o app com um contato de exemplo, o contexto que ele recebe e um registro de cada mensagem. Na pré-visualização as ações são simuladas: nada é enviado nem salvo.
  4. Clique em Salvar. Copie o segredo de assinatura que aparece: ele é mostrado uma única vez.
  5. Abra qualquer conversa na Caixa de entrada: o app aparece na barra lateral do contato. Teste «Nota interna» ou «Adicionar etiqueta» e verá o resultado na hora.

Quando terminar de testar, você pode pausá-lo ou excluí-lo.

Passo 2: adicione o seu próprio app

Campo Para que serve
Nome e ícone O que o agente vê no cabeçalho do painel. O ícone é um emoji.
URL do app A sua página, com https://. Aceita curingas (abaixo). O domínio deve ser fixo.
Onde aparece Caixa de entrada (barra lateral do contato, ao lado do chat) e/ou CRM (ficha 360 do contato).
Espaços de trabalho Todos ou só alguns.
Quem vê Todas as funções ou só algumas (administrador, supervisor, agente). Os donos sempre veem.
Canais Todos ou só alguns (WhatsApp, Instagram, e-mail…). Vale só na caixa de entrada.
Altura do painel Automática (o seu app pode ajustá-la) ou fixa.
O que o app pode pedir As ações permitidas (abaixo). Enviar mensagens vem desligado.

A ordem dos apps no painel muda com as setas da lista. Ativo / Pausado oculta o app sem excluí-lo.

Curingas da URL

São substituídos pelo valor real, codificado para URL. Quando não há valor (por exemplo, no CRM não há conversa), ficam vazios.

Curinga Valor
{contact.id} {contact.name} {contact.phone} {contact.email} {contact.external_id} Dados do contato
{contact.custom.<chave>} Um campo personalizado do contato, pela chave interna (por exemplo {contact.custom.cnpj}). Cada contato usa os campos do seu espaço de trabalho. Os da sua conta aparecem como botões ao editar a URL
{conversation.id} {channel.id} {channel.type} Conversa aberta e o seu canal (whatsapp, instagram, email…)
{agent.id} {agent.email} {agent.name} Agente que está olhando
{org.id} {workspace.id} A sua conta e o espaço de trabalho
{locale} Idioma do agente (es, en, pt)

Exemplo: https://erp.minhaempresa.com/omnifox?cliente={contact.phone}&lang={locale}

Com um campo personalizado: https://erp.minhaempresa.com/omnifox?cnpj={contact.custom.cnpj}&nome={contact.name}

O Omnifox sempre adiciona o parâmetro omnifox_token no final.

Não confie nos curingas para decidir quais dados mostrar: qualquer pessoa pode digitar uma URL. Use o omnifox_token, que é assinado.

Passo 3: verifique o token no seu servidor

omnifox_token é um JWT HS256 assinado com o segredo do seu app. Vence em 10 minutos; o Omnifox o renova enquanto o painel estiver aberto e a cada troca de conversa.

Dados (claims):

Claim Conteúdo
aud panel_app:<id do app>
iss https://omnifox.io
iat, nbf, exp, jti Emissão, validade, vencimento e identificador único
org_id, workspace_id Conta e espaço de trabalho
agent_id, agent_email Agente
contact_id, conversation_id, channel_type Contato, conversa e canal (podem ser null)
location inbox ou crm
locale Idioma do agente
contact_custom Campos personalizados do contato ({"cnpj": "12345678000190", …}; só se o contato tiver campos; até 30, cada valor cortado em 200 caracteres)

Verifique sempre: a assinatura, que alg seja HS256, que não esteja vencido (exp) e que aud seja o do seu app.

PHP (com firebase/php-jwt):

use Firebase\JWT\JWT;
use Firebase\JWT\Key;

$secret = getenv('OMNIFOX_PANEL_SECRET'); // o segredo do 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; }

$contatoId = $claims['contact_id'];
$agente = $claims['agent_email'];

Node.js (com 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');
  }
});

Se a sua página é só JavaScript (sem servidor próprio), envie o token para a sua API em cada requisição e verifique lá. Nunca coloque o segredo no navegador.

Se o segredo vazar, use Gerar novo segredo na lista: o anterior deixa de funcionar na hora.

Passo 4: converse com o Omnifox a partir da sua página (postMessage)

Carregue o kit do Omnifox na sua página:

<script src="https://app.omnifox.io/panel-apps/sdk.js"></script>
<script>
  OmnifoxPanel.onContext(function (ctx) {
    // Chamado ao carregar e cada vez que o agente troca de conversa.
    console.log(ctx.contact, ctx.conversation, ctx.agent, ctx.token);
  });

  document.querySelector('#usar').onclick = function () {
    OmnifoxPanel.insertText('O seu pedido #123 sai hoje.')
      .then(function () { OmnifoxPanel.toast('Texto pronto na resposta', 'success'); })
      .catch(function (err) { console.warn(err.code, err.message); });
  };

  OmnifoxPanel.autoHeight(); // ajusta a altura do painel ao conteúdo
</script>

Funções do kit (todas retornam uma promessa):

Função Mensagem O que faz
onContext(cb) omnifox:context Recebe o contexto agora e a cada mudança
requestContext() omnifox:request_context Pede o contexto de novo
insertText(texto) omnifox:insert_text Coloca o texto na resposta do agente. Não envia
sendMessage(texto) omnifox:send_message Envia uma mensagem ao cliente (com confirmação do agente, se ativada)
addNote(texto) omnifox:add_note Nota interna na conversa (no CRM, nota na ficha)
addTag(nome) omnifox:add_tag Etiqueta no contato; se não existir, é criada
toast(texto, tipo) omnifox:toast Aviso curto ao agente (info, success, error)
openUrl(url) omnifox:open_url Abre um link http/https em outra aba
setHeight(px) omnifox:set_height Muda a altura (só com altura automática)

Se preferir não usar o kit, o protocolo é simples:

  • A sua página envia ao pai: { type: 'omnifox:<ação>', id: '<seu id>', payload: { ... } } com window.parent.postMessage(mensagem, '*').
  • O Omnifox responde: { type: 'omnifox:result', id: '<seu id>', ok: true, data: { ... } } ou { ok: false, error: { code, message } }.
  • O Omnifox envia o contexto: { type: 'omnifox:context', payload: { app, location, locale, org, workspace, agent, contact, conversation, channel, allowed_actions, token, token_expires_at } }. contact.custom traz os campos personalizados do contato (chave → valor).
  • Quando a página estiver pronta, envie { type: 'omnifox:ready' } e você receberá o contexto.

Códigos de erro frequentes: action_not_allowed (a ação não está ativada no app ou o agente não tem permissão), cancelled (o agente não confirmou o envio), conversation_closed, text_required, tag_invalid.

Segurança

  • O Omnifox só aceita mensagens que vêm do iframe do seu app e do domínio da URL configurada. Se a sua página navegar para outro domínio, o Omnifox deixa de ouvi-la.
  • Cada ação precisa estar ativada no app e o agente precisa ter permissão para fazê-la. O Omnifox confere de novo no servidor.
  • A conversa e o contato em que a ação é feita são sempre os que o agente tem abertos; a sua página não pode escolher outros.
  • Tudo o que altera dados (mensagens, notas, etiquetas) e cada mudança de configuração fica no registro de auditoria.
  • Os apps e os seus segredos são da sua conta: nenhuma outra conta do Omnifox pode vê-los nem usá-los.
  • O iframe é carregado com sandbox (scripts, formulários, pop-ups e downloads permitidos) e sem enviar o caminho do Omnifox como referência.

Permita que o Omnifox mostre a sua página

Se o seu sistema bloqueia iframes, o painel fica em branco. Confira no seu servidor:

  • Não envie X-Frame-Options: DENY nem SAMEORIGIN nessa página.
  • Se usa Content-Security-Policy, adicione: frame-ancestors https://app.omnifox.io
  • Se a sua página usa cookies de sessão, marque-os com SameSite=None; Secure (dentro de um iframe de outro domínio, o navegador não envia cookies Lax). Melhor ainda: identifique o usuário com o omnifox_token e não dependa de cookies.

Perguntas frequentes

Tem custo? Por enquanto, os Apps do painel estão incluídos em todos os planos.

Quantos apps posso ter? Quantos precisar. Com vários, cada um é uma seção recolhível; o agente pode abrir ou fechar cada uma e o Omnifox lembra.

O painel aparece em branco. Abra o app de demonstração: se ele funcionar, o problema está nos cabeçalhos da sua página (veja acima). Confira também que a URL seja https://.

O meu app não recebe o contexto. A mensagem só chega se a sua página estiver no mesmo domínio que você colocou na URL do app (por exemplo, se redireciona de minhaempresa.com para www.minhaempresa.com, configure a URL com www).

sendMessage retorna cancelled. O agente clicou em Cancelar na confirmação. Você pode desligar a confirmação no app, mas o recomendado é mantê-la.

Isso foi útil?

Artigos relacionados

Fale conosco no WhatsApp