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"
]
}'
{
"data": {
"action": "remove",
"affected": 2,
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000",
"6ba7b810-9dad-41d1-80b4-00c04fd430c8"
],
"contactCount": 340
}
}
Segmentos
Alta y Baja Masiva
Agrega o quita contactos de un segmento estático por ID o con una selección por filtros
POST
/
segments
/
{id}
/
members
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"
]
}'
{
"data": {
"action": "remove",
"affected": 2,
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000",
"6ba7b810-9dad-41d1-80b4-00c04fd430c8"
],
"contactCount": 340
}
}
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.
La operación es idempotente: agregar dos veces o quitar dos veces el mismo grupo no cambia nada la segunda vez (
Envía exactamente una de estas dos formas de elegir contactos (enviar ambas, o ninguna, responde
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.
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.affected: 0).
Path Parameters
string
required
UUID del segmento estático
Body Parameters
string
required
"add" para agregar o "remove" para quitar.400):
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).string
Texto de búsqueda (máximo 200 caracteres), igual que en la lista de contactos. No puede estar vacío.
object
Filtros de Búsqueda Avanzada, incluido
segment_id. Se combinan con search si envías ambos.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.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 |
Respuesta
string
La acción aplicada:
add o remove.number
Contactos realmente agregados o quitados. Los que ya estaban (al agregar) o que no estaban (al quitar) no cuentan.
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.number
Contactos activos del segmento tras la operación.
boolean
Solo aparece (
true) si el cambio se aplicó pero no se pudo recalcular el conteo; contactCount puede estar desactualizado.Ejemplos
Agregar por ID
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"
]
}'
Quitar a todos los que coinciden con un filtro
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 }
}
}'
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'] } }
})
}
);
{
"data": {
"action": "remove",
"affected": 2,
"contactIds": [
"550e8400-e29b-41d4-a716-446655440000",
"6ba7b810-9dad-41d1-80b4-00c04fd430c8"
],
"contactCount": 340
}
}
Errores
Todos los400 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 |
Was this page helpful?