Iscrizione e trigger
Iscrivi i contatti in una sequenza attiva, ciclo di vita dell'iscrizione e stato reale dei trigger.
Un contatto entra in una sequenza tramite un'iscrizione (enrollment). Ogni iscrizione porta con se la propria posizione e stato, indipendenti dalle altre.
Iscrivere un contatto
POST /sequences/{id}/enroll
Authorization: Bearer <apiKey o accessToken>
X-Tenant-Id: {tenantId}
Content-Type: application/json
{
"contactId": "cont_123"
}
Richiede lo scope sequences:write. Perche l'iscrizione vada a buon fine:
- La sequenza deve essere
ACTIVE. - Il contatto deve appartenere al tuo tenant.
- Deve avere opt-in e non comparire nella lista di soppressione.
- Non puo essere gia iscritto a quella sequenza (una iscrizione per contatto e sequenza).
Ciclo di vita dell'iscrizione
| Stato | Significato |
|---|---|
ACTIVE | Avanza tra gli step |
COMPLETED | Ha raggiunto la fine della sequenza |
CANCELLED | Interrotta: il contatto ha disdetto o e stato soppresso, oppure il destinatario e stato rifiutato |
PAUSED | La sequenza e stata messa in PAUSED |
FAILED | L'invio ha esaurito i retry, o manca il template/la sequenza |
Le uscite avvengono da sole: se il contatto viene soppresso o disdice a meta flusso, la sua iscrizione passa a CANCELLED e non riceve altri step. Mettere in pausa la sequenza sposta le iscrizioni in corso a PAUSED.
Elencare le iscrizioni
GET /sequences/{id}/enrollments?page=1&limit=20&status=ACTIVE
Richiede sequences:read. Restituisce le iscrizioni paginate; filtra per status con uno qualsiasi dei valori della tabella precedente.
Trigger automatici
Alla creazione della sequenza imposti un triggerType e il suo triggerConfig. Oltre all'iscrizione manuale, i tre trigger automatici ora iscrivono i contatti da soli.
triggerType | triggerConfig | Quando iscrive |
|---|---|---|
MANUAL | — | Solo con POST /sequences/:id/enroll |
CONTACT_CREATED | { "requireOptIn": true } | Alla creazione di un contatto con opt-in |
CONTACT_TAGGED | { "tag": "vip" } | Quando quel tag viene aggiunto a un contatto |
API_EVENT | { "eventName": "signup" } | Quando quell'evento arriva via API |
CONTACT_CREATED
Creare un contatto con opt-in (con PUT /contacts o l'SDK) lo iscrive in tutte le sequenze ACTIVE con questo trigger. Il fan-out e asincrono (coda sequence-trigger), quindi un import massivo non rallenta la richiesta.
CONTACT_TAGGED
Etichettare un contatto con il tag configurato lo iscrive nelle sequenze ACTIVE che lo aspettano:
POST /contacts/{idOrExternalId}/tags
Authorization: Bearer <apiKey o accessToken>
X-Tenant-Id: {tenantId}
Content-Type: application/json
{
"tags": ["vip"]
}
Richiede contacts:write. Si attiva solo la prima volta che il tag viene aggiunto (idempotente: rietichettare non iscrive di nuovo). Rimuovere il tag con DELETE /contacts/{idOrExternalId}/tags/{tag} non annulla un'iscrizione gia creata. Anche l'iscrizione e asincrona.
API_EVENT
Attiva un tuo evento; le sequenze il cui triggerConfig.eventName corrisponde iscrivono il contatto:
POST /sequences/events
Authorization: Bearer <apiKey o accessToken>
X-Tenant-Id: {tenantId}
Content-Type: application/json
{
"eventName": "signup",
"contactId": "cont_123"
}
Richiede sequences:write. Risponde { "matched": N, "enrolled": M }: quante sequenze hanno corrisposto e quante hanno davvero iscritto (i contatti gia iscritti o senza opt-in vengono saltati). A differenza degli altri due, e sincrono.