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.
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
- Vá em Integrações → Apps do painel e clique em Novo app.
- Clique em Usar o app de demonstração. Nome, ícone, URL e todas as ações são preenchidos.
- 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.
- Clique em Salvar. Copie o segredo de assinatura que aparece: ele é mostrado uma única vez.
- 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: { ... } }comwindow.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.customtraz 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: DENYnemSAMEORIGINnessa 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 cookiesLax). Melhor ainda: identifique o usuário com oomnifox_tokene 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.
Artigos relacionados
-
Como conectar integrações e apps externos
Conecte o Omnifox às suas ferramentas favoritas a partir do catálogo de integrações em poucos passos.
-
Integrar o Omnifox com Azur, Siigo, Alegra, QuickBooks ou outro sistema contábil ou ERP
O Omnifox não tem hoje um conector nativo com sistemas contábeis ou ERP. Veja como fazer essa conexão mesmo assim com fluxos de trabalho, o nó HTTP, n8n, Make, Zapier ou a API, com exemplos.
-
Guia completo de integrações e API
Integrações e API a fundo, em 30 capítulos: chaves de API, chamadas reais, webhooks assinados, n8n, MCP e SDKs, tudo funcionando de verdade.
-
Gerar e usar API keys e webhooks
Crie chaves de API para acessar o Omnifox por código e configure webhooks para receber eventos em tempo real.
-
Introdução às integrações (webhook / OAuth / chave de API)
Conecte o Omnifox às suas outras ferramentas: o que está disponível hoje, o que chega em breve e quando usar um webhook, uma conexão OAuth ou uma chave de API.