Migrare SMS da Infobip
Questa pagina mappa SMS API, Blocklist e report di consegna di Infobip su Bird. Segui la guida principale alla migrazione nell'ordine indicato e usa queste corrispondenze per i passaggi 3, 4 e 5.
Due differenze fanno la maggior parte del lavoro. Il payload di Infobip è costruito per l'invio massivo, quindi un messaggio a una persona è un array di messaggi, ciascuno con un array di destinazioni, con il testo due livelli più in basso in content.text; POST /v1/sms/messages accetta from, to e text al livello principale. Il tuo base URL Infobip è personalizzato per account, nella forma xxxxx.api.infobip.com, autenticato con Authorization: App <key>. Bird invia da un host regionale con una bearer key, quindi l'host nel tuo codice cambia insieme alla struttura del payload.
Passa questo al tuo agente
Usa questo brief nel tuo coding agent. Parte dalla fase di discovery e produce un piano di migrazione revisionabile prima di qualsiasi modifica in produzione.
Esempio di codice
Help me migrate my SMS integration from Infobip 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/infobip.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 Infobip 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
La tabella di rinomina è breve perché il cambiamento di struttura è il vero lavoro:
| Funzione | Infobip | Bird |
|---|---|---|
| Destinatario | messages[].destinations[].to | to (uno per richiesta) |
| Mittente | messages[].sender | from |
| Corpo | messages[].content.text | text |
| Intento | (nessuno) | category, obbligatorio per il testo libero |
| Report di consegna | webhooks.delivery, per messaggio | un webhook dello spazio di lavoro iscritto agli eventi di consegna qui sotto |
| Contesto di andata e ritorno | webhooks.callbackData | metadata, ma vedi la nota sulla dimensione qui sotto |
| Raggruppamento campagna | options.campaignReferenceId | tags, solo per filtraggio; vedi sotto |
| Flash | options.flash | nessun equivalente |
| Validità | options.validityPeriod | nessun equivalente: validity_period viene rifiutato |
| Finestra di consegna | options.deliveryTimeWindow | nessun equivalente |
| Retry sicuri | (nessuno nei loro client generati) | header Idempotency-Key |
Note di porting:
- Tre livelli diventano zero. L'annidamento serve a trasportare molti messaggi e molte destinazioni in un'unica richiesta. Per inviare un messaggio a una persona, Bird accetta i tre campi al livello principale, quindi il builder che assemblava gli array va eliminato anziché tradotto.
- callbackData è più grande di metadata. Infobip accetta fino a 4000 caratteri e li restituisce nel report di consegna. metadata di Bird ha un limite di 2 KB serializzati ed è ripetuto su ogni evento del messaggio, non solo su quello terminale. L'echo è il vantaggio; il limite no, quindi qualsiasi dato vicino al limite va ridotto a una chiave da cercare altrove anziché trasportato intero.
- campaignReferenceId è contesto di reportistica, non una migrazione di campagna. tags di Bird sono coppie {name, value} che diventano dimensioni di query, così puoi segmentare le analytics per campagna come facevi prima. Quello che non portano con sé è un oggetto campagna: un tag non crea né configura un broadcast. Valuta il workflow delle campagne separatamente quando migri campagne rivolte al pubblico.
- campaignReferenceId non è una chiave di idempotenza. Infobip lo definisce come un ID per tracciare le performance di una campagna, quindi raggruppa ma non deduplica. Se ti affidavi a esso per rendere sicuro un retry, non eri protetto; l'header Idempotency-Key è ciò che lo fa qui.
- Nulla corrisponde a category. Le opzioni messaggio di Infobip coprono validità, finestra di consegna, flash e impostazioni regionali, e nessuna dichiara perché il messaggio viene inviato. Decidi per ogni tipo di messaggio se è transactional, marketing, authentication o service.
- Due campi opzionali non hanno una corrispondenza. validityPeriod è riservato e risponde a 422 SMSUnsupportedFeature; deliveryTimeWindow non ha un equivalente, quindi le finestre di programmazione passano al tuo dispatcher.
Trasferisci le rinunce
Infobip gestisce una Blocklist: un elenco dei destinatari che hanno rinunciato alle tue comunicazioni, amministrato tramite le API della Blocklist o tramite People nell'interfaccia web, con l'invio a chiunque vi compaia rifiutato. I trigger su parole chiave la alimentano automaticamente, quindi un iscritto che invia STOP finisce lì senza che la tua applicazione faccia nulla.
Questo rende l'esportazione la più semplice tra i provider di questo gruppo, e l'espansione la più grande. Una voce nella Blocklist è un iscritto per l'intero account; una soppressione Bird è una coppia mittente-iscritto. Ogni voce diventa quindi tante soppressioni quanti sono i tuoi mittenti: una Blocklist da mille voci e sei mittenti produce seimila record. Calcola il moltiplicatore prima di iniziare, perché è la differenza tra un'importazione che richiede un minuto e una che richiede batch e un log di avanzamento.
Preserva l'ambito originale della Blocklist. Non restringere una revoca durante la migrazione solo perché il nuovo modello tecnico può esprimere coppie più strette. Una preferenza a livello di spazio di lavoro può rappresentare una richiesta più ampia; è un proprietario separato rispetto alle soppressioni per mittente. Verifica entrambi quando decidi l'idoneità.
Importa attraverso il ciclo di soppressione. Leggere e gestire le soppressioni contiene il comando e il motivo per cui una soppressione manuale blocca ogni categoria, inclusa quella transazionale.
Una volta qui, Bird risponde autonomamente alle parole chiave di stop dal proprio catalogo per paese, quindi i trigger su parole chiave che avevi configurato non hanno un equivalente da ricostruire, e quelli personalizzati diventano regole su parole chiave. I motivi si accumulano anziché fondersi, quindi una coppia importata come manual che successivamente invia STOP conserva due record, e i messaggi restano bloccati finché entrambi non sono terminati.
Traduci 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 errore 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 prove di consegna resta unknown. Conserva lo stato e il codice grezzi del provider insieme all'esito normalizzato.
Infobip riporta uno status group e uno status name su ogni report di consegna, e Bird emette un tipo di evento:
| Esito | Infobip status group | Bird |
|---|---|---|
| API ha accettato il messaggio | PENDING | sms.accepted |
| Consegnato al carrier | PENDING | sms.sent |
| Il carrier ha confermato la consegna | DELIVERED | sms.delivered |
| Il carrier ha segnalato la mancata consegna | UNDELIVERABLE | sms.undelivered |
| Errore permanente | REJECTED | sms.failed |
| Rifiutato prima dell'invio | REJECTED | sms.rejected |
| Finestra di validità scaduta | EXPIRED | sms.expired |
EXPIRED è la riga da leggere con attenzione, perché copre due cose diverse sul loro lato e solo una di esse esiste qui. Infobip fa scadere un messaggio quando il proprio periodo di validità della piattaforma termina (per impostazione predefinita 48 ore) oppure quando l'operatore restituisce expired come stato finale. Bird non imposta alcuna finestra di validità propria e non esegue alcun timer che termina un messaggio, quindi sms.expired arriva unicamente dalla ricevuta di consegna del carrier. La metà segnalata dall'operatore si mappa direttamente; la metà del timer di piattaforma non ha equivalente, e un messaggio che sarebbe scaduto sul loro orologio qui resta in volo finché il carrier non decide.
REJECTED compare due volte intenzionalmente. Infobip lo usa sia per un messaggio che ha rifiutato essa stessa sia per uno che l'operatore ha restituito come rejected, che sono gli eventi di Bird scelti in base all'esito di elaborazione o del carrier e al suo motivo; un rifiuto del carrier può produrre sms.rejected. Lo status name all'interno del group è ciò che li distingue, quindi un handler che si ramificava solo sul group ha bisogno del name una volta arrivato qui. Anche PENDING copre due righe, perché è il group in cui il messaggio resta dall'accettazione fino all'arrivo di un report terminale.
Tre meccanismi cambiano insieme ai nomi:
- Le subscription sostituiscono i webhook per messaggio. Infobip assegna un webhook a ogni messaggio, quindi la destinazione è scelta da chi scrive la chiamata, e il content type è scelto con essa. Bird consegna JSON agli endpoint che il tuo spazio di lavoro registra, ciascuno iscritto ai tipi di evento desiderati, quindi un secondo consumer è una seconda subscription anziché una modifica in ogni punto di chiamata.
- Perdi la scelta per messaggio, incluso XML. Infobip permette a un messaggio di scegliere JSON o XML e allegare fino a 4000 caratteri di callback data. Bird invia solo JSON, e callbackData diventa metadata, che viene ripetuto su ogni evento di quel messaggio anziché solo sul report.
- Il pull diventa push. Infobip ti permette di recuperare i report da un endpoint di report oltre che riceverli. Bird non ha un equivalente di polling per gli eventi; iscriviti e leggi lo stato del messaggio tramite API quando ne hai bisogno su richiesta.
Registra l'endpoint una sola volta, specificando i tipi di evento che il tuo handler vuole: gli eventi sms.* sopra sono l'elenco a cui iscriversi, e non esiste un wildcard che li sostituisca. Bird invia JSON firmati secondo Standard Webhooks; 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.
Bird segnala un errore con un codice error standardizzato come invalid_destination, content_rejected, provider_unavailable o recipient_opted_out; l'elenco completo è nella pagina degli eventi. Mappa i tuoi alert su questi anziché sulle coppie numeriche group e name di Infobip.
Cutover
Destinazioni, mittenti e la rampa di traffico sono indipendenti dal provider e trattati nella guida principale. Tre elementi specifici di Infobip appartengono al piano di cutover.
L'host cambia, ed è configurazione, non codice. Il tuo base URL Infobip è assegnato per account; Bird invia da un host regionale scelto alla creazione del tuo spazio di lavoro. Individua ogni punto in cui l'host è impostato prima del cutover, incluse variabili d'ambiente, secrets manager e manifesti di deploy, perché un punto mancato fallisce a runtime anziché al build.
Il tuo brand e la tua campagna 10DLC sono registrati presso The Campaign Registry tramite le API di registrazione numeri di Infobip e non diventano automaticamente registrazioni Bird. Conferma la procedura di migrazione o registrazione applicabile prima di inviare lavoro a pagamento. Parti da Registrarsi per 10DLC: copre il significato di ogni campo, i tipi di entità riconosciuti dal registro e la chiamata dei requisiti che ti dice cosa fornire prima di creare il brand, che è il passaggio a pagamento.
I numeri di tua proprietà presso Infobip richiedono un porting che il supporto organizza, con i propri tempi e non i tuoi.
Prossimi passi
-
Confronto tra Bird e Infobip per SMS: valutazione del prodotto e considerazioni sulla migrazione
-
Invio di SMS: il payload verso cui stai migrando, nella sua interezza
-
Rinunce e parole chiave: copertura delle parole chiave per paese e gestione delle soppressioni
-
Eventi SMS: il vocabolario degli eventi verso cui si sposta il tuo handler di report
-
Webhook ed eventi: configurazione dell'endpoint e verifica Standard Webhooks
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.