Sign inGet started

Migrer SMS depuis Plivo

Cette page fait correspondre l'API Message API de Plivo, les Powerpacks et les callbacks 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'envoi est la partie facile. Les deux acceptent du JSON avec des noms de champs en minuscules, et les deux conservent l'enregistrement 10DLC à côté de l'envoi plutôt que sur un hôte séparé. Deux choses changent. L'API POST https://api.plivo.com/v1/Account/{auth_id}/Message/ de Plivo s'authentifie avec un Auth ID et un Auth Token via HTTP Basic ; POST /v1/sms/messages utilise une clé bearer API sur votre hôte régional, sans segment de compte dans le chemin. Et un Powerpack Plivo regroupe un pool de numéros, le comportement d'expéditeur persistant et l'état de désinscription dans un seul objet ; Bird répartit tout cela entre expéditeurs, suppressions et règles de mots-clés, il n'y a donc rien à recréer en tant que Powerpack.

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 Plivo 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/plivo.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 Plivo 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

FonctionPlivoBird
Destinatairedstto (un par requête)
Expéditeursrc ou powerpack_uuidfrom
Corpstexttext
Sélecteur de canaltype : sms, mms, whatsapple endpoint lui-même ; /v1/sms/messages est SMS
Intention(aucune)category, obligatoire sur le texte libre
Accusés de réceptionurl + method, par messageun webhook d'espace de travail ; JSON POST uniquement, voir ci-dessous
Contexte aller-retourvotre propre stockage, indexé par UUIDmetadata : JSON arbitraire, renvoyé sur chaque événement
Libellés filtrables(aucun)tags : paires {name, value}
Réessais sûrs(non documenté)en-tête Idempotency-Key
Médiamedia_urlspas d'équivalent : media_urls est rejeté
Notes de portage :
  • Un UUID de Powerpack devient une simple valeur d'expéditeur. Plivo résout le pool de numéros, l'expéditeur persistant et la présence locale derrière l'UUID. 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.
  • type n'a pas d'équivalent car le endpoint le porte déjà. Plivo sélectionne le canal par requête ; les endpoints SMS, WhatsApp et autres canaux de Bird sont séparés. Un code qui change type à l'exécution se divise en appels à différents endpoints.
  • Rien dans l'API Message API 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 contexte marketing par défaut.
  • Examinez la sémantique de réessai séparément. La référence d'envoi de Plivo ne documente ni clé d'idempotence ni mécanisme de déduplication, un timeout vous laisse donc dans l'incertitude. Envoyez l'en-tête Idempotency-Key dès le premier portage pour réduire le risque de requêtes dupliquées dans la fenêtre de rejeu de trois heures ; ce n'est pas une garantie de livraison exactement une fois.

Transférer les désinscriptions

Le service DND de Plivo bloque les messages sortants d'un numéro Plivo vers une destination dès que cette destination répond avec un mot-clé de désinscription. Un envoi bloqué revient signalé avec le code d'erreur 200 de Plivo, qui fait partie de leurs codes d'erreur de message et non un statut HTTP, même s'il y ressemble. Cet appariement est aussi le fonctionnement d'une suppression Bird : un expéditeur et un abonné, le périmètre importé doit donc couvrir chaque expéditeur et programme inclus dans la demande de la personne.
Une chose s'étend, et c'est la raison de compter avant d'importer. Dans une campagne 10DLC aux États-Unis, Plivo traite une désinscription de n'importe quel numéro comme une désinscription de tous les numéros liés à cette campagne. Bird stocke des paires, donc un abonné qui s'est désinscrit d'une campagne à quatre numéros devient quatre suppressions au lieu d'une. Calculez combien de paires votre liste produit avant de commencer, car cela détermine si l'import est une boucle de dizaines ou de milliers.
L'extraction de la liste passe par un export de la console plutôt que par un appel API : filtrez les numéros dans la console Plivo, sélectionnez-les et utilisez Export CSV dans le menu Choose Action. Importez le résultat via la boucle de suppression. Lire et gérer les suppressions contient la commande et explique pourquoi une suppression manuelle bloque toutes les catégories, y compris le transactionnel.
Bird gère les mots-clés d'arrêt pris en charge via son catalogue par pays. Un envoi vers une paire supprimée est refusé à l'admission avec E12077 SMSRecipientSuppressed. Une désinscription signalée par l'opérateur est un résultat de livraison recipient_opted_out distinct. Remplacez la gestion du code d'erreur Plivo 200 par les chemins d'admission et de livraison appropriés, et recréez les réponses personnalisées sous forme de règles de mots-clés.
Cela compte à nouveau plus tard, une fois le trafic en cours. Les raisons s'empilent au lieu de fusionner : une paire importée en tant que manual qui envoie ensuite STOP reçoit un second enregistrement avec la raison keyword_stop, et les messages restent bloqués tant que chaque enregistrement de cette paire n'a pas pris fin. Reprendre un abonné que vous avez importé signifie donc supprimer les deux, et une reprise qui n'efface que l'enregistrement de mot-clé semble réussir sans rien changer.

Convertir 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 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ésultatPlivo message_stateBird
API a accepté le messagequeuedsms.accepted
Transmis à l'opérateursentsms.sent
L'opérateur a confirmé la livraisondeliveredsms.delivered
L'opérateur a signalé la non-livraisonundeliveredsms.undelivered
Échec permanentfailedsms.failed
Refusé avant l'envoirejectedsms.rejected
Fenêtre de validité écoulée(aucun)sms.expired
Deux mécanismes changent en même temps que les noms :
  • Les endpoints remplacent les URL de callback par message. Plivo prend un url à chaque envoi, la destination est donc choisie par celui qui écrit l'appel. Bird livre aux endpoints enregistrés par votre espace de travail, chacun abonné aux types d'événements souhaités, un nouveau consommateur est donc un nouvel abonnement plutôt qu'une modification à chaque point d'appel.
  • Des posts JSON signés remplacent un callback GET, si c'est ce que vous aviez choisi. Le champ method de Plivo sélectionne GET ou POST pour l'accusé de réception ; Bird envoie (POST) un événement JSON et ne propose pas de GET. Si vous aviez défini method=GET, votre handler lit le résultat dans les paramètres de chaîne de requête, et ce handler doit être réécrit plutôt que simplement réenregistré. Il en va de même un guide plus loin, sur le chemin Connectivity Platform.
  • Un seul schéma de signature remplace trois en-têtes. Plivo signe les callbacks avec X-Plivo-Signature-V2, X-Plivo-Signature-Ma-V2 et X-Plivo-Signature-V2-Nonce. Bird envoie JSON signé selon Standard Webhooks, le vérificateur est donc remplacé et non ajusté : substituez-le par la recette dans Webhooks & events.
Enregistrez le endpoint une seule fois en nommant les types d'événements souhaités par votre handler : 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 essentiel du premier appel : stocker le secret de signature que la réponse affiche une seule fois.
Les valeurs numériques error_code de Plivo 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. Mappez vos alertes sur ceux-ci.

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 à Plivo doivent figurer dans le plan de bascule.
Votre marque et votre campagne 10DLC sont enregistrées auprès de The Campaign Registry via Plivo et ne deviennent pas automatiquement des enregistrements Bird. Confirmez la procédure de migration ou d'enregistrement applicable avant de soumettre du travail payant. La chaîne est plus courte ici. Plivo enregistre d'abord un profil puis une marque rattachée à celui-ci, sous /v1/Account/{auth_id}/10dlc/ ; Bird n'a pas d'objet profil, les informations commerciales que Plivo détient sur le profil sont donc fournies directement sur la marque. Commencez par S'enregistrer pour le 10DLC : la page couvre la signification de chaque champ, les types d'entités reconnus par le registre et l'appel de prérequis qui vous indique ce qu'il faut fournir avant de créer la marque, qui est l'étape payante.
Les numéros que vous possédez chez Plivo nécessitent un portage organisé par le support, selon son propre calendrier et non le vôtre. Lancez-le tôt pour qu'il se déroule en parallèle de la modification du code.

Étapes suivantes

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.