Transaktionale Nachrichten und Kaskaden

Transaktionale Nachrichten sind Bestellbestätigungen, Anmeldecodes und Versandbenachrichtigungen. Der Kunde wartet auf sie, deshalb werden sie sofort und über eine eigene Warteschlange gesendet: Eine große Kampagne hält sie nicht auf. Eine Kaskade sendet eine Nachricht nacheinander über mehrere Kanäle. Zum Beispiel zuerst WhatsApp und, wenn die Nachricht nicht innerhalb von 2 Minuten zugestellt wurde, SMS.

Eine solche Nachricht können Sie aus einer Journey oder von Ihrem eigenen Server über die API senden.

Transaktionale Vorlage

Damit eine Nachricht als transaktional gilt, aktivieren Sie in ihrer Vorlage die Option Transaktionale Nachricht. Eine solche Nachricht wird ohne Prüfung von Abonnement, Frequenzlimits und Ruhezeiten gesendet. E-Mails über den Mail-Dienst von OneTrace.ru werden ohne Aufwärmen und in einem eigenen Strom gesendet, ohne Abmeldelink in den Headern.

Markieren Sie Werbung nicht so: Das verletzt die Rechte der Empfänger und schadet Ihrer Absenderreputation.

Auch eine transaktionale Nachricht wird nicht gesendet, wenn der Kanal beim Empfänger geschlossen ist:

Eine solche Nachricht erhält den Status „Übersprungen“ mit dem Grund „Kanal für den Empfänger gesperrt“. Der Kanal öffnet sich wieder, wenn der Kunde sich erneut anmeldet – zum Beispiel im Bot auf „Start“ tippt. Eine Spam-Beschwerde schließt den Kanal nicht: E-Mails zu Bestellungen an diese Adresse kommen weiterhin an.

Senden über die API

Ihr Server sendet eine Nachricht mit der Anfrage POST /api/v1/messages. Sie benötigen einen geheimen Schlüssel mit der Berechtigung „Einzelne Nachrichten senden“, siehe API-Schlüssel.

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}
  }'

Die Antwort 202 enthält die id der Nachricht und ihren Status. Den aktuellen Status liefert GET /api/v1/messages/{id}: queued, sent, delivered, failed, skipped und andere, mit dem Grund für das Überspringen oder den Fehler.

• Wiederholen ist sicher. Eine Anfrage mit demselben Header Idempotency-Key gibt die bereits erstellte Nachricht zurück, eine zweite wird nicht gesendet. Verwenden Sie die Bestellnummer oder die ID des Vorgangs.
• Limit pro Empfänger – 20 Nachrichten pro Stunde über die API. Bei Überschreitung kommt 429 mit dem Header Retry-After.
• Eine normale Vorlage ohne die Option „Transaktional“ lässt sich ebenfalls über die API senden. Dann werden alle Versandregeln geprüft.

In der fertigen PHP-Bibliothek ist das $onetrace->messages()->send(Identity::email('anna@example.com'), 12, ['data' => [...]], 'order-A-1001'), im Laravel-Paket messages()->send(...).

Kaskade in einer Journey

Fügen Sie der Journey den Knoten Kaskadierte Nachricht aus der Gruppe „Aktionen“ hinzu. Legen Sie im Feld Kanäle der Reihe nach 2 bis 5 Schritte fest. Geben Sie für jeden Schritt an:

• Integration und Vorlage des Kanals.
• Warten bis – was als Erfolg gilt: „gesendet“, „zugestellt“ oder „gelesen“.
• Wartezeit – für „zugestellt“ und „gelesen“, standardmäßig 15 Minuten.

Die Kaskade geht zum nächsten Schritt über, wenn:

• das Profil keine Adresse oder Nummer für den Kanal hat oder der Kanal bei ihm geschlossen ist – der Schritt wird sofort übersprungen, es wird keine Nachricht erstellt;
• die Nachricht nicht gesendet wurde: Sendefehler oder Überspringen nach den Versandregeln;
• der Anbieter gemeldet hat, dass sie nicht zugestellt wurde;
• innerhalb der Wartezeit keine Zustell- oder Lesebestätigung eingegangen ist.

Auf Zustellung und Lesen lässt sich nicht in allen Kanälen warten:

Der Knoten hat zwei Ausgänge: erreicht – die Nachricht eines der Schritte hat ihr Ziel erreicht; fehlgeschlagen – kein Kanal hat funktioniert. Solange die Kaskade läuft, wartet der Teilnehmer am Knoten.

Eine kaskadierte Nachricht stellt ein und dieselbe Nachricht zu. Journey-Vorlagen wie „Warenkorb: Push → E-Mail → SMS“ funktionieren anders: Dort werden verschiedene Nachrichten mit Pausen gesendet, bis der Kunde bestellt.

Kaskade über die API

Übergeben Sie statt template_id die steps – dieselben Schritte wie im Journey-Knoten:

{
  "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 akzeptiert sent, delivered oder opened, die Einheiten von timeout sind minute, hour, day, week. Die Antwort 202 enthält die id der Kaskade, GET /api/v1/messages/cascades/{id} liefert ihren Zustand:

• status – running, reached oder failed;
• der aktuelle Schritt step;
• der Kanal, der funktioniert hat – reached_channel;
• die Nachrichten der Schritte messages.

Tarif

Transaktionale Nachrichten und das Senden über die API sind in allen Tarifen verfügbar. Kaskaden ab dem Tarif „Wachstum“, siehe Tarif und Abrechnung. Im Tarif „Start“ ist der Knoten in der Palette des Editors mit einem Schloss markiert, und die API antwortet mit 402. Wird der Tarif herabgestuft, senden bereits laufende Journeys nur den ersten Schritt der Kaskade.