Migrare SMS dalla Bird Connectivity Platform
Questa pagina mappa l'API Bird della Connectivity Platform su rest.messagebird.com, quella che potresti ancora conoscere come MessageBird API, verso Bird. Segui la guida principale alla migrazione in ordine e usa queste corrispondenze per i passi 3, 4 e 5.
Entrambe le piattaforme sono di Bird ed è l'API la parte che cambia. Tre differenze riguardano ogni chiamata. Le richieste vanno al tuo host regionale, https://us1.platform.bird.com o https://eu1.platform.bird.com, anziché a un unico host globale. L'autenticazione usa una chiave bearer API (Authorization: Bearer bk_us1_…) invece di Authorization: AccessKey. E l'invio è asincrono: POST /v1/sms/messages restituisce 202 Accepted con il messaggio in coda, mentre la Connectivity Platform restituiva l'oggetto messaggio con uno stato per destinatario già allegato.
Passa questo al tuo agente
Usa questo brief nel tuo coding agent. Parte dalla discovery e produce un piano di migrazione revisionabile prima di qualsiasi modifica in produzione.
Esempio di codice
Help me migrate my SMS integration from Bird Connectivity Platform 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/connectivity-platform.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 Connectivity Platform 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.Mappare la chiamata di invio
| Funzione | Connectivity Platform | Bird |
|---|---|---|
| Destinatario | recipients (fino a 50) | to, uno per richiesta |
| Mittente | originator | from |
| Corpo | body | text |
| Intent | (nessuno) | category, obbligatorio su testo libero |
| Codifica | datacoding | rilevata automaticamente |
| Traslitterazione | (nessuno) | options.smart_encoding (default false) |
| Riferimento client | reference | metadata, oppure tags quando filtri su di esso |
| Report di stato | reportUrl | un webhook dello spazio di lavoro iscritto agli eventi di consegna sotto |
| Riprovare sicuro | (nessuno) | header Idempotency-Key |
| Pianificazione | scheduledDatetime | nessun equivalente: scheduled_at viene rifiutato |
| Validità | validity | nessun equivalente: validity_period viene rifiutato |
| Selezione rotta | gateway | Bird seleziona la rotta |
| Classe messaggio | mclass | nessun equivalente |
| Binario e flash | type, typeDetails | solo testo |
Entrambi i campi rifiutati sono riservati e rispondono a 422 SMSUnsupportedFeature.
Note sul porting:
- L'array dei destinatari diventa una chiamata per destinatario. Una chiamata alla Connectivity Platform con 50 destinatari diventa 50 invii, oppure un batch di messaggi indipendenti. Il batch non è un fan-out di un unico corpo: ogni elemento porta il proprio destinatario, mittente e testo.
- datacoding non ha equivalente, ed è una scelta deliberata. Bird rileva la codifica dal corpo e riporta il conteggio dei segmenti sul messaggio. Se imposti datacoding: auto per mantenere i messaggi dentro GSM-7, il comportamento più vicino è options.smart_encoding, che applica la tabella di sostituzione documentata di Bird. Non è un traslitteratore generico; caratteri non supportati possono comunque richiedere la codifica Unicode.
- reference si divide in due campi. Inserisci un identificatore interno in metadata, che viene riportato su ogni evento webhook, e usa tags per le etichette a bassa cardinalità su cui vuoi filtrare e segmentare le analytics.
- Messaggi flash, payload binari e concatenazione UDH non migrano. Se usi mclass o typeDetails oggi, segnalalo al supporto prima di pianificare il cutover, non dopo.
- Usi anche la Connectivity Platform Verify API? Il porting è un lavoro separato con la sua guida: vedi Migrare Verify da un altro provider.
Trasferire gli opt-out
La Connectivity Platform lasciava a te la gestione delle keyword di stop, sia che l'avessi implementata in Flows sia nella tua applicazione sugli inbound. Bird svolge quel compito autonomamente: riconosce le keyword stop, start e help sui tuoi numeri nei paesi supportati, registra la soppressione e la applica a ogni invio. Dismetti un vecchio handler solo dopo aver verificato che il catalogo di Bird copre il suo comportamento e che il tuo processo di gestione delle preferenze funziona ancora.
Ciò che non viene dismesso è la lista. Esporta quello che conservi oggi, come coppie di numero dell'iscritto e originator da cui si è cancellato, e importalo attraverso il ciclo di soppressione prima del tuo primo invio in produzione. Se hai sempre mantenuto solo una lista globale di iscritti che hanno fatto opt-out, importa ogni iscritto una volta per ogni originator da cui invii ancora.
Tradurre i report di stato
Usa questa tabella per confrontare i concetti del ciclo di vita, non per rinominare gli eventi meccanicamente. Bird sceglie un evento di fallimento in base allo stato e alla ragione 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 sconosciuta. Conserva lo stato grezzo del provider e il codice accanto al tuo esito normalizzato.
| Esito | Connectivity Platform | Bird |
|---|---|---|
| Accettato dalla API | (sincrono) | sms.accepted |
| Consegnato al carrier | sent, buffered | sms.sent |
| Il carrier ha confermato la consegna | delivered | sms.delivered |
| Consegna fallita | delivery_failed | sms.failed |
| Finestra di validità scaduta | expired | sms.expired |
| Richiesta rifiutata all'ammissione | errore di richiesta | errore HTTP; nessun messaggio o evento |
| In attesa di invio | scheduled | nessun equivalente ancora |
Il meccanismo di consegna cambia più del vocabolario:
- I post firmati JSON sostituiscono le callback GET reportUrl. I report di stato arrivavano come richieste GET con l'esito nella query string (status, statusReason, statusErrorCode, mccmnc, price[amount]). Bird invia tramite POST un evento JSON agli endpoint registrati dal tuo spazio di lavoro, firmato secondo Standard Webhooks. L'handler va riscritto, non basta cambiare l'URL.
- La correlazione non dipende più da reference. Un report di stato era utile solo se avevi impostato un riferimento; un evento Bird porta sempre sms_id, entrambi i numeri e i tuoi metadata e tags riportati.
- La semantica dei tentativi è diversa. La Connectivity Platform riprovava un report fallito fino a 10 volte. Le consegne di Bird sono at-least-once e non ordinate: deduplica sull'header webhook-id e ordina per il timestamp nel payload.
- Riconcilia i costi tramite il messaggio e i titolari della fatturazione. Il report della Connectivity Platform portava price[amount] e price[currency]. Leggi il costo registrato del messaggio con GET /v1/sms/messages/{id} e riconcilia gli addebiti con la fatturazione. L'Stats API è per le metriche di consegna, non un totale di fatturazione autoritativo.
I messaggi in entrata funzionano allo stesso modo: iscriviti a sms.received una volta per lo spazio di lavoro invece di puntare ogni numero a un URL.
Cutover
Destinazioni, mittenti e la rampa di traffico sono indipendenti dal provider e trattati nella guida principale. L'aspetto da sollevare per tempo sono i tuoi originator: i sender ID alfanumerici vengono ricreati e, dove il paese lo richiede, ri-registrati qui, e i numeri che detieni sulla Connectivity Platform vengono spostati tramite un porting che il supporto organizza, non un'impostazione che puoi cambiare.
Passi successivi
-
Esplorare Bird SMS: workflow di prodotto e percorsi di implementazione
-
Invio SMS: il payload verso cui stai migrando, completo
-
Opt-out e keyword: ciò che Bird gestisce per te e come amministrare le soppressioni
-
Eventi SMS: il vocabolario degli eventi verso cui si sposta il tuo handler di stato
-
Webhook ed eventi: 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.