Messaggi transazionali e cascate

I messaggi transazionali sono conferme d'ordine, codici di accesso, notifiche di consegna. Il cliente li aspetta, quindi partono subito e attraverso una coda separata: una grande campagna non li rallenta. La cascata invia un unico messaggio su più canali, uno dopo l'altro. Ad esempio, prima WhatsApp e, se entro 2 minuti non viene consegnato, un SMS.

Può inviare un messaggio di questo tipo da un percorso o dal Suo server tramite l'API.

Modello transazionale

Perché un messaggio sia considerato transazionale, attivi Messaggio transazionale nel suo modello. Questo messaggio viene inviato senza verificare iscrizione, limiti di frequenza e ore di silenzio. Le email inviate tramite il servizio di posta di OneTrace.ru partono senza riscaldamento e in un flusso separato, senza link di disiscrizione nelle intestazioni.

Non contrassegni così i messaggi promozionali: viola i diritti dei destinatari e danneggia la reputazione del mittente.

Anche un messaggio transazionale non parte se il canale del destinatario è chiuso:

Un messaggio di questo tipo riceve lo stato «Saltato» con il motivo «canale bloccato per il destinatario». Il canale si riapre quando il cliente si iscrive di nuovo, ad esempio preme «Start» nel bot. Un reclamo per spam non chiude il canale: le email sugli ordini a questo indirizzo continuano ad arrivare.

Invio tramite API

Il Suo server invia il messaggio con la richiesta POST /api/v1/messages. Serve una chiave segreta con il permesso «Invio di singoli messaggi», veda Chiavi API.

curl -X POST https://cdp.onetrace.ru/api/v1/messages \
  -H "Authorization: Bearer $CDP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-A-1001" \
  -d '{
    "identity": {"type": "email", "value": "anna@example.com"},
    "template_id": 12,
    "traits": {"first_name": "Anna"},
    "data": {"order_id": "A-1001", "amount": 4990}
  }'

La risposta 202 contiene l'id del messaggio e il suo stato. Lo stato attuale viene restituito da GET /api/v1/messages/{id}: queued, sent, delivered, failed, skipped e altri, con il motivo del salto o dell'errore.

• La ripetizione è sicura. Una richiesta con la stessa intestazione Idempotency-Key restituisce il messaggio già creato, il secondo non viene inviato. Usi il numero d'ordine o l'id dell'operazione.
• Limite per destinatario: 20 messaggi all'ora tramite API. Se viene superato, arriva 429 con l'intestazione Retry-After.
• Un modello normale senza l'opzione «Transazionale» può essere inviato anche tramite API. In questo caso si applicano tutte le regole di invio.

Nella libreria PHP pronta all'uso è $onetrace->messages()->send(Identity::email('anna@example.com'), 12, ['data' => [...]], 'order-A-1001'), nel pacchetto per Laravel messages()->send(...).

Cascata in un percorso

Aggiunga al percorso il nodo Invio a cascata dal gruppo «Azioni». Nel campo Canali in ordine imposti da 2 a 5 passaggi. Per ogni passaggio indichi:

• Integrazione e Modello del canale.
• Attendere: che cosa considerare un successo, «inviato», «consegnato» o «letto».
• Tempo di attesa: per «consegnato» e «letto», 15 minuti per impostazione predefinita.

La cascata passa al passaggio successivo se:

• il profilo non ha un indirizzo o un numero per il canale, oppure il canale è chiuso: il passaggio viene saltato subito e il messaggio non viene creato;
• il messaggio non è partito: errore di invio o salto per le regole di invio;
• il provider ha segnalato la mancata consegna;
• entro il tempo di attesa non è arrivata la conferma di consegna o di lettura.

Non tutti i canali consentono di attendere la consegna e la lettura:

Il nodo ha due uscite: arrivato, il messaggio di uno dei passaggi ha raggiunto l'obiettivo; non riuscito, nessun canale ha funzionato. Finché la cascata è in corso, il partecipante attende sul nodo.

L'invio a cascata consegna lo stesso messaggio. I modelli di percorso come «Carrello: push → email → SMS» funzionano diversamente: lì messaggi diversi partono a intervalli finché il cliente non effettua un ordine.

Cascata tramite API

Invece di template_id passi steps, gli stessi passaggi del nodo del percorso:

{
  "identity": {"type": "phone", "value": "+79991234567"},
  "steps": [
    {"integration_id": 3, "template_id": 21, "wait_for": "delivered", "timeout": {"amount": 2, "unit": "minute"}},
    {"integration_id": 4, "template_id": 22, "wait_for": "sent"}
  ],
  "data": {"code": "482913"}
}

wait_for accetta sent, delivered o opened, le unità di timeout sono minute, hour, day, week. La risposta 202 contiene l'id della cascata, GET /api/v1/messages/cascades/{id} ne restituisce lo stato:

• status: running, reached o failed;
• il passaggio attuale step;
• il canale che ha funzionato, reached_channel;
• i messaggi dei passaggi messages.

Piano

I messaggi transazionali e l'invio tramite API sono disponibili in tutti i piani. La cascata è disponibile dal piano «Crescita», veda Piano e fatturazione. Con il piano «Start» il nodo nella palette dell'editor è contrassegnato da un lucchetto e l'API risponde 402. Se il piano viene ridotto, nei percorsi già attivi viene inviato solo il primo passaggio della cascata.