Migrer SMS depuis Telnyx

Cette page fait correspondre l'API Messages de Telnyx, les messaging profiles et les webhooks de livraison avec Bird. Suivez le guide de migration principal dans l'ordre et utilisez ces correspondances pour les étapes 3, 4 et 5.

L'appel d'envoi est le plus proche de celui de Bird parmi tous les fournisseurs présentés ici : JSON, une clé bearer et les mêmes noms de champs. POST https://api.telnyx.com/v2/messages prend from, to et text, tout comme POST /v1/sms/messages. Le messaging profile change de forme. Telnyx en fait l'unité de presque tout : pool d'expéditeurs, URL de webhook, portée des opt-outs et configuration des mots-clés. Un messaging profile Bird regroupe le côté envoi : l'expéditeur pour chaque pays de destination ainsi qu'un expéditeur par défaut, les numéros qui reçoivent les réponses, les paramètres d'envoi par défaut et une URL de callback. Les opt-outs et les mots-clés restent en dehors, sous forme de suppressions et de règles de mots-clés. L'essentiel du travail de cette migration consiste à décider où va chaque partie d'un profil Telnyx.

Transmettez ceci à votre agent

Utilisez ce brief dans votre agent de codage. Il commence par une phase de découverte et produit un plan de migration vérifiable avant toute modification en production.

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 platform support 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.

Faire correspondre l'appel d'envoi

Notes de portage :

• Un ID de messaging profile correspond à un ID de messaging profile Bird. Créez un messaging profile avec l'expéditeur de chaque pays de destination, ou un expéditeur par défaut, et indiquez-le dans messaging_profile_id. Si vous omettez from, Bird envoie depuis l'expéditeur du profil pour le pays de destination. Un profil Bird contient un expéditeur par pays de destination : un pool de numéros Telnyx devient donc un expéditeur choisi par pays. Un from indiqué dans l'envoi est prioritaire, et un envoi par template sélectionne toujours un expéditeur valide pour la destination et rejette from.
• Rien dans l'API Messages ne correspond à category. Décidez pour chaque type de message s'il s'agit de transactional, marketing, authentication ou service. Étiquetez en particulier le trafic d'authentification comme tel plutôt que de le laisser dans une catégorie marketing par défaut.
• Examinez séparément la sémantique des nouvelles tentatives. La référence d'envoi de Telnyx ne documente aucune clé d'idempotence : après un timeout, vous ne savez donc pas si le message est parti. Envoyez l'en-tête Idempotency-Key dès le premier portage.

Reporter les opt-outs

C'est l'étape qui surprend, et le premier chiffre à calculer est le nombre de suppressions que votre liste va générer.

Telnyx limite un opt-out à l'ensemble du messaging profile : un abonné qui envoie STOP à n'importe quel numéro d'un profil est bloqué pour tous les numéros de ce profil, et un envoi vers lui renvoie l'erreur 40300, "Blocked due to STOP message". Pour maintenir des listes d'opt-out distinctes par programme, il faut maintenir des profils distincts.

Bird limite une suppression à une paire expéditeur-abonné. Un seul opt-out Telnyx contre un profil contenant douze numéros devient donc douze suppressions Bird, et un profil avec cent numéros en devient cent. Comptez avant d'importer : le multiplicateur est le nombre d'expéditeurs que vous reportez depuis ce profil, et il détermine si l'import est une boucle de centaines ou de dizaines de milliers.

Préservez le retrait au niveau du profil sur tous les expéditeurs concernés. Le stockage au niveau de l'expéditeur ne vaut pas autorisation de reprendre un programme sous un autre numéro. Vérifiez si une préférence à l'échelle de l'espace de travail est la représentation appropriée de la demande réelle de la personne.

Importez via la boucle de suppression. Lire et gérer les suppressions contient la commande, ainsi que la raison pour laquelle une suppression manuelle bloque toutes les catégories, y compris les messages transactionnels.

Recréez les mots-clés personnalisés et les réponses automatiques configurés via autoresp_configs sous forme de règles de mots-clés Bird. Un envoi vers une paire sur la liste de suppression est refusé à l'admission avec E12077 SMSRecipientSuppressed ; un opt-out en aval est un résultat de livraison recipient_opted_out distinct. Gérez les deux cas lorsque vous remplacez l'erreur Telnyx 40300.

Les raisons s'empilent au lieu de fusionner, ce qui compte une fois le trafic lancé : une paire importée comme manual qui envoie ensuite STOP obtient un second enregistrement avec la raison keyword_stop, et les messages restent bloqués tant que tous les enregistrements de cette paire n'ont pas pris fin. Pour réactiver un abonné que vous avez importé, supprimez les deux enregistrements.

Convertir les statuts de livraison

Utilisez ce tableau pour comparer les concepts de cycle de vie, pas pour renommer mécaniquement les événements. Bird choisit un événement d'échec en fonction du statut et de la raison rapportés. Une requête API refusée ne crée aucun message ; un rejet après acceptation peut produire sms.rejected, y compris un rejet par l'opérateur. Une preuve de livraison manquante reste inconnue. Conservez le statut brut du fournisseur et le code à côté de votre résultat normalisé.

Les noms des événements et leur structure changent tous les deux. Telnyx envoie un seul webhook message.finalized qui contient l'état terminal dans un champ status : votre handler choisit donc sa branche selon une valeur à l'intérieur d'un type d'événement unique. Bird émet au contraire des types d'événements distincts, et vous vous abonnez à ceux que vous voulez : le branchement quitte donc votre code pour passer dans l'abonnement. C'est pourquoi la colonne de gauche ci-dessus nomme à la fois un événement et un statut, alors que la colonne de droite ne nomme qu'un événement.

Deux autres mécanismes changent avec les noms :

• Une callback URL de profil ou des abonnements remplacent l'URL webhook du profil. Telnyx envoie les mises à jour de livraison à l'URL du messaging profile : la destination est donc une propriété du profil par lequel chaque message a été envoyé. Le options.callback_url d'un profil Bird conserve ce fonctionnement : les événements des messages envoyés avec le profil partent vers cette URL au lieu de vos endpoints webhook, et les réponses partent vers son inbound.callback_url s'il est défini. Si le profil définit callback_events, un événement sortant qui n'y figure pas n'atteint ni l'URL ni vos endpoints : listez donc les événements de livraison dont votre handler a besoin. Callback URLs SMS couvre le routage, les nouvelles tentatives et la relecture. Sans callback URL, Bird livre aux endpoints que votre espace de travail enregistre, chacun abonné aux types d'événements souhaités : un second consommateur correspond donc à un second abonnement, et non à une modification d'un objet partagé.
• Standard Webhooks remplace le schéma de signature de Telnyx. Bird envoie des JSON signés selon Standard Webhooks ; remplacez votre vérification par la méthode décrite dans Webhooks & events. Une callback URL utilise le même schéma avec le secret de signature des callbacks de votre espace de travail, que vous devez renouveler avant de pouvoir vérifier les signatures.

Enregistrez le endpoint une seule fois en nommant les types d'événements que votre handler souhaite : les événements sms.* ci-dessus constituent la liste à laquelle vous abonner, et il n'existe pas de joker qui les remplace. Créer un endpoint contient la commande et le point à réussir dès le premier appel : stocker le secret de signature que la réponse affiche une seule fois.

Bird signale un échec avec un code error standardisé tel que invalid_destination, content_rejected, provider_unavailable ou recipient_opted_out ; la liste complète se trouve sur la page des événements. Faites correspondre vos alertes à ces codes.

Basculer

Les destinations, les expéditeurs et la montée en charge sont indépendants du fournisseur et couverts dans le guide principal. Deux éléments spécifiques à Telnyx doivent figurer dans le plan de bascule : votre marque et campagne 10DLC sont enregistrées auprès de The Campaign Registry via Telnyx et ne deviennent pas automatiquement des enregistrements Bird. Confirmez la procédure de migration ou d'enregistrement applicable avant de soumettre du travail facturé. Les numéros que vous possédez chez Telnyx nécessitent un portage que le support organise, selon son propre calendrier et non le vôtre.

Pour les exigences côté Bird, commencez par S'enregistrer pour le 10DLC : cette page couvre la signification de chaque champ, les types d'entités reconnus par le registre, et l'appel de vérification des exigences qui vous indique ce qu'il faut fournir avant de créer la marque, qui est l'étape facturée.

Étapes suivantes

• Comparer Bird et Telnyx pour SMS : évaluation produit et points de migration

• Envoyer des SMS : le payload vers lequel vous portez, en intégralité

• Opt-outs et mots-clés : couverture des mots-clés par pays et gestion des suppressions

• Événements SMS : le vocabulaire d'événements vers lequel votre handler webhook migre

• Webhooks & events : configuration du endpoint et vérification Standard Webhooks