Migrare SMS da Plivo
Questa pagina mappa la Message API, i Powerpack e i callback di consegna di Plivo su Bird. Segui la guida principale alla migrazione nell'ordine indicato e usa queste corrispondenze per i passaggi 3, 4 e 5.
L'invio è la parte facile. Entrambi accettano JSON con nomi di campo in minuscolo ed entrambi gestiscono la registrazione 10DLC insieme all'invio anziché su un host separato. Cambiano due cose. La POST https://api.plivo.com/v1/Account/{auth_id}/Message/ di Plivo si autentica con Auth ID e Auth Token tramite HTTP Basic; POST /v1/sms/messages accetta una chiave bearer API verso il tuo host regionale, senza segmento account nel path. E un Powerpack di Plivo raggruppa pool di numeri, comportamento sticky sender e stato di opt-out in un unico oggetto; Bird li separa tra sender, soppressioni e regole per parole chiave, quindi non c'è nulla da ricreare come Powerpack.
Passa questo al tuo agente
Usa questo brief nel tuo agente di codifica. Inizia con la discovery e produce un piano di migrazione verificabile prima di qualsiasi modifica in produzione.
Esempio di codice
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.Mappa la chiamata di invio
| Funzione | Plivo | Bird |
|---|---|---|
| Destinatario | dst | to (uno per richiesta) |
| Mittente | src o powerpack_uuid | from |
| Corpo | text | text |
| Selettore di canale | type: sms, mms, whatsapp | l'endpoint stesso; /v1/sms/messages è SMS |
| Intent | (nessuno) | category, obbligatorio per testo libero |
| Report di consegna | url + method, per messaggio | un webhook dello spazio di lavoro; solo JSON POST, vedi sotto |
| Contesto di andata e ritorno | un tuo store, indicizzato per UUID | metadata: JSON arbitrario, ripetuto su ogni evento |
| Etichette filtrabili | (nessuna) | tags: coppie {name, value} |
| Riprovare in sicurezza | (non documentato) | header Idempotency-Key |
| Media | media_urls | nessun equivalente: media_urls viene rifiutato |
Note sul porting:
- Un UUID Powerpack diventa un semplice valore sender. Plivo risolve il pool di numeri, lo sticky sender e la presenza locale dietro l'UUID. Bird accetta il mittente direttamente in from, quindi sceglilo per ogni invio oppure usa un invio con template, che seleziona un mittente valido per la destinazione e rifiuta from.
- type non ha un corrispettivo perché l'endpoint lo incorpora. Plivo seleziona il canale per ogni richiesta; SMS, WhatsApp e gli altri canali di Bird sono endpoint separati. Un codebase che commuta type a runtime si divide in chiamate a endpoint diversi.
- Nulla nella Message API corrisponde a category. Decidi per ogni tipo di messaggio se è transactional, marketing, authentication o service. Il traffico di autenticazione in particolare va etichettato come tale anziché lasciato nel default marketing.
- Rivedi la semantica dei tentativi separatamente. La documentazione di invio di Plivo non prevede chiave di idempotenza né meccanismo di deduplicazione, quindi un timeout lascia nell'incertezza. Invia l'header Idempotency-Key fin dal primo porting per ridurre il rischio di richieste duplicate nella finestra di replay di tre ore; non è una garanzia di consegna exactly-once.
Trasferire gli opt-out
Il servizio DND di Plivo blocca i messaggi in uscita da un numero Plivo verso una destinazione quando quella destinazione risponde con una parola chiave di opt-out. Un invio bloccato viene restituito con il codice di errore 200 di Plivo, che è uno dei codici di errore per messaggi e non uno status HTTP, per quanto possa sembrarlo. Quella coppia è il funzionamento anche di una soppressione Bird: un mittente e un iscritto, quindi l'ambito importato deve coprire ogni mittente e programma incluso nella richiesta dell'utente.
Una cosa si espande, ed è il motivo per contare prima di importare. All'interno di una campagna 10DLC US, Plivo tratta un opt-out da un qualsiasi numero come un opt-out da tutti i numeri collegati a quella campagna. Bird memorizza coppie, quindi un iscritto che ha fatto opt-out da una campagna con quattro numeri diventa quattro soppressioni anziché una. Calcola quante coppie produce la tua lista prima di iniziare, perché questo determina se l'importazione è un ciclo di decine o di migliaia.
L'estrazione della lista è un export dalla console, non una chiamata API: filtra i numeri nella console Plivo, selezionali e usa Export CSV dal menu Choose Action. Importa il risultato tramite il ciclo di soppressione. Leggere e gestire le soppressioni contiene il comando e spiega perché una soppressione manuale blocca ogni categoria, inclusa quella transazionale.
Bird gestisce le parole chiave di stop supportate tramite il suo catalogo specifico per paese. Un invio verso una coppia soppressa viene rifiutato all'ammissione con E12077 SMSRecipientSuppressed. Un opt-out segnalato dal carrier è un risultato di consegna recipient_opted_out separato. Sostituisci la gestione del codice di errore Plivo 200 con i percorsi di ammissione e consegna appropriati, e ricrea eventuali risposte personalizzate come regole per parole chiave.
Questo conta di nuovo in seguito, quando il traffico è attivo. I motivi si accumulano anziché unirsi: una coppia importata come manual che poi invia STOP ottiene un secondo record con motivo keyword_stop, e i messaggi restano bloccati finché ogni record per quella coppia non è terminato. Quindi ripristinare un iscritto importato in precedenza significa rimuovere entrambi, e un ripristino che cancella solo il record della parola chiave sembra riuscito ma non cambia nulla.
Tradurre gli stati di consegna
Usa questa tabella per confrontare i concetti del ciclo di vita, non per rinominare eventi meccanicamente. Bird sceglie un evento di fallimento in base allo stato e al motivo riportati. Una richiesta API rifiutata non crea alcun messaggio; un rifiuto dopo l'accettazione può produrre sms.rejected, incluso un rifiuto del carrier. L'assenza di evidenza di consegna resta unknown. Conserva lo stato e il codice grezzi del provider accanto al risultato normalizzato.
| Esito | Plivo message_state | Bird |
|---|---|---|
| API ha accettato il messaggio | queued | sms.accepted |
| Consegnato al carrier | sent | sms.sent |
| Il carrier ha confermato la consegna | delivered | sms.delivered |
| Il carrier ha segnalato la mancata consegna | undelivered | sms.undelivered |
| Fallimento permanente | failed | sms.failed |
| Rifiutato prima dell'invio | rejected | sms.rejected |
| Finestra di validità scaduta | (nessuno) | sms.expired |
Due meccaniche cambiano insieme ai nomi:
- Gli endpoint sostituiscono le URL di callback per messaggio. Plivo accetta un url a ogni invio, quindi la destinazione è scelta da chi scrive la chiamata. Bird consegna agli endpoint registrati dal tuo spazio di lavoro, ciascuno iscritto ai tipi di evento desiderati, quindi un nuovo consumer è una nuova sottoscrizione anziché una modifica a ogni call site.
- Post firmati JSON sostituiscono un callback GET, se è quello che avevi scelto. Il method di Plivo seleziona GET o POST per il report di consegna; Bird invia tramite POST un evento JSON e non offre GET. Se hai impostato method=GET, il tuo handler legge l'esito dai parametri della query string, e quel handler va riscritto, non semplicemente ri-registrato. Lo stesso vale nella guida accanto, sul percorso Connectivity Platform.
- Un unico schema di firma sostituisce tre header. Plivo firma i callback con X-Plivo-Signature-V2, X-Plivo-Signature-Ma-V2 e X-Plivo-Signature-V2-Nonce. Bird invia JSON firmati secondo Standard Webhooks, quindi il verificatore va sostituito, non adattato: scambialo con la ricetta in Webhooks & events.
Registra l'endpoint una sola volta, indicando i tipi di evento che il tuo handler vuole: gli eventi sms.* elencati sopra sono la lista a cui iscriversi, e non esiste un wildcard che li sostituisca. Creare un endpoint contiene il comando e l'unica cosa da fare bene alla prima chiamata, cioè salvare il signing secret che la risposta mostra una sola volta.
I valori numerici error_code di Plivo non hanno una corrispondenza uno a uno. Bird riporta un fallimento con un codice error standardizzato come invalid_destination, content_rejected, provider_unavailable o recipient_opted_out; la lista completa è nella pagina degli eventi. Mappa i tuoi alert su quelli.
Cutover
Destinazioni, mittenti e la rampa di traffico sono indipendenti dal provider e trattati nella guida principale. Due elementi specifici di Plivo appartengono al piano di cutover.
Il tuo brand e la tua campagna 10DLC sono registrati presso The Campaign Registry tramite Plivo e non diventano automaticamente registrazioni Bird. Conferma la procedura di migrazione o registrazione applicabile prima di avviare lavoro a pagamento. Qui la catena è più corta. Plivo registra prima un profilo e poi un brand collegato, sotto /v1/Account/{auth_id}/10dlc/; Bird non ha un oggetto profilo, quindi i dettagli aziendali che Plivo conserva nel profilo vengono forniti direttamente sul brand. Parti da Registrarsi per 10DLC: spiega il significato di ogni campo, i tipi di entità riconosciuti dal registro e la chiamata requirements che indica cosa fornire prima di creare il brand, che è il passaggio a pagamento.
I numeri che possiedi su Plivo richiedono un porting gestito dal supporto, con tempi propri e non tuoi. Avvialo presto e procederà in parallelo alla modifica del codice.
Passi successivi
-
Confronto tra Bird e Plivo per SMS: valutazione del prodotto e considerazioni sulla migrazione
-
Invio di SMS: il payload completo verso cui stai migrando
-
Opt-out e parole chiave: copertura delle parole chiave per paese e gestione delle soppressioni
-
Eventi SMS: il vocabolario di eventi verso cui si sposta il tuo callback handler
-
Webhooks & events: configurazione degli endpoint e verifica Standard Webhooks
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.