Skip to main content
Um segmento na aba Segments (em Audience & campaigns) é um filtro salvo sobre os contatos do workspace: ele responde “quem entra neste público?” Você reutiliza a mesma definição no Preview e nas campanhas, sem refazer planilha a cada envio. Tags (em Contacts) são etiquetas simples; segmentos permitem combinar tags, campos personalizados e opt-in de marketing com lógica E/OU. Para a versão em artigo com a mesma referência técnica: Como criar um segmento no painel: JSON, regras e bons exemplos.

​
Onde criar

  1. Audience & campaigns → aba Segments.
  2. New segment — informe nome e a definição em JSON (campo Definition / similar no produto).
O backend valida o JSON: não aceita texto livre; usa uma DSL pequena na versão 1, com limite de até 32 regras por segmento.

​
Formato obrigatório (versão 1)

Três partes: version, match, rules. 
{
  "version": 1,
  "match": "all",
  "rules": []
}
CampoValoresSignificado
version1Versão do esquema (hoje fixo em 1).
match"all" ou "any"all: todas as regras precisam ser verdadeiras (AND). any: basta uma (OR).
rulesarrayLista de regras. Array vazio = todos os contatos do workspace (útil para teste, perigoso em campanha se esquecer de filtrar).

​
Tipos de regra

​
1) Tag

O contato precisa ter a tag indicada. O tagId é o UUID da tag no workspace (não o nome exibido). No painel, ao criar o segmento, costuma haver lista de tags com nome e início do ID para copiar sem erro. 
{
  "type": "tag",
  "tagId": "<uuid>"
}

​
2) Propriedade customizada

key é a chave do campo no workspace (a mesma da API de contatos). value na regra é sempre string no JSON da definição. Campos opcionais (continuam na versão 1; omitidos = comportamento antigo):
CampoValoresPadrãoSignificado
valueMatch"exact" ou "contains""exact"exact: igualdade ao texto armazenado (comportamento original). contains: o valor salvo no contato contém o texto da regra como substring.
ignoreCasetrue ou falsefalseSe true, a comparação ignora maiúsculas/minúsculas (ex.: regra cachoeiro casa com Cachoeiro de Itapemirim).
Regras de validação
  • Com valueMatch: "contains", value não pode ser string vazia.
  • Os modos valueMatch / ignoreCase aplicam-se a valores armazenados como string JSON no campo (jsonb_typeof = string). Propriedades numéricas, booleanas ou data não entram nesse filtro de texto — use igualdade exata clássica (valueMatch omitido) apenas quando o valor no banco for string compatível.
Só igualdade exata (padrão, compatível com segmentos antigos): 
{
  "type": "property",
  "key": "nome_do_campo",
  "value": "texto"
}
Contém substring, ignorando maiúsculas (ex.: cidade): 
{
  "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. 
{
  "type": "receiveMarketing",
  "value": true
}

​
Exemplos completos para colar

Só quem aceita marketing: 
{
  "version": 1,
  "match": "all",
  "rules": [
    { "type": "receiveMarketing", "value": true }
  ]
}
VIP com marketing (tag + opt-in, AND): 
{
  "version": 1,
  "match": "all",
  "rules": [
    { "type": "tag", "tagId": "SEU_UUID_DA_TAG_VIP" },
    { "type": "receiveMarketing", "value": true }
  ]
}
Contatos em SP ou RJ (OR), pela propriedade uf: 
{
  "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 duas regras property (ou property + tag). Com valueMatch omitido, value deve ser igual ao texto salvo; com contains / ignoreCase, ajuste conforme a tabela acima. Cidade que contém um trecho (OR com outra regra): 
{
  "version": 1,
  "match": "any",
  "rules": [
    {
      "type": "property",
      "key": "cidade",
      "value": "Itapemirim",
      "valueMatch": "contains",
      "ignoreCase": true
    },
    { "type": "tag", "tagId": "SEU_UUID_OPCIONAL" }
  ]
}

​
Preview e campanhas

Depois de salvar, use Preview na listagem: o backend recalcula o filtro, mostra total e uma amostra de contatos. Se o total for zero e você esperava muitos, revise tagId, key/value e se usou all vs any. Em campanhas, ao escolher audiência por segmento, o sistema reaplica a mesma definição na hora do envio — o mesmo motor do Preview. Importante: segmento não substitui política legal nem opt-out. Envios de marketing continuam sujeitos a consentimento e, quando aplicável, a tópicos — veja Tópicos de comunicação.

​
Erros frequentes

  • tagId de outro workspace ou UUID cortado na cópia.
  • key diferente da definição do campo personalizado.
  • value na regra como texto, mas o contato tem número ou outro JSON no banco — ou uso de contains/ignoreCase esperando casar número (só vale para valor armazenado como string).
  • valueMatch: "contains" com value vazio.
  • valueMatch ou ignoreCase com tipo errado (string diferente de exact/contains, ou ignoreCase que não seja booleano).
  • Uso de any quando a intenção era todas as condições (all).
Alinhe nomes de propriedades e tags com quem integra via API de contatos para o painel e o código usarem a mesma convenção.

​
Próximo passo