SMS-Events

Jede Nachricht durchläuft einen Lebenszyklus, und Bird sendet bei jedem Schritt ein Event. Diese Seite ist das vollständige Event-Vokabular; wie Events an Ihren Endpoint zugestellt werden (Signaturen, Wiederholungsversuche, Replay), behandelt der Webhooks-Leitfaden.

Der Zustellungslebenszyklus als Pfad durch die Event-Typen:

sms.accepted: Bird hat die Nachricht und bereitet die Übergabe an einen Carrier vor.
sms.sent: Bird hat die Nachricht an den Carrier übergeben und wartet auf eine Zustellbestätigung.
Ein terminales Event:
- sms.delivered: Der Carrier hat die Zustellung an das Endgerät bestätigt.
- sms.undelivered: Der Carrier hat eine vorübergehende Nichtzustellung gemeldet, z. B. ein nicht erreichbares Endgerät.
- sms.failed: Ein permanenter Fehler hat die Zustellung verhindert.
- sms.expired: Der Carrier hat die Zustellversuche eingestellt und die Nachricht als abgelaufen gemeldet.

Die terminalen Events liefern die Zustellbestätigung des Carriers, was SMS-Plattformen als Delivery Report oder DLR bezeichnen.

Die Ausnahme ist sms.rejected: Die Nachricht wurde abgelehnt (durch eine Regelprüfung, eine nicht abschließbare Berechnung oder einen Carrier, der sie zurückgewiesen hat) statt versucht und verloren. Eine während der Verarbeitung abgelehnte Nachricht trägt sms.rejected als einziges Event.

Bird empfängt auch Antworten. Wenn ein Abonnent eine Ihrer Nummern per SMS kontaktiert, speichert Bird die Nachricht und sendet sms.received, sodass Sie ohne Polling reagieren können. Das Payload enthält den Nachrichtentext, die Segmentaufschlüsselung, beide Nummern und den Netzbetreiber, wenn der Carrier einen meldet.

Bird prüft die Antwort gegen die Keyword-Regeln für diese Nummer. Ein unterstütztes Stopp-Keyword wie STOP erzeugt eine Sender-und-Abonnenten-Unterdrückung und sendet trotzdem sms.received.

Der Event-Typ type ist ein offenes Enum: Bird kann im Laufe der Zeit neue Event-Typen hinzufügen. Behandeln Sie einen unbekannten type als zukünftiges Event und nicht als Fehler. Matchen Sie die Typen, die Sie verarbeiten, und ignorieren Sie den Rest.

Der Event-Envelope

Events erreichen Ihren Webhook-Endpoint im verschachtelten Standard-Webhooks-Envelope, der im Webhooks-Leitfaden beschrieben ist: drei Felder, type, timestamp und ein typspezifisches data-Objekt. Die Identität des Events steht nicht im Body: Sie wird im webhook-id-Header HTTP transportiert, der über Wiederholungsversuche derselben Zustellung stabil bleibt und Ihr Deduplizierungsschlüssel ist.

Feld	Beschreibung
type	Einer der Event-Typen auf dieser Seite, z. B. sms.delivered
timestamp	Zeitpunkt des Events (RFC 3339); sortieren Sie danach, nie nach Ankunftsreihenfolge, da Zustellungen nicht geordnet sind
data	Eventspezifisches Payload

Das data jedes SMS-Events enthält sms_id, workspace_id und die Adressen to und from. Es gibt außerdem tags und metadata des Sends zurück, sodass Sie Events ohne zusätzlichen Lookup routen und korrelieren können. Jeder Wert ist null, wenn der Send keinen enthielt.

Dasselbe Objekt enthält cost, die Kosten der Nachricht zum Zeitpunkt dieses Events, aufgeteilt in transaction_amount und passthrough_amount mit der Summe in amount. Es ist null bei einem Event, das nichts bepreist hat. Da Zustellungen nicht geordnet sind, mergen Sie cost komponentenweise statt das gesamte Objekt zu ersetzen: Behalten Sie für jede Komponente den Wert des Events mit dem neuesten timestamp. Ein amount summiert nur die Komponenten in seinem eigenen Payload, lesen Sie ihn daher als bisherige Kosten statt als endgültige Summe. Kosten und Abrechnung erläutert die Bedeutung jeder Komponente.

Codebeispiel

{
  "type": "sms.delivered",
  "timestamp": "2026-06-10T14:30:00Z",
  "data": {
    "sms_id": "sms_01krdgeqcxet5s7t44vh8rt9mg",
    "workspace_id": "ws_01krdgeqcxet5s7t44vh8rt9mg",
    "to": "+15551234567",
    "from": "+12025550188",
    "carrier": "Example Wireless",
    "mcc_mnc": "310260",
    "cost": {
      "amount": "0.00990",
      "currency_code": "USD",
      "transaction_amount": "0.00790",
      "passthrough_amount": "0.00200"
    },
    "tags": [{ "name": "campaign", "value": "spring-2026" }],
    "metadata": { "order_id": "ord_123" }
  }
}

Lebenszyklus-Events

sms.accepted

Wird ausgelöst, wenn Bird den Send annimmt und beginnt, ihn an einen Carrier zu übergeben. Das Payload enthält zusätzlich segments, die Aufschlüsselung Bird, die zum Annahmezeitpunkt gezählt wurde; deren count ist die Abrechnungsgrundlage des Sends.

sms.sent

Wird ausgelöst, wenn Bird die Nachricht an den Carrier übergeben hat und auf eine Zustellbestätigung wartet. Das Payload enthält zusätzlich carrier und mcc_mnc (das zustellende Netzwerk und dessen Mobile-Country-/Network-Code). Jeder Wert fehlt statt null zu sein, wenn der Carrier ihn nicht meldet. Um die Verarbeitungslatenz zu messen, vergleichen Sie den timestamp dieses Events mit dem von sms.accepted.

sms.delivered

Der Carrier hat bestätigt, dass die Nachricht das Endgerät erreicht hat. Das Payload enthält zusätzlich carrier und mcc_mnc, die jeweils fehlen, wenn die Zustellbestätigung sie nicht identifiziert hat.

Fehler-Events

Das Payload jedes Fehler-Events enthält zusätzlich ein error-Objekt: einen Bird-stabilen code (z. B. unreachable oder blocked_by_carrier), eine menschenlesbare description, den rohen carrier_error_code, wenn einer geliefert wurde, und occurred_at.

sms.undelivered

Eine nicht permanente Nichtzustellung: Das Endgerät war ausgeschaltet oder nicht erreichbar.

sms.failed

Ein permanenter Zustellungsfehler hat die Nachricht gestoppt.

sms.rejected

Die Nachricht wurde durch Prüfungen von Bird während der Verarbeitung abgelehnt, durch eine nicht abschließbare Berechnung oder durch einen Carrier, der sie zurückgewiesen hat. Eine Ablehnung stoppt die Nachricht, bevor ein Zustellversuch erfolgreich ist. Ein erschöpftes Guthaben endet hier mit dem Fehlercode insufficient_balance, und eine Nachricht, deren Berechnung nicht abgeschlossen werden konnte, wird nicht in Rechnung gestellt.

sms.expired

Der Carrier hat die Zustellversuche eingestellt und die Nachricht als abgelaufen gemeldet. Der Ablauf stammt aus der Zustellbestätigung des Carriers: Bird setzt kein eigenes Gültigkeitsfenster und betreibt keinen Timer, der eine Nachricht beendet. Der error beschreibt, warum die Nachricht noch unzugestellt war, als der Carrier aufgab, in der Regel unreachable: Das Endgerät blieb durchgehend ausgeschaltet oder außerhalb der Netzabdeckung.

Unterdrückungs-Events

Über den Lebenszyklus einzelner Nachrichten hinaus meldet ein Event eine Änderung an der Unterdrückungsliste des Workspace: sms_suppression.created wird ausgelöst, wenn eine Unterdrückung entsteht, sei es durch ein Stopp-Keyword eines Abonnenten, ein vom Carrier gemeldetes Opt-out oder einen manuellen Eintrag. Das Payload enthält die suppression_id, die Nummer des Abonnenten als destination, den originator, an den die Sperre gebunden ist (eine SMS-Unterdrückung ist das exakte Sender-und-Abonnenten-Paar), den reason und den workspace_id, sodass Ihr eigenes System die Liste ohne Polling spiegeln kann:

Codebeispiel

{
  "type": "sms_suppression.created",
  "timestamp": "2026-08-25T14:52:03.192524705Z",
  "data": {
    "suppression_id": "ssu_01krdgeqcxet5s7t44vh8rt9mg",
    "destination": "+15550001234",
    "originator": "+15557654321",
    "reason": "keyword_stop",
    "workspace_id": "ws_01ky7m21hjffh9s8kq76gyb1xf"
  }
}

Ein workspace-weites Opt-out, das auf dem Preferences-Tab erfasst wurde, ist eine erklärte Präferenz und keine Unterdrückung und löst dieses Event nicht aus.

Die Timeline einer Nachricht lesen

Webhooks liefern Events an Ihre Systeme. Für eine einmalige Überprüfung rendert das SMS-Log denselben Stream als Timeline mit Zeitstempeln, Carrier-Details und Fehlern. Um die Timeline programmatisch abzurufen, rufen Sie GET /v1/sms/messages/{message_id}/events auf. Um nur den aktuellen Status zu lesen, rufen Sie GET /v1/sms/messages/{message_id} auf.

Nächste Schritte

Webhooks & Events: Endpoint einrichten, Signaturen verifizieren und Wiederholungsversuche sowie Replay handhaben.
SMS-Log: Die Timeline pro Nachricht einsehen, die diese Events erzeugen.
SMS senden: Die Felder tags und metadata setzen, die bei jedem Event zurückgegeben werden.

Verwandte Ressourcen