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

# Contacts

> Crear, listar, consultar y actualizar contactos.

## GET /contacts

Lista contactos con paginación page-based.

**Scope requerido:** `contacts:read`

### Parámetros

| Parámetro  | Tipo   | Default | Descripción                         |
| ---------- | ------ | ------- | ----------------------------------- |
| `page`     | number | `1`     | Página                              |
| `pageSize` | number | `20`    | Resultados por página (máx 100)     |
| `search`   | string | —       | Buscar por nombre, teléfono o email |
| `tag`      | string | —       | Filtrar por tag                     |

### Request

```bash theme={null}
curl "https://api.waspytech.com/api/v2/contacts?page=1&pageSize=20&search=maria" \
  -H "Authorization: Bearer wspy_..."
```

### Response `200`

```json theme={null}
{
  "data": [
    {
      "id": "contact-uuid",
      "phoneNumber": "+5491126032641",
      "name": "María García",
      "email": "maria@email.com",
      "tags": ["VIP", "Recurrente"],
      "customFields": { "empresa": "Acme" },
      "optedIn": true,
      "lastMessageAt": "2026-04-13T14:32:00.000Z",
      "createdAt": "2026-03-01T10:00:00.000Z"
    }
  ],
  "meta": { "requestId": "...", "page": 1, "pageSize": 20, "total": 142 }
}
```

***

## GET /contacts/:id

Obtener un contacto por ID.

**Scope requerido:** `contacts:read`

```bash theme={null}
curl https://api.waspytech.com/api/v2/contacts/CONTACT_ID \
  -H "Authorization: Bearer wspy_..."
```

### Errores

| Código              | Descripción           |
| ------------------- | --------------------- |
| `CONTACT_NOT_FOUND` | El contacto no existe |

***

## GET /contacts/:id/conversations

Listar conversaciones de un contacto. Paginación cursor-based.

**Scope requerido:** `contacts:read`

```bash theme={null}
curl "https://api.waspytech.com/api/v2/contacts/CONTACT_ID/conversations?limit=10" \
  -H "Authorization: Bearer wspy_..."
```

***

## POST /contacts

Crear un nuevo contacto.

**Scope requerido:** `contacts:write`

### Body

| Campo          | Tipo      | Requerido | Descripción                       |
| -------------- | --------- | --------- | --------------------------------- |
| `phoneNumber`  | string    | Sí        | Número con código de país         |
| `name`         | string    | No        | Nombre del contacto               |
| `email`        | string    | No        | Email                             |
| `tags`         | string\[] | No        | Tags para segmentación            |
| `customFields` | object    | No        | Campos personalizados (key-value) |

### Request

```bash theme={null}
curl -X POST https://api.waspytech.com/api/v2/contacts \
  -H "Authorization: Bearer wspy_..." \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+5491126032641",
    "name": "María García",
    "email": "maria@email.com",
    "tags": ["VIP"]
  }'
```

### Response `201`

```json theme={null}
{
  "data": {
    "id": "new-contact-uuid",
    "phoneNumber": "+5491126032641",
    "name": "María García",
    "email": "maria@email.com",
    "tags": ["VIP"],
    "customFields": {},
    "optedIn": true,
    "lastMessageAt": null,
    "createdAt": "2026-04-13T15:00:00.000Z"
  },
  "meta": { "requestId": "..." }
}
```

### Errores

| Código                   | Descripción                          |
| ------------------------ | ------------------------------------ |
| `CONTACT_ALREADY_EXISTS` | Ya existe un contacto con ese número |
| `INVALID_PHONE`          | Formato de teléfono inválido         |

***

## PATCH /contacts/:id

Actualizar un contacto existente. Solo enviá los campos que querés cambiar.

**Scope requerido:** `contacts:write`

### Body (todos opcionales)

| Campo          | Tipo      | Descripción                         |
| -------------- | --------- | ----------------------------------- |
| `name`         | string    | Nombre                              |
| `email`        | string    | Email                               |
| `phoneNumber`  | string    | Número de teléfono en formato E.164 |
| `tags`         | string\[] | Reemplaza todos los tags            |
| `customFields` | object    | Merge con campos existentes         |

### Request

```bash theme={null}
curl -X PATCH https://api.waspytech.com/api/v2/contacts/CONTACT_ID \
  -H "Authorization: Bearer wspy_..." \
  -H "Content-Type: application/json" \
  -d '{
    "tags": ["VIP", "Mayorista"],
    "customFields": { "empresa": "Acme Corp" }
  }'
```