SMS senden
Eine API für jeden Text, den Sie senden.
Senden Sie transaktionale Nachrichten und Benachrichtigungen über Bird. Geben Sie Ihren Text und Absender an oder verwenden Sie ein Template; prüfen Sie Kodierung und Segmentanzahl in der Antwort. Fügen Sie einen Idempotency-Key für sichere Wiederholungen hinzu und verfolgen Sie die Zustellung über signierte Webhooks.
Eine Nachricht. Ein sichtbares Ergebnis.
Beispielversand
Sehen Sie die Annahme und eine spätere Carrier-Bestätigung. Dieses Beispiel sendet keine SMS; die Zustellung belegt nicht, dass jemand sie gelesen hat.
Täglich vertraut von Teams, die erstklassige Software entwickeln
Weitere Kundenberichte lesenTesten Sie Ihre erste SMS-Integration.
Aus der Sprache, die Sie bereits verwenden.
Das Senden ist der Kern der Bird SMS API. Das folgende Beispiel zeigt die Struktur der Anfrage. Für einen kontrollierten Test ersetzen Sie den Empfänger durch die dokumentierte Sandbox-Nummer +15005550006. Richten Sie einen geeigneten US-Absender ein und aktivieren Sie zuerst das Zielland, dann prüfen Sie Annahme- und Zustellereignisse, bevor Sie an Kunden senden.
const msg = await bird.sms.send({
from: "+15557654321",
to: "+14155550100",
text: "Your verification code is 123456.",
category: "authentication",
});
console.log(msg.id, msg.status);Ein SMS-Versand übermittelt den von Ihnen angegebenen Text. Für Login- und Kontoverifizierung verwenden Sie Bird Verify, um Codes im Rahmen eines Verifizierungsprozesses zu generieren, ablaufen zu lassen und zu prüfen.
Bauen Sie auf einem klaren Sendevertrag auf.
Bereiten Sie die Anfrage vor und verfolgen Sie das Ergebnis.
- 01
Segmentzählung vor dem Versand.
Bird gibt die berechnete Kodierung und Segmentanzahl in der Antwort zurück. Verwenden Sie den Segmentrechner, um einen Entwurf vor dem Absenden zu prüfen.
- 02
GSM-7 und Unicode, für Sie entschieden.
Die Zeichen bestimmen die Kodierung. GSM-7 fasst 160 Einheiten in ein einzelnes Segment; Unicode fasst 70. Mehrteilige Nachrichten reservieren Platz für die Zusammensetzung, und Emoji können mehr als eine Einheit belegen.
- 03
In einem Aufruf bündeln.
Senden Sie bis zu 100 unabhängige Nachrichten in einem Batch. Die Validierung erfolgt vor dem Einreihen; jede akzeptierte Nachricht hat dann ihr eigenes Ergebnis.
- 04
Wiederholen Sie die Anfrage mit einem Idempotency-Key.
Verwenden Sie einen Idempotency-Key pro logischer Anfrage und nutzen Sie ihn bei einer identischen Wiederholung erneut. Die gespeicherte API-Antwort kann wiedergegeben werden; dies garantiert keine Exactly-once-Zustellung durch den Carrier.
- 05
Zustellereignisse für Ihre Anwendung.
Abonnieren Sie Ereignisse für Annahme, Versand und Endergebnis. Verifizieren Sie Signaturen, deduplizieren Sie Webhook-Wiederholungen und nutzen Sie Lesebestätigungen, um fehlende oder verzögerte Beobachtungen zu untersuchen.
Bringen Sie die Integration mit einem kontrollierten Test voran.
Ordnen Sie Ihre aktuellen Anfragefelder, Absenderregistrierungen und die Ereignisverarbeitung Bird zu. Gleichen Sie Opt-outs ab, bevor Sie Traffic verschieben, und vergleichen Sie dann einen kontrollierten Test, bevor Sie das Produktionsrouting ändern.
import twilio from "twilio";
const client = twilio(accountSid, authToken);
await client.messages.create({
from: "+14155550172",
to: "+15005550006",
body: "Your code is 123456.",
});import { BirdClient } from "@messagebird/sdk";
const bird = new BirdClient({ apiKey: process.env.BIRD_API_KEY! });
await bird.sms.send({
from: "+14155550172",
to: "+15005550006",
text: "Your code is 123456.",
category: "authentication",
});Kennen Sie die Segmentanzahl vor dem Absenden.
GSM-7 fasst 160 Septetts in ein einzelnes Segment; UCS-2 fasst 70 Code-Einheiten. Die Mehrteilkapazität beträgt 153 bzw. 67. Erweiterte GSM-7-Zeichen belegen zwei Septetts, und Emoji können zwei Code-Einheiten belegen. Bird gibt Kodierung und Segmente bei der Annahme zurück; der geltende Tarif und etwaige Carrier-Gebühren werden separat berechnet.
const { data, error } = await bird.sms.send({
from: "Bird",
to: "+31612345678",
text: "Your code is 123456.",
category: "authentication",
}).safe();
if (error) throw error;
console.log(data.segments);
// → { characters: 20, count: 1, encoding: "GSM_7BIT" }
Eine Nachricht oder hundert, ein Aufruf.
Fassen Sie bis zu 100 unabhängige Nachrichten in einem Batch zusammen, jede mit eigenem Empfänger und Text. Ungültige Eingaben lehnen die Anfrage vor dem Einreihen ab. Nach einer erfolgreichen 202-Antwort können Verarbeitung und Zustellung für jede SMS einzeln gelingen oder fehlschlagen. Verwenden Sie dieselbe Anfrage und denselben Idempotency-Key bei Wiederholungen innerhalb des dokumentierten Aufbewahrungsfensters.
const { data: batch, error } = await bird.sms
.sendBatch(
users.map((u) => ({
from: "Bird",
to: u.phone,
text: `Hi ${u.name}, your appointment is tomorrow at ${u.time}.`,
})),
{ idempotencyKey: `reminders-${runId}` },
)
.safe();
if (error) throw error;
console.log(`queued ${batch.data.length} messages`);Verfolgen Sie die Annahme bis zum gemeldeten Ergebnis.
Eine erfolgreiche Anfrage gibt 202 Accepted zurück. Abrechnung und Carrier-Übermittlung erfolgen später und können noch fehlschlagen. Konsumieren Sie signierte Zustellereignisse und prüfen Sie den Nachrichtendatensatz bei der Untersuchung des Ergebnisses.
import { bird } from "@/lib/bird";
export async function POST(req: Request) {
const event = bird.webhooks.unwrap(
await req.text(),
Object.fromEntries(req.headers),
);
switch (event.type) {
case "sms.delivered":
await markDelivered(event.data.sms_id);
break;
case "sms.failed":
await flag(event.data.to, event.data.error?.description);
break;
}
return new Response(null, { status: 204 });
}Untersuchen Sie Fehler anhand des gemeldeten Grundes. Unterstützte STOP-Schlüsselwörter und Carrier-Opt-outs erzeugen Sperrungen; andere Zustellfehler werden nicht automatisch zu einem Opt-out.
sms.acceptedVon der API akzeptiert und für die Carrier-Übergabe in die Warteschlange gestellt.sms.sentAn das SMSC des Ziel-Carriers übermittelt.sms.deliveredZustellbestätigung vom Carrier erhalten (DLR).sms.failedEin terminaler Fehler für diesen SMS-Versuch. Prüfen Sie den gemeldeten Fehler und den Nachrichtenverlauf.
Vertiefen Sie sich in der Dokumentation.
Verdrahten Sie Webhooks, machen Sie jeden Versand mit Idempotenz-Keys sicher wiederholbar und lesen Sie die Fehlerreferenz, damit Sie jeden Fehlschlag auf die richtige Weise behandeln.
In die Praxis umsetzen.
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema. Die Ressourcen sind auf Englisch.
Fragen, bevor Sie loslegen
Wähle ich den Absender?
Wie vermeiden Wiederholungsversuche eine doppelte Nachricht?
Bedeutet „akzeptiert
Ist ein Batch dasselbe wie ein Broadcast?
Der Rest der SMS-Plattform
Eine API, ein Satz Keys. Entdecken Sie die anderen Funktionen.
Erstellen Sie den vollständigen Messaging-Workflow.
Verbinden Sie den SMS-Versand mit den Absender-, Ziel- und Zustellkontrollen, die Ihre Anwendung benötigt. Bereiten Sie die Integration vor, bevor Sie an Kunden senden.