Mini-apps

​

Onde fica no painel

• Cadastro: Configurações → Apps (admin e editor).
• Onde o app aparece, conforme o posicionamento escolhido:

​

Como configurar

​

O token do app

​

Como funciona por trás

1. A Zatten abre https://SEU-APP/?data=<token> no iframe, ocupando 100% do espaço.
2. O data é um JWE compacto (alg: dir, enc: A256GCM), criptografado com o token do app. A chave é o token decodificado de base64url (32 bytes).
3. Seu app descriptografa, valida o exp (o token vale 24 horas) e cria a sua própria sessão. O data é só o aperto de mão inicial.
4. No Painel do chat, trocar de conversa recarrega o app com o lead novo. Trocar o tema do painel também recarrega.

​

Ler o contexto (Node, com a biblioteca jose)

import { jwtDecrypt } from 'jose' // npm i jose

const key = Buffer.from(process.env.ZATTEN_MINIAPP_SECRET!, 'base64url')

export async function readZattenData(data: string) {
  const { payload } = await jwtDecrypt(data, key) // confere integridade e exp
  return payload
}

import { createDecipheriv } from 'crypto'

export function readZattenData(data: string, secret: string) {
  const key = Buffer.from(secret, 'base64url')
  const [header, , iv, ct, tag] = data.split('.')
  const d = createDecipheriv('aes-256-gcm', key, Buffer.from(iv, 'base64url'))
  d.setAAD(Buffer.from(header))
  d.setAuthTag(Buffer.from(tag, 'base64url'))
  const json = Buffer.concat([
    d.update(Buffer.from(ct, 'base64url')),
    d.final() // lança se o token foi adulterado ou a chave está errada
  ]).toString()
  const claims = JSON.parse(json)
  if (!claims.exp || claims.exp * 1000 < Date.now()) throw new Error('expirado')
  return claims
}

​

O que vem no token

{
  "tenant_id": "e6f3…",
  "tenant_name": "Agência X",
  "user_id": "4486…",
  "user_email": "ana@agencia.com",
  "user_role": "editor",
  "attendant_id": "de5f…",
  "theme": "light",
  "lead": {
    "id": "d4ab…",
    "name": "João",
    "wa_id": "5511999998888",
    "thread_id": "zt-thread-…",
    "tags": [{ "id": "d6f8…", "name": "VIP" }],
    "kanban": { "id": "a1…", "name": "Novo Lead" },
    "properties": [{ "label": "CPF", "value": "123" }]
  },
  "custom": { "env": "prod" },
  "iat": 1782525769,
  "exp": 1782612169
}

​

Pelo MCP

​

Armadilhas

• Não confie no user_role para autorizar. Use como dica e faça a sua própria autorização. Isole os dados por tenant_id e attendant_id.
• Login por cookie em outro domínio falha. No iframe, o navegador trata o app como terceiro. Hospede o app num subdomínio do domínio do white-label (ex.: estoque.cliente.com ao lado de cliente.com).
• Token exposto. Quem tem o token do app lê e forja o contexto. Nunca no front-end nem no repositório.
• Regenerar derruba o app até você atualizar a variável de ambiente.
• Painel do chat é estreito. Sem menu lateral, sem tabela larga, sem duas colunas. Nada de position: fixed contando com a janela inteira.
• O app recarrega ao reabrir, trocar de lead ou de tema. Mantenha o carregamento rápido.

​

Perguntas frequentes

​

Para saber mais

• White-label
• Usuários, papéis e permissões
• A API: visão geral
• JWE (RFC 7516): https://www.rfc-editor.org/rfc/rfc7516
• Biblioteca jose: https://github.com/panva/jose
• Termos para buscar: “JWE compact”, “A256GCM”, “iframe third-party cookies”, “jwtDecrypt”.