Messages transactionnels et envois en cascade

Les messages transactionnels sont les confirmations de commande, les codes de connexion et les notifications de livraison. Le client les attend : ils partent donc immédiatement, par une file d'attente distincte, et une grosse campagne ne les retarde pas. L'envoi en cascade transmet un même message par plusieurs canaux, l'un après l'autre. Par exemple, d'abord WhatsApp, puis un SMS si le message n'est pas remis en 2 minutes.

Vous pouvez envoyer un tel message depuis un parcours ou depuis votre serveur via l'API.

Modèle transactionnel

Pour qu'un message soit considéré comme transactionnel, cochez Message transactionnel dans son modèle. Ce message est envoyé sans vérification de l'abonnement, des limites de fréquence ni des heures de silence. Les e-mails envoyés par le service de messagerie de OneTrace.ru partent sans montée en charge progressive, par un flux distinct et sans lien de désabonnement dans les en-têtes.

N'utilisez pas cette option pour de la publicité : cela enfreint les droits des destinataires et nuit à la réputation de l'expéditeur.

Même un message transactionnel ne part pas si le canal est fermé pour le destinataire :

Ce message reçoit le statut « Ignoré » avec le motif « canal bloqué pour le destinataire ». Le canal se rouvre lorsque le client s'abonne à nouveau, par exemple en appuyant sur « Start » dans le bot. Une plainte pour spam ne ferme pas le canal : les e-mails sur les commandes continuent d'arriver à cette adresse.

Envoi via l'API

Votre serveur envoie le message avec la requête POST /api/v1/messages. Il faut une clé secrète avec l'autorisation « Envoi de messages individuels », voir Clés 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": "Anne"},
    "data": {"order_id": "A-1001", "amount": 4990}
  }'

La réponse 202 contient l'id du message et son statut. GET /api/v1/messages/{id} renvoie le statut actuel : queued, sent, delivered, failed, skipped, etc., avec le motif de l'omission ou de l'erreur.

• Une nouvelle tentative est sans risque. Une requête avec le même en-tête Idempotency-Key renvoie le message déjà créé, aucun second message n'est envoyé. Utilisez le numéro de commande ou l'id de l'opération.
• Limite par destinataire : 20 messages par heure via l'API. En cas de dépassement, vous recevez 429 avec l'en-tête Retry-After.
• Un modèle ordinaire sans l'option « Transactionnel » peut aussi être envoyé via l'API. Toutes les règles d'envoi sont alors vérifiées.

Dans la bibliothèque PHP prête à l'emploi, c'est $onetrace->messages()->send(Identity::email('anna@example.com'), 12, ['data' => [...]], 'order-A-1001'), et dans le paquet pour Laravel, messages()->send(...).

Cascade dans un parcours

Ajoutez au parcours le nœud Envoi en cascade du groupe « Actions ». Dans le champ Canaux dans l’ordre, définissez de 2 à 5 étapes. Pour chaque étape, indiquez :

• l'Intégration et le Modèle du canal ;
• Attendre : ce qui compte comme un succès, « envoyé », « remis » ou « lu » ;
• le Délai d’attente : pour « remis » et « lu », 15 minutes par défaut.

La cascade passe à l'étape suivante si :

• le profil n'a pas d'adresse ou de numéro pour le canal, ou si le canal est fermé pour lui : l'étape est sautée immédiatement, aucun message n'est créé ;
• le message n'est pas parti : erreur d'envoi ou omission due aux règles d'envoi ;
• le fournisseur a signalé que le message n'a pas été remis ;
• aucune confirmation de remise ou de lecture n'est arrivée pendant le délai d'attente.

Attendre la remise et la lecture n'est pas possible dans tous les canaux :

Le nœud a deux sorties : arrivé, le message de l'une des étapes a atteint son but ; échec, aucun canal n'a fonctionné. Tant que la cascade est en cours, le participant attend sur le nœud.

L'envoi en cascade transmet un seul et même message. Les modèles de parcours du type « Panier : push → e-mail → SMS » fonctionnent autrement : des messages différents y partent avec des pauses, jusqu'à ce que le client passe commande.

Cascade via l'API

Au lieu de template_id, transmettez steps, les mêmes étapes que dans le nœud du parcours :

{
  "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 accepte sent, delivered ou opened ; les unités de timeout sont minute, hour, day, week. La réponse 202 contient l'id de la cascade, et GET /api/v1/messages/cascades/{id} renvoie son état :

• status : running, reached ou failed ;
• l'étape en cours step ;
• le canal qui a fonctionné, reached_channel ;
• les messages des étapes messages.

Forfait

Les messages transactionnels et l'envoi via l'API sont disponibles avec tous les forfaits. La cascade est disponible à partir du forfait « Croissance », voir Forfait et facturation. Avec « Essentiel », le nœud est marqué d'un cadenas dans la palette de l'éditeur et l'API répond 402. Si le forfait est rétrogradé, seule la première étape de la cascade est envoyée dans les parcours déjà actifs.