# Segmentos

## Listar segmentos

`GET /v1/c/{slug}/segments` · Escopos: `contacts:read` · `campaigns:write`

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |

### Exemplo de pedido

```bash
curl -X GET "https://api.donetalk.com/v1/c/demo/segments" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Resposta 200

```json
{
  "segments": [
    {
      "id": "01a1a0b0-1c2d-7e3f-8a9b-0c1d2e3f4a5b",
      "name": "Clientes do plano anual",
      "conditions": [
        {
          "field": "field.plano",
          "op": "eq",
          "value": "anual"
        }
      ],
      "count": 312,
      "updatedAt": "2026-10-23T13:02:11.000Z"
    }
  ]
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Criar um segmento

`POST /v1/c/{slug}/segments` · Escopos: `contacts:write`

Um grupo de contatos por condições: etiqueta, origem, último desfecho, dias desde a última conversa ou o cadastro, consentimento de marketing, nome, WhatsApp e qualquer campo (`field.<chave>`).

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |

### Corpo do pedido

| Campo | Tipo | Obrigatório | Detalhes |
|---|---|---|---|
| `name` | string | sim | até 120 caracteres |
| `conditions` | lista de objeto | sim | até 20 |
| `conditions[].field` | string | sim | até 80 caracteres |
| `conditions[].op` | um de `eq`, `neq`, `has`, `not_has`, `contains`, `empty`, `not_empty`, `gt`, `lt`, `none` | sim |  |
| `conditions[].value` | string · number · boolean · um de `null` | não |  |

### Exemplo de pedido

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/segments" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Clientes do plano anual",
  "conditions": [
    {
      "field": "field.plano",
      "op": "eq",
      "value": "anual"
    }
  ]
}'
```

### Resposta 201

```json
{
  "segment": {
    "id": "01a1a0b0-1c2d-7e3f-8a9b-0c1d2e3f4a5b"
  }
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Editar um segmento

`PUT /v1/c/{slug}/segments/{id}` · Escopos: `contacts:write`

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |
| `id` | O id do registro. |

### Corpo do pedido

| Campo | Tipo | Obrigatório | Detalhes |
|---|---|---|---|
| `name` | string | sim | até 120 caracteres |
| `conditions` | lista de objeto | sim | até 20 |
| `conditions[].field` | string | sim | até 80 caracteres |
| `conditions[].op` | um de `eq`, `neq`, `has`, `not_has`, `contains`, `empty`, `not_empty`, `gt`, `lt`, `none` | sim |  |
| `conditions[].value` | string · number · boolean · um de `null` | não |  |

### Exemplo de pedido

```bash
curl -X PUT "https://api.donetalk.com/v1/c/demo/segments/:id" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Clientes do plano anual",
  "conditions": [
    {
      "field": "field.plano",
      "op": "eq",
      "value": "anual"
    }
  ]
}'
```

### Resposta 200

```json
{
  "ok": true
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Apagar um segmento

`DELETE /v1/c/{slug}/segments/{id}` · Escopos: `contacts:write`

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |
| `id` | O id do registro. |

### Exemplo de pedido

```bash
curl -X DELETE "https://api.donetalk.com/v1/c/demo/segments/:id" \
  -H "Authorization: Bearer $DONETALK_KEY"
```

### Resposta 200

```json
{
  "ok": true
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Contar quem entra

`POST /v1/c/{slug}/segments/count` · Escopos: `contacts:read` · `campaigns:write`

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |

### Corpo do pedido

| Campo | Tipo | Obrigatório | Detalhes |
|---|---|---|---|
| `conditions` | lista de objeto | sim | até 20 |
| `conditions[].field` | string | sim | até 80 caracteres |
| `conditions[].op` | um de `eq`, `neq`, `has`, `not_has`, `contains`, `empty`, `not_empty`, `gt`, `lt`, `none` | sim |  |
| `conditions[].value` | string · number · boolean · um de `null` | não |  |

### Exemplo de pedido

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/segments/count" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conditions": [
    {
      "field": "tag",
      "op": "has",
      "value": "01a12150-3610-7c00-b680-188c2b4c7313"
    }
  ]
}'
```

### Resposta 200

```json
{
  "count": 312
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`

## Buscar contatos por condições

`POST /v1/c/{slug}/contacts/search` · Escopos: `contacts:read`

### Parâmetros do endereço

| Campo | Detalhes |
|---|---|
| `slug` | O identificador da empresa no DoneTalk (o mesmo da chave). |

### Corpo do pedido

| Campo | Tipo | Obrigatório | Detalhes |
|---|---|---|---|
| `segmentId` | string (uuid) | não |  |
| `conditions` | lista de objeto | não | até 20; default `[]` |
| `conditions[].field` | string | sim | até 80 caracteres |
| `conditions[].op` | um de `eq`, `neq`, `has`, `not_has`, `contains`, `empty`, `not_empty`, `gt`, `lt`, `none` | sim |  |
| `conditions[].value` | string · number · boolean · um de `null` | não |  |
| `q` | string | não | até 100 caracteres |
| `limit` | integer | não | até 200; mínimo 1; default `50` |
| `offset` | integer | não | até 1000000; default `0` |

### Exemplo de pedido

```bash
curl -X POST "https://api.donetalk.com/v1/c/demo/contacts/search" \
  -H "Authorization: Bearer $DONETALK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "conditions": [
    {
      "field": "marketing",
      "op": "eq",
      "value": "opted_in"
    }
  ],
  "limit": 50
}'
```

### Resposta 200

```json
{
  "total": 312,
  "marketingAllowed": 298,
  "contacts": [
    {
      "id": "01a0d05a-3ee3-75bd-9db5-dc9856f079c8",
      "displayName": "Ana Souza",
      "source": "api",
      "fields": {
        "cpf": "529.982.247-25",
        "plano": "anual"
      },
      "isBlocked": false,
      "address": "5548999990001",
      "marketing": "opted_in",
      "lastOutcome": "converted",
      "tags": [
        {
          "id": "01a12150-3610-7c00-b680-188c2b4c7313",
          "name": {
            "pt-BR": "VIP",
            "en": "VIP",
            "es": "VIP"
          },
          "color": "#92400e"
        }
      ],
      "lastActivityAt": "2026-10-22T18:40:02.000Z",
      "createdAt": "2026-09-23T22:19:30.396Z"
    }
  ]
}
```

### Erros possíveis

- `401` `unauthorized`
- `403` `insufficient_scope`
- `422` `validation_failed`
- `429` `rate_limited`