> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Segmentos na audiência

> Filtros salvos com tags, campos de plataforma, propriedades, tópicos e marketing.

<Tip>
  **Segmento** = pergunta **salva** (“quem entra?”). **Tag** cola na ficha; **segmento** combina várias regras com AND/OR. Sempre use **Preview** antes de campanha grande.
</Tip>

## O que é um segmento?

É um **público dinâmico** definido por regras JSON (`version: 1`). Quando você roda uma campanha, o sistema **reaplica** as mesmas regras, a lista não fica congelada no momento em que você salvou (a menos que use lista fixa de IDs na campanha).

Analogia: **tag** é etiqueta na pasta. **Segmento** é a busca salva: “VIP em SP que aceita marketing e está no tópico Promoções”.

## Segmento × tag × tópico × campanha

|              | **Segmento**    | **Tag**             | **Tópico**                 | **Campanha**         |
| ------------ | --------------- | ------------------- | -------------------------- | -------------------- |
| Função       | Define **quem** | Marca contato       | Consentimento por tema     | **Dispara** mensagem |
| Persistência | Regras salvas   | Na ficha do contato | Inscrição por tema         | Execução (Run)       |
| Na API       | `segments:*`    | `tags:*` / `tagIds` | `topics:*` / regra `topic` | `campaigns:*`        |

## Formato (versão 1)

```json theme={null}
{
  "version": 1,
  "match": "all",
  "rules": []
}
```

| Campo   | Valores            | Significado                                                  |
| ------- | ------------------ | ------------------------------------------------------------ |
| `match` | `"all"` ou `"any"` | **all** = AND (todas as regras). **any** = OR (qualquer uma) |
| `rules` | array (até **32**) | Lista vazia = **todos** os contatos, cuidado em campanha!    |

## Tipos de regra (5)

| `type`             | O que filtra                                      |
| ------------------ | ------------------------------------------------- |
| `tag`              | Contato tem a tag                                 |
| `property`         | Campo **personalizado** (`cidade`, `plano`)       |
| `contactField`     | Campo **de plataforma** (nome, telefone, e-mail…) |
| `topic`            | Inscrito ou não em um **tópico**                  |
| `receiveMarketing` | Opt-in geral de marketing                         |

### Exemplos rápidos

**Tag + marketing:**

```json theme={null}
{
  "version": 1,
  "match": "all",
  "rules": [
    { "type": "tag", "tagId": "SEU_UUID_TAG_VIP" },
    { "type": "receiveMarketing", "value": true }
  ]
}
```

**Cidade + tópico:**

```json theme={null}
{
  "version": 1,
  "match": "all",
  "rules": [
    {
      "type": "property",
      "key": "cidade",
      "op": "contains",
      "value": "cachoeiro",
      "ignoreCase": true
    },
    { "type": "topic", "topicId": "SEU_UUID_TOPICO", "subscribed": true }
  ]
}
```

Operadores completos por tipo de campo: **referência da API** (grupo Segmentos).

<Note>
  Não existe regra `type: "channel"`. Para “tem telefone” use `hasPhone` ou `phone`. Para Telegram use `hasTelegram` ou `telegramPeer`.
</Note>

## Preview e campanhas

**Preview** (`segments:read`), amostra paginada (máx. **500** por página) com `id`, `name`, `phone`, `email`, `receiveMarketing`.

Na **campanha**, escolha o segmento como audiência. No **Run**, as regras rodam de novo.

<Note>
  Segmento **não substitui** opt-out legal. Combine `topic` / `receiveMarketing` com sua política. Veja [Tópicos](/contacts-api/como-funciona/topicos-de-comunicacao).
</Note>

## Erros frequentes

* `tagId` / `topicId` de outro workspace
* `key` de propriedade diferente do campo personalizado
* `match: "any"` quando queria **todas** as condições (`all`)
* Cidade em `phone startsWith`, cidade é `property`, não DDD

## Próximos passos

* [Campanhas no painel](/contacts-api/como-funciona/campanhas-no-painel): usar segmento como audiência
* [Tópicos](/contacts-api/como-funciona/topicos-de-comunicacao): consentimento por tema
* [Escopos](/contacts-api/como-funciona/escopos-da-api-key)
* [Introdução](/contacts-api/como-funciona/introducao)