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. Ce qui ne se transpose pas, c'est le messaging profile. 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. Bird répartit tout cela entre expéditeurs, abonnements webhook et suppressions. L'essentiel du travail de cette migration consiste à démêler cet objet.
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.
Exemple de code
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.Faire correspondre l'appel d'envoi
| Fonction | Telnyx | Bird |
|---|---|---|
| Destinataire | to | to (un par requête) |
| Expéditeur | from ou messaging_profile_id | from |
| Corps | text | text |
| Intention | (aucune) | category, requis pour le texte libre |
| Accusés de réception | l'URL webhook du profil | un webhook d'espace de travail abonné aux événements de livraison ci-dessous |
| Contexte aller-retour | votre propre stockage, indexé par ID | metadata : JSON arbitraire, renvoyé à chaque événement |
| Étiquettes filtrables | (aucune) | tags : paires {name, value} |
| Réessais sûrs | (non documenté) | en-tête Idempotency-Key |
| Média | media_urls | pas d'équivalent : media_urls est rejeté |
Notes de portage :
- Un messaging profile ID devient une simple valeur d'expéditeur. Telnyx résout le pool de numéros et ses règles d'envoi derrière le profil. Bird prend l'expéditeur lui-même dans from, choisissez-le à chaque envoi ou utilisez un envoi par template, qui sélectionne un expéditeur valide pour la destination et rejette from.
- Rien dans l'API Messages ne correspond à category. Décidez par type de message s'il s'agit de transactional, marketing, authentication ou service. Le trafic d'authentification en particulier doit être étiqueté comme tel plutôt que laissé dans un défaut marketing.
- Examinez la sémantique de réessai séparément. La référence d'envoi de Telnyx ne documente aucune clé d'idempotence, un timeout vous laisse donc dans l'incertitude. 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 supprimée 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. Réactiver un abonné que vous avez importé implique de supprimer les deux.
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é.
| Résultat | Telnyx | Bird |
|---|---|---|
| API a accepté le message | queued | sms.accepted |
| Transmis à l'opérateur | sent, sur message.sent | sms.sent |
| L'opérateur a confirmé la livraison | delivered, sur message.finalized | sms.delivered |
| Échec de livraison | delivery_failed | sms.undelivered |
| Échec permanent | sending_failed | sms.failed |
| Requête refusée à l'admission | erreur de requête | erreur HTTP ; ni message ni événement |
| Fenêtre de validité écoulée | (aucun) | sms.expired |
La forme de l'événement change, pas seulement les mots. Telnyx envoie un seul webhook message.finalized contenant l'état terminal dans un champ status, votre handler branche donc sur une valeur à l'intérieur d'un type d'événement unique. Bird émet des types d'événements distincts, et vous vous abonnez à ceux que vous voulez, de sorte que le branchement quitte votre code pour passer dans l'abonnement. C'est pourquoi la colonne de gauche ci-dessus nomme un événement et un statut ensemble, et la colonne de droite ne nomme qu'un événement.
Deux autres mécanismes changent avec les noms :
- Les 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é. Bird livre aux endpoints que votre espace de travail enregistre, chacun abonné aux types d'événements souhaités, de sorte qu'un second consommateur est un second abonnement plutôt qu'une modification d'un objet partagé.
- Standard Webhooks remplace le schéma de signature de Telnyx. Bird envoie JSON signés selon Standard Webhooks ; remplacez la vérification par la recette dans Webhooks & events.
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
Ressources associées
Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.