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

# Alta y Baja Masiva

> Agrega o quita contactos de un segmento estático por ID o con una selección por filtros

Agrega o quita muchos contactos de un segmento **estático** en una sola petición. Puedes indicar los contactos por ID, o describir "todos los que coinciden" con una búsqueda y filtros para que el servidor los resuelva.

<Note>
  Solo funciona con segmentos estáticos. Un segmento dinámico no tiene miembros que editar: se calcula con sus reglas. Si usas un dinámico responde `400`.
</Note>

La operación es **idempotente**: agregar dos veces o quitar dos veces el mismo grupo no cambia nada la segunda vez (`affected: 0`).

***

## Path Parameters

<ParamField path="id" type="string" required>
  UUID del segmento estático
</ParamField>

***

## Body Parameters

<ParamField body="action" type="string" required>
  `"add"` para agregar o `"remove"` para quitar.
</ParamField>

Envía **exactamente una** de estas dos formas de elegir contactos (enviar ambas, o ninguna, responde `400`):

<ParamField body="contactIds" type="string[]">
  UUID de los contactos. De 1 a 10 000. Todos deben existir y ser de tu negocio; si alguno no, responde `400` y no se aplica nada. Los duplicados se ignoran. Al agregar solo cuentan contactos activos (no eliminados).
</ParamField>

<ParamField body="search" type="string">
  Texto de búsqueda (máximo 200 caracteres), igual que en la lista de contactos. No puede estar vacío.
</ParamField>

<ParamField body="filters" type="object">
  Filtros de [Búsqueda Avanzada](/api-reference/contacts/search), incluido `segment_id`. Se combinan con `search` si envías ambos.
</ParamField>

<Warning>
  Una selección por filtros se valida de forma **estricta**: una clave desconocida (en cualquier nivel), un valor vacío o un filtro sin condiciones responde `400`. Así, "quitar los contactos con el tag `prueba`" nunca se convierte por un error de escritura en "quitar a todos". Tampoco existe un "todos" implícito: la selección debe tener al menos un filtro o una búsqueda. El body no admite campos distintos de `action`, `contactIds`, `search` y `filters`.
</Warning>

***

## Límites

| Límite | Valor |
| - | - |
| `contactIds` por petición | 10 000 |
| Contactos de una selección por filtros | **50 000**. Si la selección los supera responde `400` con `Selección demasiado grande; usa filtros más específicos` |
| `contactIds` devueltos en la respuesta | Solo si el total afectado es de **10 000 o menos** |

Para mover más de 50 000 contactos, divide la selección con filtros más específicos (por ejemplo por tag, origen o fecha de creación) y envía varias peticiones.

***

## Respuesta

<ResponseField name="data.action" type="string">
  La acción aplicada: `add` o `remove`.
</ResponseField>

<ResponseField name="data.affected" type="number">
  Contactos realmente agregados o quitados. Los que ya estaban (al agregar) o que no estaban (al quitar) no cuentan.
</ResponseField>

<ResponseField name="data.contactIds" type="string[]">
  IDs de los contactos afectados, útil para ofrecer "Deshacer" enviando la acción contraria con estos IDs. **Solo se devuelve hasta 10 000**; si hay más, el campo se omite y debes usar `affected`.
</ResponseField>

<ResponseField name="data.contactCount" type="number">
  Contactos activos del segmento tras la operación.
</ResponseField>

<ResponseField name="data.countStale" type="boolean">
  Solo aparece (`true`) si el cambio se aplicó pero no se pudo recalcular el conteo; `contactCount` puede estar desactualizado.
</ResponseField>

***

## Ejemplos

### Agregar por ID

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.whaapy.com/segments/7c9e6679-7425-40de-944b-e07fc1f90ae7/members \
    -H "Authorization: Bearer wha_TU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "add",
      "contactIds": [
        "550e8400-e29b-41d4-a716-446655440000",
        "6ba7b810-9dad-41d1-80b4-00c04fd430c8"
      ]
    }'
  ```
</RequestExample>

### Quitar a todos los que coinciden con un filtro

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.whaapy.com/segments/7c9e6679-7425-40de-944b-e07fc1f90ae7/members \
    -H "Authorization: Bearer wha_TU_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "action": "remove",
      "filters": {
        "tags": { "any": ["prueba"] },
        "created_at": { "within_days": 7 }
      }
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    'https://api.whaapy.com/segments/7c9e6679-7425-40de-944b-e07fc1f90ae7/members',
    {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer wha_TU_API_KEY',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        action: 'remove',
        filters: { tags: { any: ['prueba'] } }
      })
    }
  );
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "data": {
      "action": "remove",
      "affected": 2,
      "contactIds": [
        "550e8400-e29b-41d4-a716-446655440000",
        "6ba7b810-9dad-41d1-80b4-00c04fd430c8"
      ],
      "contactCount": 340
    }
  }
  ```
</ResponseExample>

***

## Errores

Todos los `400` tienen la forma `{ "error": "..." }`, salvo los de formato del body, que incluyen `details`.

| Código | Causa |
| - | - |
| `400` | El segmento es dinámico: `Solo se pueden agregar o quitar contactos en segmentos estáticos` |
| `400` | Body inválido: `action` ausente o desconocida, campos extra, `contactIds` vacío o con más de 10 000 elementos, o se enviaron `contactIds` junto con `search`/`filters` (o ninguno de los dos) |
| `400` | Algún contacto no existe o no es de tu negocio: `Algunos contactos no existen o no pertenecen a tu negocio` |
| `400` | `Filtros inválidos (campo "..."): ...` por clave desconocida, valor vacío, filtro sin condiciones o teléfono sin dígitos |
| `400` | `La búsqueda no puede estar vacía` o `La selección debe tener al menos un filtro o una búsqueda` |
| `400` | `Selección demasiado grande; usa filtros más específicos` (más de 50 000 contactos) |
| `404` | El `id` no es un UUID válido, o el segmento no existe o no es de tu negocio |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.