Como criar um segmento no painel: JSON, regras e bons exemplos

Um segmento responde: “quem do meu workspace entra nesse público?”. No produto, ele é um filtro reutilizável: você salva a lógica uma vez, prevê quantas pessoas entram e escolhe esse segmento ao montar uma campanha—sem refazer planilha a cada envio.

O guia técnico completo (validação, erros e fluxo da tela) está na documentação: https://docs.notifique.dev/segmento-introducao

No painel, o caminho é Audience & campaigns → aba Segments → New segment. Você informa um nome e uma definição em JSON. O backend não aceita texto solto: ele valida uma DSL pequena e segura, hoje na versão 1, e traduz isso em consulta aos contatos do workspace (sempre isolado por workspace).

O formato obrigatório tem três partes: version, match (all ou any) e rules como lista. O limite é até 32 regras por segmento. Abaixo, o esqueleto que você cola no campo Definition JSON:

{
  "version": 1,
  "match": "all",
  "rules": []
}

Com match all, todas as regras precisam ser verdadeiras (AND). Com any, basta uma (OR). Se rules for um array vazio, o segmento inclui todos os contatos daquele workspace—útil para testar pipeline, mas perigoso em campanha se você esquecer de apertar o filtro depois.

Há só três tipos de regra. (1) Tag — o contato precisa ter essa tag. O tagId é o identificador da tag no workspace, não o nome amigável. No modal de criação, o painel costuma listar tags carregadas com nome e início do ID para você copiar sem erro.

{
  "type": "tag",
  "tagId": "<uuid>"
}

(2) Propriedade customizada — o key é a chave da definição da propriedade no workspace (a mesma que você usa na API de contatos). O value na DSL precisa ser string. Se você não informar nada além disso, o comportamento continua o de sempre: igualdade exata (case-sensitive) com o valor JSON armazenado no contato.

Ainda na versão 1 da DSL, a regra property aceita campos opcionais: valueMatch pode ser exact (padrão quando omitido) ou contains — neste caso o valor no contato precisa conter o texto da regra. ignoreCase, quando true, faz a comparação ignorar maiúsculas e minúsculas (padrão false quando omitido). Validação: com contains, value não pode ser vazio. contains e ignoreCase se aplicam de forma consistente quando a propriedade está gravada como string no JSON do contato; número, booleano ou data armazenados de outro modo não entram nesse mesmo critério de “contém texto”.

{
  "type": "property",
  "key": "nome_do_campo",
  "value": "texto"
}

Exemplo: cidade salva como “Cachoeiro de Itapemirim” e você quer quem tenha “cachoeiro” no meio do texto, sem diferenciar maiúsculas:

{
  "type": "property",
  "key": "cidade",
  "value": "cachoeiro",
  "valueMatch": "contains",
  "ignoreCase": true
}

(3) Marketing geral — filtra quem aceita ou não comunicação de marketing no cadastro do contato. Combine com tags ou propriedades para respeitar consentimento e ainda ser específico no recorte.

{
  "type": "receiveMarketing",
  "value": true
}

Exemplo: só quem aceita marketing (definição completa):

{
  "version": 1,
  "match": "all",
  "rules": [
    { "type": "receiveMarketing", "value": true }
  ]
}

Exemplo: VIP que aceita marketing — tag e opt-in ao mesmo tempo (AND):

{
  "version": 1,
  "match": "all",
  "rules": [
    { "type": "tag", "tagId": "SEU_UUID_DA_TAG_VIP" },
    { "type": "receiveMarketing", "value": true }
  ]
}

Exemplo: contatos em SP ou RJ (qualquer um dos dois — OR), usando a mesma propriedade uf com valores diferentes:

{
  "version": 1,
  "match": "any",
  "rules": [
    { "type": "property", "key": "uf", "value": "SP" },
    { "type": "property", "key": "uf", "value": "RJ" }
  ]
}

Para “SP e plano premium”, use match all com uma regra de uf e outra de propriedade plano cujo value seja exatamente o que você grava nos contatos.

Depois de salvar, use Preview na listagem: o backend recalcula o filtro, devolve total e uma página de contatos (nome, telefone, e-mail) para validar se o JSON reflete a intenção. Se o total for zero quando você esperava muitos contatos, revise tagId, key/value, valueMatch, ignoreCase ou o match.

Em campanhas, ao escolher audiência por segmento, o sistema reutiliza a mesma definição na hora de montar o público—o mesmo motor de segmentação do preview, incluindo contains e ignoreCase quando usados nas regras. Envios de marketing continuam sujeitos a consentimento (tópicos, quando aplicável); segmento não substitui política interna nem opt-out.

Erros frequentes: UUID de tag de outro workspace ou copiado incompleto; key diferente do cadastro da propriedade; valor string na regra mas número (ou outro tipo) no contato quando você esperava match de texto; contains com value vazio; match errado (any quando queria all). Quando possível, padronize propriedades e tags com quem integra via API para o painel e o código falarem a mesma língua.

Resumo: segmento no painel é JSON na versão 1 com regras tag, property (opcionalmente com valueMatch e ignoreCase) e receiveMarketing, AND/OR explícitos, validação no servidor e preview antes de disparar. Dominar esse formato deixa campanhas previsíveis e a base auditável.