Migrer SMS depuis Bandwidth
Cette page fait correspondre l'API Messages, les Applications et les callbacks de messages de Bandwidth à 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. Bandwidth répartit le canal sur deux hôtes : l'envoi se trouve sur l'hôte de messagerie sous le chemin de votre compte, authentifié via HTTP Basic, tandis que l'enregistrement 10DLC se trouve sur l'hôte API principal. Bird regroupe l'envoi, l'enregistrement et les événements de livraison sous une seule URL de base et une seule clé bearer. Et l'applicationId présent sur chaque envoi Bandwidth porte la configuration des callbacks ; Bird n'a pas d'objet équivalent, car les callbacks sont un abonnement de l'espace de travail et non une propriété du message.
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 Bandwidth 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/bandwidth.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 Bandwidth 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 | Bandwidth | Bird |
|---|---|---|
| Destinataire | to (tableau) | to (un par requête) |
| Expéditeur | from | from |
| Corps | text | text |
| Routage des callbacks | applicationId | un webhook d'espace de travail abonné aux événements de livraison ci-dessous |
| Intention | (aucune) | category, obligatoire sur le texte libre |
| Libellé libre | tag (une chaîne) | metadata ; tags uniquement si vous pouvez le nommer |
| Contexte aller-retour | votre propre stockage, indexé par ID | metadata : JSON arbitraire, renvoyé sur chaque événement |
| Priorité de livraison | priority | pas d'équivalent |
| Réessais sûrs | (aucun dans leur spécification) | en-tête Idempotency-Key |
| Média | media | pas d'équivalent : media_urls est rejeté |
Notes de portage :
- to passe d'un tableau à un seul destinataire. Bandwidth accepte une liste ; Bird envoie un message par requête. Une boucle remplace le tableau, et chaque appel peut porter son propre Idempotency-Key.
- L'applicationId disparaît au lieu d'être déplacé. Il sert à indiquer à Bandwidth où envoyer les callbacks. Sur Bird, c'est un abonnement de l'espace de travail, donc rien dans l'envoi ne le désigne.
- tag et tags ne sont pas le même champ. Le tag de Bandwidth est une seule chaîne libre ; les tags de Bird sont des paires {name, value} qui deviennent des dimensions de requête. Une seule chaîne opaque se transporte généralement mieux dans metadata.
- Rien dans l'API Messages ne correspond à category. Décidez par type de message s'il s'agit de transactional, marketing, authentication ou service.
Transférer les opt-outs
Il n'y a pas de liste à exporter, et c'est la conclusion plutôt qu'une lacune de ce guide.
En dehors du toll-free, Bandwidth ne gère pas de listes d'opt-in ou d'opt-out pour vous. Leur propre documentation le dit clairement : la responsabilité de respecter les commandes et de maintenir les listes incombe au client. Le toll-free est l'exception, où STOP et ses variantes sont appliqués au niveau du réseau indépendamment de votre configuration ; les long codes et les short codes ne bénéficient pas de ce traitement.
Dans cette migration, la liste faisant autorité est donc déjà la vôtre. C'est une table, un indicateur sur un enregistrement de contact, ou une vérification que votre chemin d'envoi exécute avant d'appeler l'API, et la première tâche consiste à déterminer lequel fait autorité plutôt que de demander un export à quiconque. Votre propre journal de messages entrants est le recours : certains opt-outs proviennent de messages entrants, tandis que d'autres sont venus du support, de formulaires ou d'un autre canal de préférences.
Importez ensuite via la boucle de suppression. Une suppression Bird est une paire expéditeur-abonné, donc un abonné que vous avez bloqué sur trois expéditeurs représente trois enregistrements. Lire et gérer les suppressions contient la commande, et la raison pour laquelle une suppression manuelle bloque toutes les catégories, y compris les messages transactionnels.
Décidez qui est propriétaire de la liste après la bascule, car c'est ici que vous gagnez quelque chose et pouvez en perdre la trace. Bird répond aux mots-clés d'arrêt depuis son propre catalogue par pays, donc dès que vous envoyez ici, la plateforme gère les suppressions pour vous : un abonné qui envoie STOP produit un enregistrement avec la raison keyword_stop sans que votre application ne fasse quoi que ce soit. Si votre code maintient sa propre liste et continue de l'appliquer, les deux divergent, et le symptôme habituel est un abonné qui a repris d'un côté et pas de l'autre. Gardez le propriétaire des préférences d'audience explicite et synchronisez les changements pertinents de manière délibérée. Les suppressions par expéditeur seules ne couvrent pas les préférences à l'échelle de l'espace de travail ni les demandes en dehors du catalogue de mots-clés. Les raisons s'empilent au lieu de fusionner, donc une paire que vous avez importée comme manual et qui envoie ensuite STOP détient deux enregistrements, et les messages restent bloqués tant que les deux n'ont pas pris fin.
Convertir les statuts de livraison
Utilisez cette table pour comparer les concepts de cycle de vie, pas pour renommer mécaniquement les événements. Bird choisit un événement d'échec à partir 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. L'absence de preuve de livraison reste inconnue. Conservez le statut brut du fournisseur et le code aux côtés de votre résultat normalisé.
| Résultat | Type de callback Bandwidth | Bird |
|---|---|---|
| API a accepté le message | la réponse 202, pas d'événement | sms.accepted |
| Remis à l'opérateur | message-sent | sms.sent |
| L'opérateur a confirmé la livraison | message-delivered | sms.delivered |
| N'a jamais atteint l'opérateur | message-failed | sms.rejected |
| Rejeté par l'opérateur | message-failed | sms.failed |
| L'opérateur a signalé la non-livraison | message-failed | sms.undelivered |
| L'opérateur a abandonné | message-failed | sms.expired |
| Requête refusée à l'admission | erreur de requête | erreur HTTP ; pas de message ni d'événement |
Deux éléments de cette table méritent une action plutôt qu'une simple lecture.
Reconstruisez la gestion des états terminaux autour de l'enregistrement de message et des horodatages d'événements de Bird. Les livraisons de webhooks peuvent se répéter ou arriver dans le désordre ; votre consommateur ne doit pas supposer une seule livraison d'un seul callback final. Un statut rejeté et un statut d'échec de livraison peuvent sélectionner des événements Bird différents même lorsque les deux proviennent de l'aval.
message-sending n'a pas de ligne car il est réservé à MMS, et message-read est réservé à RBM ; aucun des deux ne se déclenche pour SMS.
Deux mécanismes changent avec les noms :
- Les abonnements remplacent l'Application. Bandwidth route les callbacks selon l'applicationId nommé par le message. Bird livre aux points de terminaison enregistrés par votre espace de travail, chacun abonné aux types d'événements qu'il souhaite, donc un nouveau consommateur est un nouvel abonnement plutôt qu'une nouvelle Application et un redéploiement.
- Standard Webhooks remplace leur authentification de callbacks. Bird envoie des JSON signés selon Standard Webhooks ; remplacez la vérification par la méthode décrite dans Webhooks & events.
Enregistrez le point de terminaison une seule fois, en nommant les types d'événements que votre handler attend : les événements sms.* ci-dessus sont la liste à laquelle s'abonner, et il n'existe pas de joker pour les remplacer. Créer un point de terminaison contient la commande et le point à réussir dès le premier appel, à savoir stocker le secret de signature que la réponse affiche une seule fois.
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 à Bandwidth appartiennent au plan de bascule : votre marque et votre campagne 10DLC sont enregistrées auprès de The Campaign Registry via Bandwidth 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 Bandwidth 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 : la 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 Bandwidth pour SMS : évaluation du produit et considérations 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 de callbacks migre
-
Webhooks & events : configuration du point de terminaison 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.