Migrare SMS da Sinch
Questa pagina mappa SMS API, i gruppi e i delivery report di Sinch su Bird. Segui la guida principale alla migrazione nell'ordine indicato e usa queste corrispondenze per i passaggi 3, 4 e 5.
Due differenze strutturali condizionano il porting, ed entrambe costano più delle rinominazioni dei campi. Sinch lega l'invio a un service plan nel path dell'URL e invia un batch, quindi anche un messaggio a una sola persona è comunque un array; l'endpoint POST /v1/sms/messages di Bird accetta un destinatario sul tuo host regionale con una bearer key e nessun segmento di piano. Inoltre la registrazione US, che non puoi saltare, si trova su un host diverso da quello dell'invio, dietro una famiglia di credenziali diversa, quindi un codebase che raggiunge Sinch per entrambe le cose sta contattando due posti.
Passa questo al tuo agent
Usa questo brief nel tuo coding agent. 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 Sinch 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/sinch.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 Sinch 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 | Sinch | Bird |
|---|---|---|
| Destinatario | to (array, o un group ID) | to (uno per richiesta) |
| Mittente | from | from |
| Corpo | body | text |
| Routing account | service plan, nel path dell'URL | la bearer key; nessun segmento nel path |
| Intento | (nessuno) | category, obbligatorio su testo libero |
| Report di consegna | delivery_report + callback_url, per batch | un webhook dello spazio di lavoro; nessun controllo per singolo invio |
| Correlazione | client_reference | metadata, restituito su ogni evento |
| Etichette filtrabili | (nessuna) | coppie tags: {name, value} |
| Ripetizioni sicure | (non documentato) | header Idempotency-Key |
| Flash | flash_message | nessun equivalente |
Note sul porting:
- Scegli deliberatamente tra invio singolo, batch o broadcast. to è un array su Sinch e qui è un singolo numero, quindi usa invii singoli o l'endpoint batch per un massimo di 100 messaggi indipendenti. Una campagna verso un'audience appartiene al workflow di broadcast. Un batch che faceva riferimento a un gruppo richiede prima la risoluzione dell'appartenenza; vedi la sezione sugli opt-out, perché è lo stesso problema.
- body diventa text. È l'unica rinominazione che tocca ogni punto di chiamata.
- client_reference non è una chiave di idempotenza. Sinch lo definisce come un identificatore aggiunto al delivery report del batch, quindi correla ma non deduplica. Se ti affidavi a esso per rendere sicura una ripetizione, non eri coperto; Idempotency-Key è ciò che lo fa qui.
- Niente corrisponde a category. Decidi per ogni tipo di messaggio se è transactional, marketing, authentication o service.
Trasferire gli opt-out
Sinch registra chi è iscritto, e Bird ha bisogno di sapere chi si è cancellato. Questa inversione è il lavoro.
Sinch gestisce i destinatari come gruppi, e un gruppo può aggiornarsi automaticamente tramite keyword trigger, quindi un iscritto che invia STOP viene rimosso dal gruppo e un iscritto che invia SUBSCRIBE viene aggiunto. L'opt-out è dunque codificato come assenza da una lista anziché come presenza su una, e l'assenza non è esportabile: un numero mancante da un gruppo potrebbe essersi cancellato, non essersi mai iscritto, o essere stato rimosso da un'importazione sei mesi fa.
Quindi ricostruisci anziché esportare. Il tuo log dei messaggi in entrata è la fonte affidabile, perché alcuni opt-out sono nati come messaggi in entrata, mentre altri sono arrivati tramite supporto, moduli o un altro canale di preferenza, e quei messaggi esistono indipendentemente da ciò che dice ora l'appartenenza al gruppo. Dove hai mantenuto un tuo flag di cancellazione accanto al gruppo, quel flag è una prova migliore dell'appartenenza. Porta la lista ricostruita nel ciclo di soppressione, e mostrala a chi gestisce l'account prima di importarla: una voce errata qui blocca silenziosamente messaggi che intendevi inviare.
Una soppressione di Bird è una coppia mittente-iscritto, quindi un iscritto che blocchi su tre mittenti genera tre record. Leggere e gestire le soppressioni contiene il comando, e la ragione per cui una soppressione manuale blocca ogni categoria, inclusa quella transazionale.
Una volta qui, Bird risponde autonomamente alle keyword di stop dal proprio catalogo per paese, quindi il comportamento di auto-aggiornamento del gruppo non ha un equivalente da ricostruire: un iscritto che invia STOP produce una soppressione senza che la tua applicazione faccia nulla. I motivi si accumulano anziché fondersi, quindi una coppia che hai importato come manual e che in seguito invia STOP ha due record, e i messaggi restano bloccati finché entrambi non sono terminati.
Tradurre gli stati di consegna
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 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 sconosciuta. Conserva lo stato e il codice grezzi del provider accanto al risultato normalizzato.
Il riferimento ai delivery report di Sinch include queued, dispatched, delivered e diversi stati finali di errore distinti. Conserva codice e stato a livello di destinatario quando traduci il tuo reporting.
| Concetto Sinch | Decisione di integrazione Bird |
|---|---|
| Queued / Dispatched | Traccia accettazione e invio al carrier separatamente con sms.accepted e sms.sent. |
| Delivered | Registra l'esito di rete tramite sms.delivered; non dimostra la lettura. |
| Failed / Rejected / Deleted | Esamina il motivo riportato. Gli eventi di fallimento di Bird non si selezionano con una sostituzione solo per nome. |
| Aborted / Expired / Cancelled | Conserva la causa e la fase. L'invio singolo API di Bird non ha scheduling né timer di validità per ricreare questi controlli. |
| Unknown | Mantieni l'esito incerto; non contare come consegna una ricevuta mancante e non interpretabile. |
Il sms.expired di Bird segue un report di scadenza del carrier. Esamina il tuo comportamento esistente di scadenza e cancellazione separatamente da quell'evento, anziché mappare ogni timeout su di esso.
Nota inoltre che gli stati intermedi vengono riportati solo quando il batch ha richiesto il reporting per_recipient, che è parte di ciò che cambia qui sotto.
Perdi il controllo per singolo invio del reporting di consegna, e vale la pena dirlo chiaramente. Un batch Sinch sceglie la propria granularità di report e può sovrascrivere l'URL di callback del service plan per quel singolo invio. Bird non offre nessuna delle due: il reporting è una sottoscrizione dello spazio di lavoro, ogni evento sottoscritto viene consegnato e non c'è override per messaggio. Se usavi delivery_report per silenziare le campagne verbose, quel filtro si sposta nel tuo handler. Se indirizzavi i report di una campagna a un endpoint diverso, ora diventa un unico endpoint con un branch, oppure una seconda sottoscrizione.
Registra l'endpoint una sola volta, indicando i tipi di evento che il tuo handler vuole: gli eventi sms.* sopra elencati sono la lista a cui sottoscriversi, e non esiste un wildcard che li sostituisca. Bird invia JSON firmati secondo Standard Webhooks; Create an endpoint contiene il comando e l'unica cosa da fare bene alla prima chiamata, ovvero salvare il signing secret che la risposta mostra una sola volta.
Bird segnala un fallimento con un codice error standardizzato come invalid_destination, content_rejected, provider_unavailable o recipient_opted_out; l'elenco completo è nella pagina degli eventi.
Passaggio in produzione
Destinazioni, mittenti e il ramp-up del traffico sono indipendenti dal provider e trattati nella guida principale. Due elementi specifici di Sinch appartengono al piano di cutover.
Il tuo brand e la tua campagna 10DLC sono registrati presso The Campaign Registry tramite Sinch e non diventano automaticamente registrazioni Bird. Conferma la procedura di migrazione o registrazione applicabile prima di inviare lavoro a pagamento. Qui è anche dove l'integrazione si semplifica. Su Sinch l'API di registrazione è un host separato da quello dell'invio e utilizza credenziali di progetto anziché il token del service plan, e la stessa documentazione di Sinch dichiara che HTTP Basic è pensato solo per scopi di test ed è fortemente soggetto a limitazione delle richieste, quindi un'integrazione di produzione costruisce un flusso di token OAuth. Su Bird /v1/sms/10dlc/* si trova accanto a /v1/sms/messages sotto un unico base URL e un'unica chiave, quindi quel ciclo di vita del token viene ritirato anziché portato. Parti da Register for 10DLC, che spiega cosa significa ciascun campo e la chiamata di requisiti che ti dice cosa fornire prima di creare il brand, che è il passaggio a pagamento.
I numeri che possiedi su Sinch richiedono un porting che il supporto organizza, con i suoi tempi e non con i tuoi.
Passi successivi
-
Confronta Bird e Sinch per SMS: valutazione del prodotto e considerazioni sulla migrazione
-
Inviare SMS: il payload verso cui stai migrando, nella sua interezza
-
Opt-out e keyword: copertura delle keyword 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.