Sign inGet Started

SMS senden

Diese Anleitung behandelt den Einzel-Sende-Endpunkt POST /v1/sms/messages. Erstellen Sie ein JSON-Payload mit Empfänger, Absender, Nachrichtentext und Kategorie. Bird gibt 202 Accepted mit einer Nachrichten-ID zurück und stellt asynchron zu. Jede Anfrage sendet eine Nachricht an einen Empfänger. Um viele Nachrichten auf einmal zu senden, verwenden Sie Batch-Versand. Um ein Template statt eines eigenen Texts zu senden, übergeben Sie ein template-Objekt anstelle von text, category und from.

Vor dem Senden: Zielland aktivieren

Ihr Workspace hat eine Ziel-Allowlist mit Default-Deny, die anfangs nur das Heimatland Ihrer Organisation enthält. Bird lehnt einen Versand in jedes andere Land mit 422 SMSDestinationNotEnabled ab, bevor ein Absender aufgelöst wird. Aktivieren Sie die Länder, die Sie bedienen, unter SMS > Destinations im Dashboard.

Ein minimaler Versand

Das kleinste gültige Freitext-Payload besteht aus einem to-Empfänger, einem from-Absender, einem text-Nachrichtentext und einer category.
const msg = await bird.sms.send({
  from: "+15557654321",
  to: "+14155550100",
  text: "Your verification code is 123456.",
  category: "authentication",
});
console.log(msg.id, msg.status);
Verwenden Sie Ihren regionalen Host (https://us1.platform.bird.com oder https://eu1.platform.bird.com) mit einem passenden bk_{region}_...-Schlüssel. Die Antwort ist die akzeptierte Nachricht:
Codebeispiel
{
  "id": "sms_01ky7qmwgpfkybj9ecrnwjx714",
  "direction": "outbound",
  "status": "accepted",
  "to": "+31612345678",
  "from": "Bird",
  "text": "Your Bird verification code is 481920. It expires in 10 minutes.",
  "category": "authentication",
  "segments": { "count": 1, "encoding": "GSM_7BIT", "characters": 64 },
  "cost": null,
  "carrier": null,
  "mcc_mnc": null,
  "sent_at": null,
  "delivered_at": null,
  "created_at": "2026-07-23T14:56:34.326Z"
}
status: accepted bedeutet, dass Bird die Nachricht hat und sie verarbeitet; cost ist null, weil die Preisermittlung während der Verarbeitung stattfindet. Was danach passiert, wird unter Das asynchrone Modell beschrieben.

Aufbau des Payloads

Empfänger

to ist ein Empfänger im E.164-Format: ein führendes +, Landesvorwahl und Teilnehmernummer, zum Beispiel +31612345678. Eine Nachricht geht an einen Empfänger, ohne cc, bcc oder Empfänger-Array. Um viele Personen zu erreichen, senden Sie einen Batch.

Absender

from ist bei einem Freitext-Versand erforderlich und ist der Absender, den der Empfänger sieht. Es gibt zwei Formen, und welche davon funktionieren, hängt vom Zielland ab:
  • Eine alphanumerische Absenderkennung: 3 bis 11 Buchstaben, Ziffern, Leerzeichen, Bindestriche, Unterstriche oder Punkte, mit mindestens einem Buchstaben und ohne Trennzeichen am Anfang oder Ende, z. B. Bird oder Acme-Co. Sie muss einen Buchstaben enthalten – eine reine Ziffernfolge mit Satzzeichen wie 555 555 wird abgelehnt. Einige Länder verlangen eine Registrierung, andere, darunter die USA, unterstützen alphanumerische Absenderkennungen nicht. Empfänger können nicht darauf antworten.
  • Eine Nummer, die Ihrem Workspace gehört, im E.164-Format oder als reine Ziffern. Jeder rein numerische from wird als Nummer interpretiert und unter Ihren Absendern nachgeschlagen, daher wird eine beliebige Nummer, die Ihnen nicht gehört, abgelehnt. Ob sie als Long Code, gebührenfreie Nummer oder Short Code fungiert, ergibt sich aus der Nummer selbst, nicht aus der Anzahl der eingegebenen Ziffern. Ein 6-stelliger from ist nicht deshalb ein Short Code, weil er 6 Ziffern hat; er ist ein Short Code, wenn die Nummer, die Sie besitzen, einer ist.
Ein Absender, der für das Zielland nicht gültig ist, wird mit einem 422 abgelehnt, der den Grund nennt (zum Beispiel SMSAlphaNotSupported, wenn alphanumerische Absender nicht verfügbar sind). Bei einem Template-Versand wird from nicht akzeptiert: Bird wählt einen Absender für das Zielland und die Kategorie aus.
Das Beanspruchen einer Absenderkennung, die Anforderungen einzelner Länder und die länderspezifische Registrierung werden unter SMS-Absenderkennungen beschrieben.

Nachrichtentext und Kategorie

text ist der Nachrichtentext, mindestens ein Zeichen. Er wird in Segmenten abgerechnet und zugestellt; ein Versand ist auf 12 Segmente begrenzt (etwa 1.836 GSM-7-Zeichen oder 804 bei erweiterter UCS-2-Kodierung). Ein Nachrichtentext über der Obergrenze wird mit einem 422 abgelehnt, nicht gekürzt.
category ist bei einem Freitext-Versand erforderlich und klassifiziert die Nachricht als transactional, marketing, authentication oder service. Es teilt Bird und den Carriern mit, warum Sie senden. Ein Einmal-Bestätigungscode verwendet authentication; eine Werbeaktion verwendet marketing. Wählen Sie die Kategorie, die zum Zweck der Nachricht passt.

Tags und Metadaten

Beide hängen eigene Daten an einen Versand an, dienen aber unterschiedlichen Zwecken:
  • tags sind strukturierte {name, value}-Paare (max. 20 pro Versand; Name 1 bis 32 Zeichen, Wert 1 bis 64, nur ASCII [A-Za-z0-9_-], Groß-/Kleinschreibung wird unterschieden, Namen innerhalb eines Versands eindeutig). Sie sind vollwertige Filterdimensionen: Filtern Sie die Nachrichtenliste nach Tag. Verwenden Sie sie für Labels mit niedriger Kardinalität wie campaign oder experiment_variant.
  • metadata ist ein beliebiges JSON-Objekt (max. 2 KB serialisiert). Es wird gespeichert, bei API-Lesezugriffen zurückgegeben und bei jedem Webhook-Event mitgesendet, ist aber keine Filterdimension. Verwenden Sie es für Roundtrip-Kontext: interne IDs, Fremdschlüssel oder alles, was Sie mit jedem Event zurückerhalten möchten.
Codebeispiel
{
  "tags": [{ "name": "campaign", "value": "spring-2026" }],
  "metadata": { "user_id": "usr_12345", "order_id": "ord_98765" }
}

Feldreferenz

FeldTypErforderlichEinschränkungen / Hinweise
tostring (E.164)jaEin Empfänger pro Nachricht
fromstringja*Eigene E.164-Nummer, alphanumerische Absenderkennung (3–11 Zeichen, mindestens ein Buchstabe) oder Short Code (5–6 Ziffern)
textstringja*Mindestens 1 Zeichen; begrenzt auf 12 Segmente
categorystringja*transactional, marketing, authentication oder service
tags{name, value}[]neinMax. 20; Name 1–32 Zeichen, Wert 1–64 Zeichen; nur [A-Za-z0-9_-]
metadataobjectneinBeliebiges JSON, max. 2 KB serialisiert
optionsobjectneinVerarbeitungseinstellungen pro Nachricht. smart_encoding ist die einzige verfügbare; siehe Segmente und Kodierung
* Erforderlich bei einem Freitext-Versand. Ein Template-Versand liefert Nachrichtentext, Kategorie und Absender aus dem Template und lehnt diese drei Felder ab.

Versand mit einem Template

Statt text selbst zu verfassen, setzen Sie das template-Objekt des Versands auf eines der integrierten Templates von Bird. Das Template liefert den Nachrichtentext, die Kategorie und den Absender, daher werden text, category, from und media_urls nicht zusammen damit akzeptiert. Der Katalog, die Variablen jedes Templates und der vollständige Template-Versand-Vertrag befinden sich unter SMS-Templates.

Segmente und Kodierung

SMS wird pro Segment abgerechnet. Eine Nachricht, die in die GSM-7-Kodierung passt, erhält 160 Zeichen pro einzelnem Segment; UCS-2 (ausgelöst durch Emoji, CJK oder andere Nicht-GSM-Zeichen) reduziert auf 70. Längere Nachrichten werden in Multipart-Segmente mit etwas niedrigeren Grenzen pro Segment aufgeteilt. Jede Antwort enthält die aufgelösten segments: die abrechenbaren count, die encoding und die Zeichenanzahl. Segmente sind die Einheit, nach der abgerechnet wird; siehe Kosten.
Wenn typografische Zeichen der einzige Grund sind, warum ein Nachrichtentext außerhalb von GSM-7 fällt, kann intelligente Kodierung die Segmentanzahl reduzieren. Setzen Sie options.smart_encoding auf true, und Bird ersetzt typografische Anführungszeichen, Gedankenstriche, Auslassungspunkte und ähnliche Zeichen vor dem Senden durch GSM-7-Äquivalente. Sie ist standardmäßig deaktiviert, weil sie den von Ihnen verfassten Text verändert.
Den vollständigen Zeichensatz, Erweiterungstabellen-Zeichen mit doppeltem Platzbedarf, Emoji-Größen, was die intelligente Kodierung ersetzt, und die Segment-Berechnung finden Sie unter Zeichenlimits.

Batch-Versand

POST /v1/sms/batches sendet bis zu 100 unabhängige Nachrichten in einer Anfrage. Batch-Anfragen verwenden die sms_batch-Richtlinie zur Begrenzung der Anfragerate, getrennt von der sms_send-Richtlinie für Einzelversand. Der Body ist ein JSON-Objekt, dessen messages-Array die Nachrichtenobjekte aus Payload aufbauen enthält:
const result = await bird.sms.sendBatch({
  messages: [
    {
      from: "+15557654321",
      to: "+15551111111",
      text: "Hi Alice!",
      category: "marketing",
    },
    {
      from: "+15557654321",
      to: "+15552222222",
      text: "Hi Bob!",
      category: "marketing",
    },
  ],
});
Die Validierung ist alles oder nichts: Ist eine Nachricht im Batch ungültig, wird die gesamte Anfrage mit einem 422 abgelehnt und nichts gesendet – ein Batch wird also nie teilweise ausgeführt. Bei Erfolg enthält die 202-Antwort jede akzeptierte Nachricht in Einreichungsreihenfolge unter data sowie ein summary mit dem accepted_count. Ab diesem Punkt ist jede Nachricht unabhängig: Der Fehler eines Empfängers wirkt sich nie auf die anderen aus.

Das asynchrone Modell: Was 202 bedeutet

Ein erfolgreicher Versand gibt 202 Accepted mit einer Nachrichten-ID und status: accepted zurück. Anfragefehler werden sofort zurückgegeben: Ein ungültiges Feld, ein Body über dem Segment-Limit, ein Zielland, das Sie nicht aktiviert haben, oder ein ungültiger Absender liefert ein 422. Ein Workspace ohne Wallet-Guthaben erhält ein 402.
Die Zustellung erfolgt asynchron. Die Nachricht wechselt zu sent, wenn Bird sie an den Carrier übergibt. Eine Zustellbestätigung setzt dann delivered, undelivered, failed oder expired über Events und Webhooks und die Lese-Endpunkte. Dieses Design hat drei Konsequenzen:
  • Kosten werden nach der Annahme berechnet. Das cost einer Nachricht ist zum Zeitpunkt der Annahme null und wird gefüllt, sobald Bird den Versand während der Verarbeitung bepreist. Lesen Sie die Nachricht zurück oder warten Sie auf das Zustellungs-Event, um die bisherige Gebühr zu sehen; Kosten und Abrechnung beschreibt die Komponenten und wann eine unbepreist bleibt.
  • Eine Nachricht kann nach dem 202 abgelehnt werden. Schlägt die Belastung während der Verarbeitung fehl, endet die Nachricht als rejected mit einem sms.rejected-Webhook und Ihnen wird nichts berechnet; ein erschöpftes Wallet erscheint als last_error.code: insufficient_balance.
  • Lesezugriffe können kurz hinter dem 202 zurückbleiben. Die Nachricht wird auf den Lese-Endpunkten kurz nach dem 202 sichtbar, sodass sich ein 404 unmittelbar nach dem Versand innerhalb von Momenten von selbst auflöst.

Reservierte Felder

Bird lehnt die folgenden Anfragefelder derzeit mit 422 SMSUnsupportedFeature ab:
scheduled_at, validity_period, media_urls, messaging_profile_id, broadcast_id, campaign_id, audience_id, contact_id, topic_id, personalization, options.max_price_per_segment, options.track_clicks
Fügen Sie diese Felder nicht in einen Versand ein.

Sicheres erneutes Senden

Senden Sie den Idempotency-Key-Header mit einem eindeutigen Wert pro logischem Versand. Wenn eine Anfrage erfolgreich ist, aber keine Antwort zurückgibt, wiederholen Sie dieselbe Anfrage mit demselben Schlüssel. Bird gibt das ursprüngliche Ergebnis zurück, anstatt eine doppelte Nachricht zu senden. Siehe Idempotenz für Schlüsselformat und Aufbewahrungsdauer.

Kosten und Abrechnung

Ausgehende SMS wird pro Segment abgerechnet. Was Sie zahlen, hängt vom Zielland und Carrier ab; einige Routen enthalten einen Drittanbieter-Zuschlag, z. B. US-10DLC-Carrier-Gebühren.
Das cost einer Nachricht gliedert die Gebühr in benannte Komponenten. transaction_amount ist das, was Bird für den Transport der Nachricht berechnet hat, passthrough_amount ist eine weitergegebene Drittanbieter-Gebühr, und amount ist die Summe der bepreisten Komponenten in currency_code. Eine Komponente, die noch nicht bepreist wurde, ist null statt "0.00000" – eine Nachricht, deren Zuschlag nie aufgelöst wurde, meldet amount also nur als Transportgebühr. Die Nachrichtenreferenz dokumentiert jedes Feld.
Der Zuschlag wird nach bestem Aufwand ermittelt. Bird löst ihn auf, während die Zustellbestätigung erfasst wird, innerhalb eines begrenzten Zeitfensters. Wird er in diesem Fenster nicht aufgelöst, bleibt passthrough_amount dauerhaft null: Bird versucht es nicht erneut, und amount bleibt die Transportgebühr.
Eingehende SMS wird auf zwei Posten abgerechnet: der Eingangsrate pro Segment und einem eingehenden Carrier-Zuschlag, sofern einer anfällt. Beide werden im cost der empfangenen Nachricht ausgewiesen: die Rate als transaction_amount, der Zuschlag als passthrough_amount. Anders als beim ausgehenden Gegenstück wird der eingehende Zuschlag bei Annahme der Nachricht bepreist, nicht bei der Zustellung, und wird daher nie nachträglich ergänzt.
Überprüfen Sie Kosten und Segmente pro Nachricht im SMS-Log.

Nächste Schritte

  • SMS-Vorlagen: Senden Sie eine integrierte Vorlage und lassen Sie Bird den Absender auswählen.
  • SMS-Log: Finden Sie eine Nachricht und prüfen Sie ihren Lebenszyklus, ihre Segmente und Kosten.
  • Events: Empfangen Sie Zustellungs-Events in Ihren Systemen.
  • SMS-Metriken: Überwachen Sie Zustellrate, Fehlerrate und akzeptiertes Volumen.
  • Idempotenz: Sicher erneut versuchen mit dem Idempotency-Key-Header.
  • Ihre erste SMS senden: Ein Video, das dasselbe Setup im Dashboard Schritt für Schritt zeigt