Inscripcion y disparadores
Inscribe contactos en una secuencia activa, ciclo de vida del enrollment y estado real de los disparadores.
Un contacto entra en una secuencia mediante una inscripcion (enrollment). Cada inscripcion lleva su propia posicion y estado, independiente del resto.
Inscribir un contacto
POST /sequences/{id}/enroll
Authorization: Bearer <apiKey o accessToken>
X-Tenant-Id: {tenantId}
Content-Type: application/json
{
"contactId": "cont_123"
}
Requiere el scope sequences:write. Para que la inscripcion tenga exito:
- La secuencia debe estar en
ACTIVE. - El contacto debe pertenecer a tu tenant.
- Debe estar opted-in y no aparecer en la lista de supresion.
- No puede estar ya inscrito en esa secuencia (una inscripcion por contacto y secuencia).
Ciclo de vida de la inscripcion
| Estado | Significado |
|---|---|
ACTIVE | Avanzando por los pasos |
COMPLETED | Llego al final de la secuencia |
CANCELLED | Detenida: el contacto se dio de baja o fue suprimido, o el destinatario fue rechazado |
PAUSED | La secuencia se puso en PAUSED |
FAILED | El envio agoto los reintentos o falta la plantilla/secuencia |
Las salidas ocurren solas: si el contacto se suprime o se da de baja a mitad del flujo, su inscripcion pasa a CANCELLED y no recibe mas pasos. Poner la secuencia en pausa mueve las inscripciones en curso a PAUSED.
Listar inscripciones
GET /sequences/{id}/enrollments?page=1&limit=20&status=ACTIVE
Requiere sequences:read. Devuelve las inscripciones paginadas; filtra por status con cualquiera de los valores de la tabla anterior.
Disparadores automaticos
Al crear la secuencia fijas un triggerType y su triggerConfig. Ademas de la inscripcion manual, los tres disparadores automaticos ya inscriben contactos por si solos.
triggerType | triggerConfig | Cuando inscribe |
|---|---|---|
MANUAL | — | Solo con POST /sequences/:id/enroll |
CONTACT_CREATED | { "requireOptIn": true } | Al crear un contacto opted-in |
CONTACT_TAGGED | { "tag": "vip" } | Al anadir ese tag a un contacto |
API_EVENT | { "eventName": "signup" } | Al recibir ese evento por API |
CONTACT_CREATED
Al crear un contacto opted-in (con PUT /contacts o el SDK) se inscribe en todas las secuencias ACTIVE con este disparador. El fan-out es asincrono (cola sequence-trigger), asi que una importacion masiva no penaliza la peticion.
CONTACT_TAGGED
Etiquetar un contacto con el tag configurado lo inscribe en las secuencias ACTIVE que lo esperan:
POST /contacts/{idOrExternalId}/tags
Authorization: Bearer <apiKey o accessToken>
X-Tenant-Id: {tenantId}
Content-Type: application/json
{
"tags": ["vip"]
}
Requiere contacts:write. Solo dispara la primera vez que se anade el tag (es idempotente: reetiquetar no vuelve a inscribir). Quitar el tag con DELETE /contacts/{idOrExternalId}/tags/{tag} no cancela una inscripcion ya creada. La inscripcion tambien es asincrona.
API_EVENT
Dispara un evento propio; las secuencias cuyo triggerConfig.eventName coincide inscriben al contacto:
POST /sequences/events
Authorization: Bearer <apiKey o accessToken>
X-Tenant-Id: {tenantId}
Content-Type: application/json
{
"eventName": "signup",
"contactId": "cont_123"
}
Requiere sequences:write. Responde { "matched": N, "enrolled": M }: cuantas secuencias coincidieron y cuantas inscribieron de verdad (las ya inscritas o sin opt-in se omiten). A diferencia de los otros dos, es sincrono.