Ações personalizadas (botões no lead)

​

Onde fica no painel

• Configurar: Automações → Ações personalizadas. Admin e editor.
• Usar: os botões aparecem na seção Ações do painel do lead no chat e no modal do lead no Kanban. Qualquer usuário com acesso ao projeto pode clicar.

​

Como configurar

​

Variáveis

​

Como funciona por trás

​

A chamada

• Sai dos servidores da Zatten, não do navegador. A URL e os headers nunca chegam ao navegador de quem clica.
• Com corpo (POST, PUT, PATCH): Content-Type: application/json.
• Tempo limite: 10 segundos. Sem nova tentativa.
• Não há assinatura. Para autenticar, use um header (por exemplo Authorization).

​

O corpo

{ "telefone": "5511999998888", "etapa": "Orçamento enviado", "cpf": "12345678900" }

{
  "action": { "id": "9a8b7c6d-0000-4000-8000-000000000010", "name": "Criar pedido no ERP" },
  "triggered_by": {
    "user_id": "u5e7r000-0000-4000-8000-000000000004",
    "email": "ana@agencia.com",
    "role": "editor"
  },
  "tenant_id": "a1b2c3d4-0000-4000-8000-000000000002",
  "attendant_id": "p40j3t00-0000-4000-8000-000000000006",
  "lead": {
    "id": "6f1c2b9e-3a4d-4c55-9a77-0d2e1f3b4c5d",
    "name": "Maria Souza",
    "wa_id": "5511999998888",
    "thread_id": "zt_8d7c6b5a",
    "tags": [{ "id": "b2c1d0e9-0000-4000-8000-000000000001", "name": "Clareamento" }],
    "kanban": { "id": "c0l00000-0000-4000-8000-000000000009", "name": "Orçamento enviado" },
    "properties": [
      { "slug": "cidade", "label": "Cidade", "value": "Campinas" }
    ]
  },
  "triggered_at": "2026-10-06T14:20:11.512Z"
}

​

Como o endpoint deve responder

​

Pelo MCP

• Identificado por name. O estado é is_active (boolean), não status.
• Sem webhook_url, a ação nasce pendente: sem endereço, desligada e com o selo Pendente na lista. Só liga com endereço. Importar um JSON ou duplicar um projeto leva o endereço e os headers preenchidos, como vieram da origem: confira se eles servem ao projeto novo.
• webhook_url, headers, query_params e body_params vazios não gravam por cima dos atuais.
• get_template traz URL e headers preenchidos, inclusive tokens. Nunca mostre esses valores ao cliente.

​

Armadilhas

• Variável no header não funciona. Bearer {{lead.id}} vai literalmente para o header. Coloque dados do lead na URL ou no corpo.
• Tudo vira texto. Com parâmetros no corpo, "valor": "450" chega como texto, não número. Converta no endpoint.
• Definir um parâmetro no corpo troca o payload inteiro. Quem dependia do payload padrão para de receber lead, triggered_by e o resto.
• GET e DELETE não levam corpo. Use parâmetros na URL.
• URL com http:// é recusada no painel.
• 10 segundos e acabou. Processo lento aparece como erro para quem clicou, mesmo que tenha dado certo depois. Responda rápido.
• Clique duplo, chamada dupla. Não há proteção contra dois cliques seguidos em momentos diferentes. Para ações que não podem se repetir (cobrança), ligue Pedir confirmação e trate repetição no endpoint (por exemplo, pelo lead.id e pela action.id).

​

Perguntas frequentes

​

Para saber mais

• Visão geral das automações
• Webhooks de eventos: para avisar um sistema sem clique.
• Tools HTTP do agente
• Propriedades: o slug usado em {{lead.property.<slug>}}.
• Termos para buscar: “webhook action button”, “HTTP request Authorization header Bearer”, “Lucide icons”.