¿Qué es un segmento?
Un segmento es un grupo de contactos de tu negocio. Hay dos tipos:- Estático: una lista de contactos que tú agregas y quitas (a mano, por ID o con una selección por filtros). Los segmentos estáticos no usan reglas.
- Dinámico: un filtro guardado que se calcula al momento. No guarda una lista de miembros: cada vez que consultas el segmento, o que una campaña lo usa, se evalúa el filtro sobre tus contactos actuales. Un contacto que empieza a cumplir las condiciones entra solo; el que deja de cumplirlas sale solo.
Los endpoints de segmentos viven en
https://api.whaapy.com/segments (sin /v1) y se autentican con tu API Key, igual que el resto de la API.Reglas de un segmento dinámico
Formato actual: versión 3
filters acepta los mismos campos que filters en Búsqueda Avanzada (teléfono, nombre, email, tags, etapa del funnel, origen, fechas, campos personalizados, etc.), con una excepción: no se permite segment_id dentro de un segmento (evita segmentos que dependen de sí mismos). Se guarda en snake_case, como en la API de búsqueda.
La validación de v3 es estricta a propósito. Si una regla se ignorara en silencio, el segmento sería más grande de lo que esperas y podrías enviar una campaña a contactos equivocados. Por eso, en lugar de ignorarlas, se rechazan.
Versiones anteriores (v1 y v2)
Las reglas heredadas siguen aceptándose al crear, actualizar y previsualizar:- v1:
{ "operator": "AND" | "OR", "conditions": [...] }, sin campoversion. - v2:
{ "version": 2, "operator": "AND" | "OR", "groups": [...] }.
filters (ver abajo). Convertirla nunca modifica lo guardado.
Campos de respuesta
Además de los campos habituales (id, name, type, contactCount, color…), los segmentos devuelven:
number
Número de contactos activos del segmento. En un dinámico se calcula al momento.
object | null
Filtros v3 del segmento. En reglas v3 son los guardados. En reglas v1/v2 solo aparecen cuando la conversión es exacta y se comprobó que ambos motores cuentan lo mismo; esa comprobación se hace al consultar el detalle (
GET /segments/{id}), por lo que en el listado puede venir null. En segmentos estáticos es null.string | null
"filters" si las reglas guardadas son v3, "legacy" si son v1/v2, y null en estáticos.boolean
Solo aparece (con valor
true) cuando no se pudo contar al momento, por ejemplo por un tiempo de espera. En ese caso contactCount es el último valor guardado. Vuelve a consultar el segmento o llama a POST /segments/{id}/evaluate.string
Solo aparece cuando las reglas guardadas ya no son válidas. El segmento se sigue devolviendo para que puedas abrirlo y corregirlo, pero no contiene a nadie hasta que lo hagas; nunca se amplía la audiencia.
boolean
Solo aparece en la respuesta de
PATCH /segments/{id} cuando enviaste un type distinto al actual. El tipo de un segmento no se puede cambiar: se ignora y se avisa con este campo.Endpoints
Crear un segmento dinámico
type "dynamic" requiere rules. Un type "static" no las usa: enviar reglas v3 a un estático responde 400; reglas heredadas, null o vacías se ignoran por compatibilidad. El campo autoRefreshInterval se sigue aceptando pero se ignora, porque los dinámicos ya se calculan al momento.
Previsualizar reglas
POST /segments/preview recibe { "rules": ... } (v1, v2 o v3) y devuelve data.count y data.preview (una muestra de contactos) sin guardar nada.
Errores 400
Un segmento rechaza reglas que no se pueden aplicar con seguridad. Todas las respuestas tienen la forma{ "error": "..." }.
Los mensajes de reglas terminan con
Corrige la regla del segmento e inténtalo de nuevo. En validaciones de formato (por ejemplo un campo que falta) la respuesta es { "error": "Datos inválidos", "details": [...] }.
Otros códigos: 404 si el segmento no existe o no es de tu negocio (nunca se distingue entre ambos casos) y 500 ante un error interno.
Próximos pasos
Búsqueda Avanzada
Todos los filtros disponibles
Uso de un segmento
Campañas y agentes que lo usan
Alta y baja masiva
Agregar o quitar miembros de un estático