SMS von Telnyx migrieren

Diese Seite ordnet Telnyx' Messages API, Messaging-Profile und Delivery-Webhooks Bird zu. Folgen Sie der Hauptmigrationsanleitung in der angegebenen Reihenfolge und verwenden Sie diese Zuordnungen für die Schritte 3, 4 und 5.

Der Send-Call ist dem von Bird am ähnlichsten unter allen Anbietern hier: JSON, ein Bearer-Key und dieselben Feldnamen. POST https://api.telnyx.com/v2/messages nimmt from, to und text entgegen, und POST /v1/sms/messages ebenso. Was sich nicht übertragen lässt, ist das Messaging-Profil. Telnyx macht es zur zentralen Einheit für fast alles: Sender-Pool, Webhook-URL, Opt-out-Geltungsbereich und Keyword-Konfiguration. Bird verteilt diese auf Sender, Webhook-Subscriptions und Suppressions. Der größte Teil der Arbeit bei dieser Migration besteht darin, dieses Objekt aufzulösen.

Übergeben Sie das an Ihren Agent

Verwenden Sie dieses Briefing in Ihrem Coding-Agent. Es beginnt mit einer Bestandsaufnahme und erstellt einen überprüfbaren Migrationsplan, bevor Produktionsänderungen vorgenommen werden.

Codebeispiel

Help me migrate my SMS integration from Telnyx to Bird.
1. Inspect this repository's sends, senders, callbacks, schedules, templates, opt-outs and tests. List the traffic and behavior that must survive the migration.
2. Read the Markdown guides at https://bird.com/docs/guides/sms/migrate/telnyx.md and https://bird.com/docs/guides/sms/migrate.md. Use an existing authenticated Bird MCP or CLI connection. If neither is available, follow https://bird.com/docs/ai/set-up-your-agent.md. Discover the actual operations; do not invent commands or ask me to paste credentials into chat.
3. Prepare the code changes, sender/destination requirements, consent migration, webhook verification and rollout/rollback plan. Preserve the scope of each customer's preferences, including requests outside SMS replies. Separate API batches from audience broadcasts and preserve any behavior that has no direct endpoint equivalent.
4. Show me the exact affected resources, destinations, test volume and known costs before an action that sends messages, spends money, registers or changes a sender, or moves production traffic. Require explicit human authorization for each paid submission or production change. Name one-off 10DLC registration and resubmission fees before requesting approval. An existing explicit approval for that exact action is sufficient; broad migration approval is not. Simulated SMS destinations are billable and still require authorization.
5. If I am keeping Telnyx numbers, prepare the human support port request and obtain authorization to send it. Read bird support-tickets create --help, then use the available CLI or MCP support operation with the reviewed number list and requirements. Return the ticket ID and follow the reply; support arranges the port on its own schedule, separately from the code cutover.
6. Run local and intercepted tests first. When authorized, perform the agreed bounded integration tests, inspect accepted and final outcomes separately, and report failures or uncertainty. Do not claim a delivery receipt proves reading or that request idempotency guarantees exactly-once delivery.
7. Keep production cutover and retiring the old provider as explicit steps in the approved rollout. Finish with the diff, evidence, unresolved requirements and the next action.

Den Send-Call zuordnen

Funktion	Telnyx	Bird
Empfänger	to	to (einer pro Request)
Sender	from oder messaging_profile_id	from
Inhalt	text	text
Intent	(keiner)	category, erforderlich bei Freitext
Zustellberichte	die Webhook-URL des Profils	ein Workspace-Webhook, der die unten genannten Delivery-Events abonniert hat
Round-Trip-Kontext	eigener Speicher, nach ID geschlüsselt	metadata: beliebiges JSON, wird bei jedem Event zurückgegeben
Filterbare Labels	(keine)	tags: {name, value}-Paare
Sichere Wiederholungen	(nicht dokumentiert)	Idempotency-Key-Header
Medien	media_urls	kein Äquivalent: media_urls wird abgelehnt

Portierungshinweise:

Eine Messaging-Profil-ID wird zu einem einfachen Sender-Wert. Telnyx löst den Nummernpool und dessen Senderegeln hinter dem Profil auf. Bird nimmt den Sender selbst in from entgegen – wählen Sie ihn also pro Versand, oder verwenden Sie einen Template-Versand, der einen gültigen Sender für das Ziel auswählt und from ablehnt.
Auf der Messages API gibt es keine Entsprechung für category. Entscheiden Sie pro Nachrichtentyp, ob es sich um transactional, marketing, authentication oder service handelt. Authentifizierungsverkehr sollte insbesondere als solcher gekennzeichnet werden, anstatt in einem Marketing-Standard zu verbleiben.
Prüfen Sie die Retry-Semantik separat. Die Send-Referenz von Telnyx dokumentiert keinen Idempotency-Key, sodass ein Timeout Sie im Unklaren lässt. Senden Sie den Idempotency-Key-Header ab der ersten Portierung mit.

Opt-outs übernehmen

Dies ist der Schritt, der überrascht – und die Zahl, die Sie zuerst ermitteln sollten, ist, wie viele Suppressions aus Ihrer Liste werden.

Telnyx bezieht ein Opt-out auf das gesamte Messaging-Profil: Ein Subscriber, der STOP an eine beliebige Nummer eines Profils sendet, wird für jede Nummer dieses Profils gesperrt, und ein Versand an diese Person ergibt den Fehler 40300, "Blocked due to STOP message". Getrennte Opt-out-Listen für getrennte Programme erreichen Sie durch getrennte Profile.

Bird bezieht eine Suppression stattdessen auf ein Sender-Subscriber-Paar. Ein einzelnes Telnyx-Opt-out gegen ein Profil mit zwölf Nummern wird also zu zwölf Bird-Suppressions, und ein Profil mit hundert Nummern wird zu hundert. Zählen Sie vor dem Import: Der Multiplikator ist die Anzahl der Sender, die Sie aus diesem Profil übernehmen, und er entscheidet, ob der Import eine Schleife von Hunderten oder von Zehntausenden ist.

Bewahren Sie den profilweiten Widerruf über alle betroffenen Sender hinweg. Die Speicherung auf Sender-Ebene ist keine Erlaubnis, ein Programm unter einer anderen Nummer fortzusetzen. Prüfen Sie, ob eine Workspace-weite Präferenz die passende Abbildung für die tatsächliche Anfrage der Person ist.

Importieren Sie über die Suppressions-Schleife. Suppressions lesen und verwalten enthält den Befehl und erklärt, warum eine manuelle Suppression jede Kategorie einschließlich Transaktionsnachrichten blockiert.

Erstellen Sie die benutzerdefinierten Keywords und Auto-Antworten, die über autoresp_configs konfiguriert waren, als Bird-Keyword-Regeln neu. Ein Versand an ein unterdrücktes Paar wird bei der Annahme mit E12077 SMSRecipientSuppressed abgewiesen; ein nachgelagertes Opt-out ist ein separates recipient_opted_out-Zustellergebnis. Behandeln Sie beide Pfade, wenn Sie den Telnyx-Fehler 40300 ersetzen.

Gründe stapeln sich, anstatt zusammengeführt zu werden – das wird relevant, sobald Traffic fließt: Ein Paar, das Sie als manual importiert haben und das dann STOP sendet, erhält einen zweiten Eintrag mit dem Grund keyword_stop, und Nachrichten bleiben gesperrt, bis jeder Eintrag für dieses Paar beendet ist. Einen einmal importierten Subscriber wieder aufzunehmen bedeutet, beide Einträge zu entfernen.

Zustellstatus übersetzen

Verwenden Sie diese Tabelle, um Lifecycle-Konzepte zu vergleichen, nicht um Events mechanisch umzubenennen. Bird wählt ein Failure-Event anhand des gemeldeten Status und Grunds. Ein abgelehnter API-Request erzeugt keine Nachricht; eine Ablehnung nach Annahme kann sms.rejected erzeugen, einschließlich einer Carrier-Ablehnung. Fehlende Zustellnachweise bleiben unbekannt. Bewahren Sie den rohen Provider-Status und -Code zusammen mit Ihrem normalisierten Ergebnis auf.

Ergebnis	Telnyx	Bird
API hat die Nachricht angenommen	queued	sms.accepted
An den Carrier übergeben	sent, bei message.sent	sms.sent
Carrier hat Zustellung bestätigt	delivered, bei message.finalized	sms.delivered
Zustellung fehlgeschlagen	delivery_failed	sms.undelivered
Permanenter Fehler	sending_failed	sms.failed
Request bei Annahme abgelehnt	Request-Fehler	HTTP-Fehler; keine Nachricht oder Event
Gültigkeitsfenster abgelaufen	(keiner)	sms.expired

Die Event-Struktur ändert sich, nicht nur die Bezeichnungen. Telnyx sendet einen message.finalized-Webhook, der den Endstatus in einem status-Feld enthält, sodass Ihr Handler innerhalb eines einzelnen Event-Typs nach einem Wert verzweigt. Bird gibt stattdessen unterschiedliche Event-Typen aus, und Sie abonnieren die gewünschten – die Verzweigung verlagert sich also aus Ihrem Code in die Subscription. Deshalb nennt die linke Spalte oben ein Event und einen Status zusammen und die rechte Spalte nur ein Event.

Zwei weitere Mechanismen ändern sich mit den Namen:

Subscriptions ersetzen die Webhook-URL des Profils. Telnyx sendet Zustellupdates an die URL des Messaging-Profils, sodass das Ziel eine Eigenschaft des Profils ist, über das jede Nachricht gesendet wurde. Bird liefert an Endpoints, die Ihr Workspace registriert, jeweils abonniert auf die gewünschten Event-Typen – ein zweiter Consumer ist also eine zweite Subscription, kein Eingriff in ein gemeinsames Objekt.
Standard Webhooks ersetzt das Signaturverfahren von Telnyx. Bird sendet JSON, signiert gemäß Standard Webhooks; ersetzen Sie die Verifizierung durch die Anleitung in Webhooks & Events.

Registrieren Sie den Endpoint einmalig und benennen Sie die Event-Typen, die Ihr Handler benötigt: Die sms.*-Events oben sind die Liste, die Sie abonnieren, und es gibt keinen Platzhalter, der sie ersetzt. Endpoint erstellen enthält den Befehl und das Einzige, was beim ersten Aufruf stimmen muss: das Signing-Secret, das die Antwort genau einmal anzeigt, sicher zu speichern.

Bird meldet einen Fehler mit einem standardisierten error-Code wie invalid_destination, content_rejected, provider_unavailable oder recipient_opted_out; die vollständige Liste finden Sie auf der Events-Seite. Richten Sie Ihr Alerting danach aus.

Umstellung

Destinations, Sender und der Traffic-Ramp sind anbieterunabhängig und in der Hauptanleitung behandelt. Zwei Telnyx-spezifische Punkte gehören auf den Umstellungsplan: Ihre 10DLC-Brand und -Campaign sind über Telnyx bei The Campaign Registry registriert und werden nicht automatisch zu Bird-Registrierungen. Klären Sie das anwendbare Migrations- oder Registrierungsverfahren, bevor Sie kostenpflichtige Arbeiten einreichen. Nummern, die Sie bei Telnyx besitzen, erfordern eine Portierung, die der Support organisiert – nach dessen Zeitplan, nicht nach Ihrem.

Für die Bird-seitigen Anforderungen beginnen Sie mit Für 10DLC registrieren: Dort wird erklärt, was jedes Feld bedeutet, welche Entity-Typen die Registry anerkennt und welcher Requirements-Call Ihnen sagt, was Sie angeben müssen, bevor Sie die Brand erstellen – das ist der kostenpflichtige Schritt.

Nächste Schritte

Bird und Telnyx für SMS vergleichen: Produktbewertung und Migrationsüberlegungen
SMS senden: der Payload, auf den Sie portieren, vollständig
Opt-outs und Keywords: Keyword-Abdeckung pro Land und Suppressions-Verwaltung
SMS-Events: das Event-Vokabular, auf das Ihr Webhook-Handler umsteigt
Webhooks & Events: Endpoint-Einrichtung und Standard-Webhooks-Verifizierung