#Como aplicar tags a partir de eventos do meu próprio sistema?

Crie uma integração Webhook genérico, configure regras de tag e faça o seu sistema enviar um POST com qualquer JSON para a URL da integração. A Clickmax identifica o contato, aplica as tags das regras que baterem e, com isso, dispara as automações com o gatilho Tag Aplicada ao Contato.

Exemplo: o seu app avisa que um aluno passou 21 dias sem acessar → a regra aplica a tag desengajado-3-semanas → uma automação de WhatsApp ou e-mail tenta trazê-lo de volta.

Antes de começar

• Papel: quem pode gerenciar integrações no workspace. Veja papéis e permissões.
• Atenção: qualquer pessoa com a URL pode enviar dados para a sua base de contatos. Compartilhe só com o sistema que vai chamá-la.

#Passo 1 — Crie a integração

1. Abra Integrações e procure Webhook genérico.
2. Dê um nome à integração (ex.: Régua de engajamento) e crie.
3. A Clickmax abre a integração já na aba Regras. A URL de recebimento fica no topo da tela, pronta para copiar.

#Passo 2 — Configure as regras de tag

Na aba Regras, cada regra diz: se o Campo do JSON atender à Condição com o Valor, aplique a tag.

1. Clique em Adicionar regra.
2. Em Campo do JSON, escreva o caminho do campo no JSON que o seu sistema envia. Use ponto para campos dentro de objetos (plano.tipo) e colchetes para listas (itens[0].nome).
3. Escolha a Condição: é igual a, é diferente de, contém, é maior que, é maior ou igual a, é menor que, é menor ou igual a, está vazio ou não está vazio.
4. Preencha o Valor (não é usado em está vazio e não está vazio).
5. Em Aplicar a tag, busque e escolha uma tag da lista. Para uma tag nova, digite o nome e clique em Criar tag "…" (exige permissão para criar tags).
6. Opcional: em Tag fixa (opcional), escolha (ou crie) uma tag aplicada em toda chamada que identificar um contato, batendo regra ou não. O X ao lado remove a tag fixa.
7. Clique em Salvar regras.

A regra guarda a tag escolhida, não o nome digitado: renomear a tag depois continua funcionando. Se a tag for excluída, a regra deixa de aplicá-la e o campo mostra Esta tag foi excluída. Escolha outra.

Como as regras são comparadas:

• Cada regra é avaliada separadamente: todas as que baterem aplicam a sua tag.
• Texto é comparado sem diferenciar maiúsculas e minúsculas e ignorando espaços nas pontas (" Inativo " é igual a inativo).
• é maior que e as outras comparações de número só batem quando os dois lados são números. "21" (texto) conta como número; vírgula decimal também (1.234,50).
• contém num campo que é uma lista verifica se algum item é igual ao valor.
• Um campo que não veio no JSON só bate em está vazio e em é diferente de.
• No máximo 20 tags são aplicadas por chamada, contando a tag fixa.

#Passo 3 — Teste antes de salvar

Em Testar antes de salvar, cole um exemplo do JSON que o seu sistema vai enviar e clique em Testar. Nada é gravado: a tela mostra qual contato seria usado (ou se seria criado), o resultado de cada regra com o valor recebido e as tags que seriam aplicadas. O teste usa as regras como estão na tela, mesmo antes de salvar.

#Passo 4 — Envie os eventos do seu sistema

Faça um POST com o corpo em JSON para a URL da integração. Identifique o contato com um destes campos, nesta ordem de prioridade:

Os demais campos do JSON servem apenas às regras: eles não alteram o cadastro do contato.

curl -X POST "URL_DA_SUA_INTEGRACAO" \
  -H "Content-Type: application/json" \
  --data '{ "email": "[email protected]", "evento": "inativo", "dias_sem_acesso": 21 }'

Com as regras evento é igual a inativo → desengajado e dias_sem_acesso é maior ou igual a 21 → desengajado-3-semanas, esse envio aplica as duas tags ao contato.

#Passo 5 — Confira o resultado

Na aba Histórico da integração, cada chamada mostra as tags aplicadas e se o contato foi criado ou já existia. Clique em Detalhes para ver o JSON recebido.

Uma tag que o contato já tinha não é aplicada de novo, então reenviar o mesmo evento não dispara a automação outra vez.

#Limites

• Corpo da requisição de até 32 KB; acima disso a chamada é recusada com 413.
• Cerca de 600 chamadas por minuto por integração; acima disso a chamada é recusada com 429. Reenvie depois.
• Até 50 regras por integração e 20 tags por chamada.

#Se não funcionou

• O histórico mostra "Nenhum contato identificado": o JSON não trouxe leadId, email nem telephone válidos. A chamada é ignorada e nenhum contato é criado.
• O histórico mostra "leadId não encontrado": o leadId enviado não existe neste workspace. Envie o leadId certo ou use email/telephone.
• Nenhuma tag aplicada: use Testar antes de salvar com o mesmo JSON para ver o valor que cada regra leu. Confira o caminho do campo e se a comparação de número recebeu um número.
• A automação não rodou: confira se ela usa o gatilho Tag Aplicada ao Contato com a mesma tag e se está ativa. Se o contato já tinha a tag, ela não é aplicada de novo.
• A requisição retornou erro: consulte os códigos de erro.

#Relacionados

• Envie leads de uma página externa — quando você só quer criar leads, sem regras de tag
• Contatos e leads no CRM