# SMS migreren van Telnyx

Deze pagina vertaalt Telnyx' Messages API, messaging profiles en delivery webhooks naar Bird. Volg de [hoofdmigratiegids](/docs/guides/sms/migrate) op volgorde en gebruik deze mappings voor stap 3, 4 en 5.

De verzendaanroep lijkt het meest op die van Bird van alle providers hier: JSON, een bearer key en dezelfde veldnamen. `POST https://api.telnyx.com/v2/messages` accepteert `from`, `to` en `text`, en [`POST /v1/sms/messages`](/docs/api/reference/create-sms-message) ook. Wat niet meekomt is het messaging profile. Telnyx maakt het de eenheid van bijna alles: senderpool, webhook-URL, opt-outscope en de keywordconfiguratie. Bird verdeelt die over senders, webhook-subscriptions en suppressions. Het meeste werk in deze migratie is het ontwarren van dat object.

## Geef dit aan je agent

Gebruik deze briefing in je coding agent. Hij begint met discovery en levert een reviewbaar migratieplan op voordat er iets in productie verandert.

```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.
```

## Vertaal de verzendaanroep

| Wat het doet            | Telnyx                           | Bird                                                             |
| ----------------------- | -------------------------------- | ---------------------------------------------------------------- |
| Ontvanger               | `to`                             | `to` (één per request)                                           |
| Afzender                | `from` of `messaging_profile_id` | `from`                                                           |
| Inhoud                  | `text`                           | `text`                                                           |
| Intent                  | (geen)                           | `category`, verplicht bij vrije tekst                            |
| Afleverrapporten        | de webhook-URL van het profile   | een werkruimte-webhook geabonneerd op de afleverevents hieronder |
| Retourcontext           | je eigen opslag, op ID gekeyed   | `metadata`: willekeurige JSON, meegestuurd bij elk event         |
| Filterbare labels       | (geen)                           | `tags`: `{name, value}`-paren                                    |
| Veilig opnieuw proberen | (niet gedocumenteerd)            | `Idempotency-Key`-header                                         |
| Media                   | `media_urls`                     | geen equivalent: `media_urls` wordt geweigerd                    |

Porteernotities:

- **Een messaging-profile-ID wordt een gewone afzenderwaarde.** Telnyx lost de nummerpool en de verzendregels op achter het profile. Bird accepteert de afzender zelf in `from`, dus kies die per verzending, of gebruik een [template send](/docs/guides/sms/templates), die een geldige afzender selecteert voor de bestemming en `from` weigert.
- **Niets op de Messages API komt overeen met `category`.** Beslis per berichttype of het `transactional`, `marketing`, `authentication` of `service` is. Authenticatieverkeer moet specifiek als zodanig gelabeld worden in plaats van in een marketingstandaard achtergelaten.
- **Bekijk retry-semantiek apart.** Telnyx' send-referentie documenteert geen idempotency key, dus een timeout laat je raden. Stuur de `Idempotency-Key`-header mee vanaf de eerste port.

## Neem opt-outs over

**Dit is de stap die mensen verrast, en het getal dat je eerst moet uitrekenen is hoeveel suppressions je lijst wordt.**

Telnyx beperkt een opt-out tot het hele messaging profile: een abonnee die `STOP` sms't naar een willekeurig nummer op een profile wordt geblokkeerd voor elk nummer op dat profile, en een verzending naar die persoon geeft fout `40300`, "Blocked due to STOP message". Aparte opt-outlijsten voor aparte programma's bijhouden doe je door aparte profiles te gebruiken.

Bird beperkt een suppression tot een afzender-en-abonneepaar. Eén Telnyx-opt-out tegen een profile met twaalf nummers wordt dus twaalf Bird-suppressions, en een profile met honderd nummers wordt er honderd. Tel voordat je importeert: de vermenigvuldigingsfactor is het aantal afzenders dat je overneemt van dat profile, en dat bepaalt of de import een lus van honderden of van tienduizenden is.

Behoud de profile-brede intrekking over alle relevante afzenders. Opslag op afzenderniveau is geen toestemming om een programma onder een ander nummer te hervatten. Controleer of een werkruimte-brede voorkeur de juiste representatie is van het daadwerkelijke verzoek van de persoon.

Importeer via de [suppression-lus](/docs/guides/sms/migrate#4-carry-over-your-opt-out-list). [Suppressions lezen en beheren](/docs/guides/sms/opt-outs-and-keywords#reading-and-managing-suppressions) bevat het commando, en de reden waarom een handmatige suppression elke categorie blokkeert, inclusief transactioneel.

Maak de aangepaste keywords en auto-responses die via `autoresp_configs` geconfigureerd zijn opnieuw als Bird [keyword rules](/docs/guides/sms/opt-outs-and-keywords#campaign-keywords). Een verzending naar een onderdrukt paar wordt geweigerd bij toelating met `E12077 SMSRecipientSuppressed`; een downstream opt-out is een apart `recipient_opted_out`-afleverresultaat. Vang beide paden op wanneer je Telnyx-fout `40300` vervangt.

Redenen stapelen in plaats van samen te voegen, en dat doet ertoe zodra er verkeer loopt: een paar dat je importeerde als `manual` en dat vervolgens `STOP` sms't, krijgt een tweede record met reden `keyword_stop`, en berichten blijven geblokkeerd totdat elk record voor dat paar is beëindigd. Een abonnee hervatten die je ooit importeerde betekent beide verwijderen.

## Vertaal afleverstatussen

Gebruik deze tabel om levenscyclusconcepten te vergelijken, niet om events mechanisch te hernoemen. Bird kiest een fout-event op basis van de gerapporteerde status en reden. Een geweigerd API-request maakt geen bericht aan; een weigering na acceptatie kan `sms.rejected` opleveren, inclusief een carrierweigering. Ontbrekend afleverbewijs blijft onbekend. Bewaar de ruwe providerstatus en -code naast je genormaliseerde uitkomst.

| Uitkomst                           | Telnyx                              | Bird                             |
| ---------------------------------- | ----------------------------------- | -------------------------------- |
| API heeft het bericht geaccepteerd | `queued`                            | `sms.accepted`                   |
| Overgedragen aan de carrier        | `sent`, op `message.sent`           | `sms.sent`                       |
| Carrier bevestigde aflevering      | `delivered`, op `message.finalized` | `sms.delivered`                  |
| Aflevering mislukt                 | `delivery_failed`                   | `sms.undelivered`                |
| Permanente fout                    | `sending_failed`                    | `sms.failed`                     |
| Request geweigerd bij toelating    | requestfout                         | HTTP-fout; geen bericht of event |
| Geldigheidsvenster verstreken      | (geen)                              | `sms.expired`                    |

**De eventvorm verandert, niet alleen de woorden.** Telnyx stuurt één `message.finalized`-webhook met de eindstatus in een `status`-veld, dus je handler vertakt op een waarde binnen één eventtype. Bird stuurt aparte eventtypen, en je abonneert je op de typen die je wilt, dus de vertakking verplaatst zich uit je code naar de subscription. Daarom noemt de linkerkolom hierboven een event en een status samen en de rechterkolom alleen een event.

Er veranderen nog twee mechanismen met de namen:

- **Subscriptions vervangen de webhook-URL van het profile.** Telnyx post afleverupdates naar de URL op het messaging profile, dus de bestemming is een eigenschap van het profile waardoor elk bericht is verzonden. Bird levert af op endpoints die je werkruimte registreert, elk geabonneerd op de eventtypen die het wil, dus een tweede consumer is een tweede subscription in plaats van een wijziging aan een gedeeld object.
- **Standard Webhooks vervangt Telnyx' ondertekeningsschema.** Bird stuurt JSON ondertekend volgens [Standard Webhooks](https://www.standardwebhooks.com); vervang de verificatie door het recept in [Webhooks & events](/docs/guides/webhooks#verify-signatures).

Registreer het endpoint eenmalig en noem de eventtypen die je handler wil: de `sms.*`-events hierboven zijn de lijst om op te abonneren, en er is geen wildcard die ze vervangt. [Maak een endpoint aan](/docs/guides/webhooks#create-an-endpoint) bevat het commando en het enige dat je bij de eerste aanroep goed moet doen: het signing secret opslaan dat de response precies één keer toont.

Bird rapporteert een fout met een gestandaardiseerde `error`-code zoals `invalid_destination`, `content_rejected`, `provider_unavailable` of `recipient_opted_out`; de volledige lijst staat op de [eventpagina](/docs/guides/sms/events#failure-events). Koppel je alerting daaraan.

## Overschakelen

[Bestemmingen](/docs/guides/sms/migrate#1-enable-your-destination-countries), [afzenders](/docs/guides/sms/migrate#2-set-up-a-sender) en de [verkeersopbouw](/docs/guides/sms/migrate#6-test-against-simulated-destinations) zijn provideronafhankelijk en worden behandeld in de hoofdgids. Twee Telnyx-specifieke punten horen op het overschakelplan: je 10DLC-merk en -campagne zijn geregistreerd bij The Campaign Registry via Telnyx en worden niet automatisch Bird-registraties. Bevestig de toepasselijke migratie- of registratieprocedure voordat je betaald werk indient. Nummers die je bezit bij Telnyx moeten geport worden, iets dat support regelt op hun eigen planning, niet de jouwe.

Begin voor de Bird-vereisten bij [Registreren voor 10DLC](/docs/guides/sms/10dlc): die pagina behandelt wat elk veld betekent, de entitytypen die het register erkent, en de requirements-aanroep die je vertelt wat je moet aanleveren voordat je het merk aanmaakt, want dat is de betaalde stap.

## Volgende stappen

- [Vergelijk Bird en Telnyx voor SMS](/products/sms/compare/bird-vs-telnyx): productevaluatie en migratieoverwegingen

- [SMS verzenden](/docs/guides/sms/sending-sms): de volledige payload waar je naartoe porteert
- [Opt-outs en keywords](/docs/guides/sms/opt-outs-and-keywords): keyworddekking per land en suppressionbeheer
- [SMS-events](/docs/guides/sms/events): de eventwoordenschat waar je webhook-handler naartoe verhuist
- [Webhooks & events](/docs/guides/webhooks): endpoint-setup en Standard Webhooks-verificatie

## 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)