# Segmentos

## Listar segmentos

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

### Parámetros de la dirección

| Campo | Detalles |
|---|---|
| `slug` | El identificador de la empresa en DoneTalk (el de la clave). |

### Ejemplo de solicitud

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

### Respuesta 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"
    }
  ]
}
```

### Errores posibles

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

## Crear un segmento

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

Un grupo de contactos por condiciones: etiqueta, origen, último desenlace, días desde la última conversación o el alta, consentimiento de marketing, nombre, WhatsApp y cualquier campo (`field.<clave>`).

### Parámetros de la dirección

| Campo | Detalles |
|---|---|
| `slug` | El identificador de la empresa en DoneTalk (el de la clave). |

### Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Detalles |
|---|---|---|---|
| `name` | string | sí | hasta 120 caracteres |
| `conditions` | lista de objeto | sí | hasta 20 |
| `conditions[].field` | string | sí | hasta 80 caracteres |
| `conditions[].op` | uno de `eq`, `neq`, `has`, `not_has`, `contains`, `empty`, `not_empty`, `gt`, `lt`, `none` | sí |  |
| `conditions[].value` | string · number · boolean · uno de `null` | no |  |

### Ejemplo de solicitud

```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"
    }
  ]
}'
```

### Respuesta 201

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

### Errores posibles

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

## Editar un segmento

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

### Parámetros de la dirección

| Campo | Detalles |
|---|---|
| `slug` | El identificador de la empresa en DoneTalk (el de la clave). |
| `id` | El id del registro. |

### Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Detalles |
|---|---|---|---|
| `name` | string | sí | hasta 120 caracteres |
| `conditions` | lista de objeto | sí | hasta 20 |
| `conditions[].field` | string | sí | hasta 80 caracteres |
| `conditions[].op` | uno de `eq`, `neq`, `has`, `not_has`, `contains`, `empty`, `not_empty`, `gt`, `lt`, `none` | sí |  |
| `conditions[].value` | string · number · boolean · uno de `null` | no |  |

### Ejemplo de solicitud

```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"
    }
  ]
}'
```

### Respuesta 200

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

### Errores posibles

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

## Borrar un segmento

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

### Parámetros de la dirección

| Campo | Detalles |
|---|---|
| `slug` | El identificador de la empresa en DoneTalk (el de la clave). |
| `id` | El id del registro. |

### Ejemplo de solicitud

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

### Respuesta 200

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

### Errores posibles

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

## Contar quién entra

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

### Parámetros de la dirección

| Campo | Detalles |
|---|---|
| `slug` | El identificador de la empresa en DoneTalk (el de la clave). |

### Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Detalles |
|---|---|---|---|
| `conditions` | lista de objeto | sí | hasta 20 |
| `conditions[].field` | string | sí | hasta 80 caracteres |
| `conditions[].op` | uno de `eq`, `neq`, `has`, `not_has`, `contains`, `empty`, `not_empty`, `gt`, `lt`, `none` | sí |  |
| `conditions[].value` | string · number · boolean · uno de `null` | no |  |

### Ejemplo de solicitud

```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"
    }
  ]
}'
```

### Respuesta 200

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

### Errores posibles

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

## Buscar contactos por condiciones

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

### Parámetros de la dirección

| Campo | Detalles |
|---|---|
| `slug` | El identificador de la empresa en DoneTalk (el de la clave). |

### Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Detalles |
|---|---|---|---|
| `segmentId` | string (uuid) | no |  |
| `conditions` | lista de objeto | no | hasta 20; default `[]` |
| `conditions[].field` | string | sí | hasta 80 caracteres |
| `conditions[].op` | uno de `eq`, `neq`, `has`, `not_has`, `contains`, `empty`, `not_empty`, `gt`, `lt`, `none` | sí |  |
| `conditions[].value` | string · number · boolean · uno de `null` | no |  |
| `q` | string | no | hasta 100 caracteres |
| `limit` | integer | no | hasta 200; mínimo 1; default `50` |
| `offset` | integer | no | hasta 1000000; default `0` |

### Ejemplo de solicitud

```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
}'
```

### Respuesta 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"
    }
  ]
}
```

### Errores posibles

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