SMS von einem anderen Anbieter migrieren

1. Zielländer aktivieren
2. Absender einrichten
3. Den Send-Call abbilden auf POST /v1/sms/messages
4. Opt-out-Liste übernehmen
5. Zustellberichte auf Webhooks umstellen
6. Gegen simulierte Ziele testen vor dem Cutover

1. Zielländer aktivieren

2. Absender einrichten

• Alphanumerische Sender-IDs erstellen Sie selbst unter SMS > Senders. Wenn das Zielland eine Registrierung der Sender-ID verlangt, reichen Sie die Registrierung dort ein und warten Sie auf die Genehmigung, bevor Sie Traffic darüber routen.
• US-Geschäfts-Traffic über lokale Long Codes erfordert die entsprechende 10DLC-Marke und -Kampagne, eingerichtet unter SMS > 10DLC. Toll-Free-Nummern und dedizierte Short Codes haben eigene Verifizierungs- oder Antragsprogramme. Die USA akzeptieren alphanumerische Sender-IDs grundsätzlich nicht, eine europäische Sender-ID, die überall sonst funktioniert, hat also kein US-Äquivalent.
• Nummern erhalten Sie über den Numbers-Workflow, wobei Verfügbarkeit und verwaltete Bereitstellung vom Typ und Zielland abhängen. Prüfen Sie SMS-Nummern für den richtigen Weg; das Anlegen eines alphanumerischen Absenders beschafft keine Nummer.
• Bestehende Nummern behalten ist kein Self-Service: Bird hat keinen Port-in-Flow, den Sie über das Dashboard steuern können. Wenn Ihre Abonnenten auf Nummern antworten, die Sie heute besitzen, klären Sie den Port mit dem Support, bevor Sie ein Cutover-Datum festlegen, und planen Sie Port und Codeänderung als getrennte Vorgänge.

3. Den Send-Call abbilden

• Ein Empfänger pro Request. Bird hat kein Recipients-Array. Wenn Ihr bisheriger Anbieter einen Call an viele Nummern verteilt, wird daraus ein Call pro Empfänger oder ein Batch unabhängiger Nachrichten in einem einzelnen Request.
• category ist bei Freitext erforderlich, und zwar transactional, marketing, authentication oder service. Die meisten Anbieter leiten die Absicht aus der Kampagne oder dem Absender ab; hier deklarieren Sie sie pro Nachricht. Wenn ein Zielland eine Registrierung des Absenders verlangt, ist diese Registrierung für eine Kategorie genehmigt, und ein Versand außerhalb dieser Kategorie wird mit 422 SenderCategoryNotPermitted abgelehnt. Beachten Sie: Der active-Status des Absenders kann Ihnen das nicht im Voraus sagen, weil er ohne Bezug zu einer Kategorie gemeldet wird; lesen Sie stattdessen die länderspezifischen Anforderungen. Setzen Sie das beim Port richtig um, statt alles auf einen Wert zu setzen.
• Der Body ist in Segmenten begrenzt, und Bird kürzt nicht. Ein zu langer Body wird mit einem 422 abgelehnt. Nicht-GSM-7-Zeichen reduzieren die Kapazität eines Segments um mehr als die Hälfte. Wenn Ihr bisheriger Anbieter geschwungene Anführungszeichen und Bindestriche stillschweigend transliteriert hat, setzen Sie options.smart_encoding, um die gewohnten Segmentzahlen beizubehalten. Die Option ist standardmäßig deaktiviert, weil sie den von Ihnen verfassten Body verändert.
• Verwenden Sie tags für Filterdimensionen und metadata für Kontext. Tags sind {name, value}-Paare, nach denen Sie Analytics filtern und aufschlüsseln können; Metadata sind beliebige JSON, die Bird speichert, bei Reads zurückgibt und bei jedem Webhook-Event mitliefert. Ein einzelnes Client-Referenzfeld bei Ihrem alten Anbieter entspricht in der Regel metadata.
• Einzelversand-Scheduling und ausgehende MMS erfordern einen separaten Plan. scheduled_at, media_urls, validity_period und empfängerspezifische personalization sind reservierte Felder, die mit 422 SMSUnsupportedFeature abgelehnt werden. Diese Teile Ihrer Integration lassen sich nicht mit dem Rest umziehen: Halten Sie geplante Versendungen in Ihrer eigenen Queue und rufen Sie den Send-Endpoint zum vorgesehenen Zeitpunkt auf. Für Zielgruppen-Kampagnen evaluieren Sie Broadcasts separat; ein Broadcast ist kein Endpoint-Feld-Rename.
• Verwenden Sie Idempotency-Key für begrenzte Retries. Senden Sie einen eindeutigen Key pro logischer Nachricht und nutzen Sie ihn für Retries des identischen Requests innerhalb des dreistündigen Replay-Fensters. Replays reduzieren doppelte Requests, sind aber keine Exactly-once-Zustellgarantie. Siehe Idempotency.

4. Opt-out-Liste übernehmen

while IFS=, read -r destination originator; do
  curl -s -X POST https://us1.platform.bird.com/v1/sms/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"destination\": \"$destination\", \"originator\": \"$originator\"}"
done < opt-outs.csv

• Beide Enden sind für absenderspezifische Suppressions erforderlich. Ein Workspace-weites Opt-out gehört zum separaten Preference Owner. Der Call ist idempotent: 201 legt eine neue Suppression an, 200 gibt die bereits vorhandene manuelle Suppression zurück. Ein erneutes Ausführen eines teilweisen Imports ist also sicher.
• Importierte Paare erhalten reason: manual, was jede Kategorie einschließlich transaktionaler blockiert. Das ist strenger als eine Suppression, die Bird selbst über ein Stop-Keyword aufzeichnet. Wenn ein Abonnent nur Marketing abgelehnt hat, entscheiden Sie bewusst, ob Sie dieses Paar importieren.

5. Zustellberichte auf Webhooks umstellen

• Zustellungen werden gemäß Standard Webhooks signiert, mit den Headern webhook-id, webhook-timestamp und webhook-signature und einem HMAC-SHA256 über {id}.{timestamp}.{raw body}. Anbieter, die mit einem eigenen Schema signieren, erfordern einen Austausch der Signaturprüfung; die Anleitung dazu steht unter Webhooks & Events.
• Die Zustellung erfolgt at-least-once und ungeordnet. Deduplizieren Sie anhand von webhook-id und sortieren Sie nach dem Payload-timestamp, nie nach Ankunftsreihenfolge.

6. Gegen simulierte Ziele testen

• Es handelt sich um US-Nummern, daher müssen die Vereinigten Staaten unter Destinations aktiviert sein, und from muss ein für die USA gültiger Absender sein. Eine alphanumerische Sender-ID wird dort abgelehnt.
• Ein simulierter Versand wird berechnet, zum normalen Tarif des Ziellandes. Nichts erreicht ein Endgerät, aber die Wallet-Belastung ist real. Dimensionieren Sie Ihren Smoke-Test entsprechend.
• Das Ergebnis ergibt sich allein aus dem Ziel. Es gibt kein separates Test-Credential und keinen Testmodus, den Sie ausschalten müssten.

Von einem bestimmten Anbieter migrieren

• Twilio: formkodierter PascalCase zu JSON, Messaging Services zu Absendern, StatusCallback zu abonnierten Webhooks
• Plivo: src und dst zu from und to, Powerpacks zu Absendern, DND-Paare zu Suppressions
• Telnyx: der ähnlichste Send zu Bird, Messaging-Profile aufgelöst in Absender und Subscriptions, profilweite Opt-outs zu Paaren
• Bandwidth: zwei Hosts zu einem, applicationId-Callbacks zu Workspace-Webhooks und eine Opt-out-Liste, die Ihre eigene Anwendung bereits vorhält
• Sinch: Batches zu Einzelversendungen, body zu text, Gruppenmitgliedschaften als Suppressions neu aufgebaut
• Infobip: ein dreistufiges Payload vereinfacht, eine kontobezogene Base-URL zu einem regionalen Host, eine Blocklist zu Paaren erweitert
• Bird Connectivity Platform: rest.messagebird.com API, originator und recipients zu from und to, reportUrl-GET-Callbacks zu signierten Webhooks

Nächste Schritte

• SMS-Anbieter vergleichen: Produkt-Workflow und Migrationserwägungen bewerten
• SMS senden: das vollständige Send-Payload, Absender, Segmente und das asynchrone 202-Modell
• Opt-outs und Keywords: was Bird für Sie beantwortet und wie Sie Suppressions verwalten
• SMS-Events: das Event-Vokabular und die Event-Payloads
• Webhooks & Events: Endpoint-Einrichtung, Signaturprüfung, Retries und Replay