# SMS von Telnyx migrieren Diese Seite ordnet Telnyx' Messages API, Messaging-Profile und Delivery-Webhooks Bird zu. Folgen Sie der [Hauptmigrationsanleitung](/docs/guides/sms/migrate) 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`](/docs/api/reference/create-sms-message) 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. ```text 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](/docs/guides/sms/templates), 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](/docs/guides/sms/migrate#4-carry-over-your-opt-out-list). [Suppressions lesen und verwalten](/docs/guides/sms/opt-outs-and-keywords#reading-and-managing-suppressions) 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](/docs/guides/sms/opt-outs-and-keywords#campaign-keywords) 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](https://www.standardwebhooks.com); ersetzen Sie die Verifizierung durch die Anleitung in [Webhooks & Events](/docs/guides/webhooks#verify-signatures). 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](/docs/guides/webhooks#create-an-endpoint) 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](/docs/guides/sms/events#failure-events). Richten Sie Ihr Alerting danach aus. ## Umstellung [Destinations](/docs/guides/sms/migrate#1-enable-your-destination-countries), [Sender](/docs/guides/sms/migrate#2-set-up-a-sender) und der [Traffic-Ramp](/docs/guides/sms/migrate#6-test-against-simulated-destinations) 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](/docs/guides/sms/10dlc): 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](/products/sms/compare/bird-vs-telnyx): Produktbewertung und Migrationsüberlegungen - [SMS senden](/docs/guides/sms/sending-sms): der Payload, auf den Sie portieren, vollständig - [Opt-outs und Keywords](/docs/guides/sms/opt-outs-and-keywords): Keyword-Abdeckung pro Land und Suppressions-Verwaltung - [SMS-Events](/docs/guides/sms/events): das Event-Vokabular, auf das Ihr Webhook-Handler umsteigt - [Webhooks & Events](/docs/guides/webhooks): Endpoint-Einrichtung und Standard-Webhooks-Verifizierung ## Related resources - [Choose a sender for your markets](/explained/sms/which-sms-sender-type-should-i-use) (answer) - [Check your message segments](/tools/sms-segment-calculator) (tool) - [Compare SMS providers](/products/sms/compare) (product)