Migrer SMS depuis un autre fournisseur

1. Activer vos pays de destination
2. Configurer un expéditeur
3. Adapter l'appel d'envoi vers POST /v1/sms/messages
4. Importer votre liste de désinscriptions
5. Basculer les accusés de réception vers des webhooks
6. Tester avec des destinations simulées avant la bascule

1. Activer vos pays de destination

2. Configurer un expéditeur

• Créez vous-même les identifiants d’expéditeur alphanumériques sous SMS > Senders. Si le pays de destination exige l’enregistrement de l’identifiant d’expéditeur, soumettez la demande et attendez son approbation avant d’y acheminer du trafic.
• Le trafic commercial US via des numéros longs locaux nécessite la marque et la campagne 10DLC applicables, configurées sous SMS > 10DLC, tandis que les numéros gratuits et les numéros courts dédiés ont leurs propres programmes de vérification ou de candidature. Les États-Unis n'acceptent pas du tout les identifiants d'expéditeur alphanumériques : un identifiant européen qui fonctionne partout ailleurs n'a pas d'équivalent aux États-Unis.
• Les numéros passent par le workflow Numbers, avec une disponibilité et un provisionnement éventuellement géré selon le type et la destination. Consultez SMS numbers pour le bon parcours ; ajouter un identifiant d'expéditeur alphanumérique n'acquiert pas de numéro.
• Conserver vos numéros actuels n'est pas en libre-service : Bird ne propose pas de flux de portage entrant pilotable depuis le tableau de bord. Si vos abonnés répondent à des numéros que vous possédez aujourd'hui, lancez le portage auprès du support avant de planifier une date de bascule, et prévoyez que le portage et la modification du code soient deux événements distincts.

3. Adapter l'appel d'envoi

• Un destinataire par requête. Bird n'a pas de tableau de destinataires. Si votre fournisseur actuel distribue un appel vers plusieurs numéros, cela devient un appel par destinataire, ou un batch de messages indépendants dans une seule requête.
• category est obligatoire pour le texte libre, et ses valeurs sont transactional, marketing, authentication ou service. La plupart des fournisseurs déduisent l'intention de la campagne ou de l'expéditeur ; ici vous la déclarez par message, et si le pays de destination exige que l'expéditeur soit enregistré, cet enregistrement est approuvé pour une catégorie et un envoi hors de celle-ci est rejeté avec 422 SenderCategoryNotPermitted. Le statut active de l'expéditeur ne peut pas vous l'indiquer à l'avance, car il est rapporté sans référence à une catégorie ; consultez plutôt les exigences par pays. Faites-le correctement dès le portage au lieu de tout mettre par défaut sur une seule valeur.
• Le corps est limité en segments, et Bird ne tronque pas. Un corps trop long est rejeté avec un 422. Les caractères non GSM-7 réduisent de plus de moitié ce qui tient dans un segment : si votre fournisseur actuel translittérait silencieusement les guillemets courbes et les tirets, activez options.smart_encoding pour conserver les comptages de segments auxquels vous êtes habitué. Cette option est désactivée par défaut car elle modifie le corps que vous avez composé.
• Utilisez tags pour les dimensions de filtrage et metadata pour le contexte. Les tags sont des paires {name, value} sur lesquelles vous pouvez filtrer et découper vos analyses ; les métadonnées sont des JSON arbitraires que Bird stocke, retourne en lecture et renvoie dans chaque événement webhook. Un champ de référence client unique chez votre ancien fournisseur correspond généralement à metadata.
• La planification par envoi individuel et les MMS sortants nécessitent un plan distinct. scheduled_at, media_urls, validity_period et personalization par destinataire sont des champs réservés, rejetés avec 422 SMSUnsupportedFeature. Ces parties de votre intégration ne migrent pas avec le reste : conservez les envois planifiés dans votre propre file d'attente et appelez le point de terminaison d'envoi au moment de soumission prévu. Pour les campagnes d'audience, évaluez Broadcasts séparément ; un broadcast n'est pas un simple renommage de champ du point de terminaison.
• Utilisez Idempotency-Key pour des réessais bornés. Envoyez une clé unique par message logique et réutilisez-la pour les réessais de la requête identique dans la fenêtre de rejeu de trois heures. Les rejeux réduisent les requêtes en double mais ne constituent pas une garantie de livraison exactement une fois. Voir Idempotency.

4. Importer votre liste de désinscriptions

while IFS=, read -r destination originator; do
  curl -s -X POST https://us1.platform.bird.com/v1/sms/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"destination\": \"$destination\", \"originator\": \"$originator\"}"
done < opt-outs.csv

• Les deux extrémités sont requises pour les suppressions spécifiques à un expéditeur. Une désinscription à l'échelle de l'espace de travail relève du preference owner distinct. L'appel est idempotent : 201 enregistre une nouvelle suppression, 200 retourne la suppression manuelle déjà en place, donc relancer un import partiel est sans risque.
• Les paires importées reçoivent reason: manual, qui bloque toutes les catégories y compris transactionnelles. C'est plus strict qu'une suppression que Bird enregistre lui-même à partir d'un mot-clé d'arrêt. Si un abonné s'est désinscrit uniquement du marketing, décidez délibérément si vous devez importer cette paire.

5. Basculer les accusés de réception vers des webhooks

• Les livraisons sont signées selon Standard Webhooks, en utilisant les en-têtes webhook-id, webhook-timestamp et webhook-signature avec un HMAC-SHA256 sur {id}.{timestamp}.{raw body}. Les fournisseurs qui signent avec leur propre schéma nécessitent un remplacement de la vérification ; la recette est dans Webhooks & events.
• La livraison est au-moins-une-fois et non ordonnée. Dédupliquez sur webhook-id et triez par le timestamp du payload, jamais par ordre d'arrivée.

6. Tester avec des destinations simulées

• Ce sont des numéros américains, donc les États-Unis doivent être activés sous Destinations, et from doit être un expéditeur valide pour les États-Unis. Un identifiant d'expéditeur alphanumérique y est rejeté.
• Un envoi simulé est facturé au tarif normal de la destination. Rien n'atteint un téléphone, mais le débit du portefeuille est réel : dimensionnez votre test de fumée en conséquence.
• Le résultat dépend uniquement de la destination. Il n'y a ni identifiant de test séparé, ni mode test à désactiver.

Migration depuis un fournisseur spécifique

• Twilio : PascalCase encodé en formulaire vers JSON, Messaging Services vers des expéditeurs, StatusCallback vers des webhooks souscrits
• Plivo : src et dst vers from et to, Powerpacks vers des expéditeurs, paires DND vers des suppressions
• Telnyx : l'envoi le plus proche de celui de Bird, les profils de messagerie décomposés en expéditeurs et abonnements, les opt-outs au niveau du profil vers des paires
• Bandwidth : deux hôtes vers un seul, les callbacks applicationId vers des webhooks d'espace de travail, et une liste de désinscriptions que votre propre application détient déjà
• Sinch : les lots vers des envois unitaires, body vers text, l'appartenance aux groupes reconstruite en suppressions
• Infobip : un payload à trois niveaux aplati, une URL de base par compte vers un hôte régional, une Blocklist étendue en paires
• Bird Connectivity Platform : le rest.messagebird.com API, originator et recipients vers from et to, les callbacks GET reportUrl vers des webhooks signés

Étapes suivantes

• Comparer les fournisseurs SMS : évaluer le workflow produit et les considérations de migration
• Envoyer des SMS : le payload d'envoi complet, les expéditeurs, les segments et le modèle asynchrone 202
• Désinscriptions et mots-clés : ce que Bird gère pour vous, et comment administrer les suppressions
• Événements SMS : le vocabulaire des événements et les payloads par événement
• Webhooks & events : configuration des endpoints, vérification de signature, réessais et rejeu