Migrer SMS depuis Twilio
Cette page fait correspondre l'API Programmable Messaging de Twilio, les Messaging Services et les callbacks de statut à Bird. Suivez le guide de migration principal dans l'ordre et utilisez ces correspondances pour les étapes 3, 4 et 5.
Deux différences structurent l'ensemble du portage. L'POST /2010-04-01/Accounts/{AccountSid}/Messages.json de Twilio accepte des paramètres PascalCase encodés en formulaire, authentifiés avec votre Account SID et Auth Token ; POST /v1/sms/messages accepte du JSON authentifié avec une clé bearer API contre votre hôte régional. Par ailleurs, un Messaging Service Twilio peut regrouper la sélection de l'expéditeur, la gestion des désinscriptions et la configuration des callbacks. Faites correspondre chaque comportement séparément au propriétaire Bird ; renommer son SID en valeur d'expéditeur ne préserve pas l'ensemble du service.
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 Twilio 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 https://bird.com/docs/guides/sms/migrate/twilio.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 Twilio 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 | Twilio | Bird |
|---|---|---|
| Destinataire | To | to (un par requête) |
| Expéditeur | From ou MessagingServiceSid | from |
| Corps | Body | text |
| Modèle de contenu | ContentSid + ContentVariables | vérifiez le contenu séparément ; les modèles système Bird ne sont pas un import du Content Twilio |
| Intention | (aucune) | category, obligatoire sur le texte libre |
| Libellés filtrables | (aucun) | paires tags : {name, value} |
| Contexte aller-retour | votre propre stockage, indexé par SID | metadata : JSON arbitraire, renvoyé sur chaque événement |
| Accusés de réception | StatusCallback | un webhook d'espace de travail abonné aux événements de livraison ci-dessous |
| Translittération | SmartEncoded | options.smart_encoding (par défaut false) |
| Réessais sûrs | (aucun sur Messages) | en-tête Idempotency-Key |
| Planification | ScheduleType + SendAt | pas d'équivalent : scheduled_at est rejeté |
| Médias | MediaUrl | pas d'équivalent : media_urls est rejeté |
| Validité | ValidityPeriod | pas d'équivalent : validity_period est rejeté |
| Raccourcissement de liens | ShortenUrls | pas d'équivalent |
Les trois champs rejetés sont réservés et répondent à 422 SMSUnsupportedFeature. Conservez la planification et la gestion des médias en l'état pour le moment.
Notes de portage :
- Traitez les comportements du Messaging Service séparément. Twilio résout le pool d'expéditeurs, l'expéditeur persistant et la correspondance géographique derrière le SID. Bird prend l'expéditeur lui-même dans from, donc choisissez l'expéditeur à chaque envoi, ou utilisez un envoi par modèle, qui sélectionne un expéditeur valide pour la destination et rejette from.
- Une limite de caractères devient un plafond de segments. Les longueurs sont proches pour du texte GSM-7, mais le comportement en cas de dépassement diffère : Bird ne tronque jamais, donc un corps trop long est rejeté avec une 422 au lieu d'être coupé.
- 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.
- Les identifiants de test de Twilio correspondent à des destinations simulées. Les numéros magiques avec lesquels vous testez déjà, notamment +15005550006 et +15005550001, produisent ici aussi des résultats synthétisés, avec deux différences : il n'y a pas d'identifiant de test séparé, et les envois sont facturés. Les résultats sont listés dans le guide principal.
Transférer les désinscriptions
Twilio peut associer une désinscription à un numéro ou à un Messaging Service. Une demande à l'échelle du service peut couvrir plusieurs expéditeurs. Préservez cette portée lors de l'import dans les suppressions expéditeur-abonné de Bird, ou utilisez la préférence d'espace de travail appropriée pour une demande véritablement globale à l'espace de travail.
La documentation Advanced Opt-Out de Twilio indique que le signalement des numéros bloqués n'est pas exposé via sa Console ni via REST API. Demandez un export via le processus de support disponible et rapprochez-le de vos propres enregistrements de préférences, journaux entrants et demandes de support. Un journal de mots-clés seul peut être incomplet.
Importez le résultat vérifié via le workflow de suppression. Une suppression manuelle bloque toutes les catégories pour cette paire, donc vérifiez la portée visée au lieu de la restreindre ou de l'élargir silencieusement.
Le 21610 de Twilio signale un destinataire désinscrit. Dans Bird, une paire supprimée est refusée à l'admission avec E12077 SMSRecipientSuppressed, avant qu'un message n'existe. L'erreur de livraison recipient_opted_out signale plutôt une désinscription en aval. Vérifiez la couverture de mots-clés de Bird avant de retirer un gestionnaire existant, et conservez les mécanismes de désinscription en dehors du catalogue intégré.
Traduire les statuts de livraison
Utilisez ce tableau pour comparer les concepts de cycle de vie, pas pour renommer les événements mécaniquement. Bird choisit un événement d'échec à partir du statut et de la raison signalé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 de l'opérateur. Une preuve de livraison manquante reste inconnue. Conservez le statut brut du fournisseur et le code aux côtés de votre résultat normalisé.
| Résultat | Twilio MessageStatus | Bird |
|---|---|---|
| API a accepté le message | queued, accepted | sms.accepted |
| Remis à l'opérateur | sending, sent | sms.sent |
| L'opérateur a confirmé la livraison | delivered | sms.delivered |
| L'opérateur a signalé la non-livraison | undelivered | sms.undelivered |
| Échec permanent | failed | sms.failed |
| Requête refusée à l'admission | erreur de requête | erreur HTTP ; pas de message ni d'événement |
| Fenêtre de validité écoulée | (aucun) | sms.expired |
| Planifié ou annulé | scheduled, canceled | pas encore d'équivalent |
Trois mécanismes changent avec les noms :
- Les endpoints remplacent les URL de callback. Twilio poste vers le StatusCallback sur le message ou le Messaging Service. Bird livre à des endpoints que votre espace de travail enregistre, chacun abonné aux types d'événements qu'il souhaite, de sorte qu'un nouveau consommateur est un nouvel abonnement plutôt qu'un redéploiement.
- Du JSON signé remplace les posts encodés en formulaire. Twilio envoie du application/x-www-form-urlencoded avec un en-tête X-Twilio-Signature ; Bird envoie du JSON signé selon Standard Webhooks. Remplacez la vérification par la procédure décrite dans Webhooks & events.
- Les messages entrants arrivent sous forme d'événements. Le webhook "A message comes in" par numéro de Twilio attend une réponse TwiML que votre application peut utiliser pour répondre automatiquement. Bird émet sms.received vers le même endpoint abonné que tout le reste, et il n'y a pas de corps de réponse qui envoie une réponse : répondez en appelant le point de terminaison d'envoi, ou laissez les règles de mots-clés répondre pour vous.
Enregistrez le endpoint une seule fois en nommant les types d'événements que votre gestionnaire souhaite : les événements sms.* dans le tableau ci-dessus sont la liste à laquelle vous abonner, et il n'y a pas de joker qui les remplace. Créer un endpoint contient la commande, la raison pour laquelle le catalogue doit être énuméré, et le point à réussir dès le premier appel, à savoir stocker le secret de signature que la réponse affiche une seule fois.
Les codes d'erreur numériques de Twilio n'ont pas de correspondance un pour un. 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 à ceux-ci plutôt qu'aux codes de la plage 30000.
Basculer
Les destinations, les expéditeurs et la montée en charge du trafic sont indépendants du fournisseur et couverts dans le guide principal. Deux éléments spécifiques à Twilio doivent figurer dans le plan de bascule : votre marque et votre campagne 10DLC sont enregistrées auprès de The Campaign Registry via Twilio et ne deviennent pas automatiquement des enregistrements Bird. Confirmez la procédure de migration ou d'enregistrement applicable avant de soumettre du travail payant. Les numéros que vous possédez chez Twilio 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'inscrire au 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 Twilio pour SMS : évaluation du produit et considérations de migration
-
Envoyer des SMS : le payload vers lequel vous portez, dans son intégralité
-
Désinscriptions 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 gestionnaire de statuts migre
-
Webhooks & events : configuration des endpoints 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.