# Migrare SMS da Bandwidth

Questa pagina mappa l'API Messages di Bandwidth, le Application e i callback dei messaggi su Bird. Segui la [guida principale alla migrazione](/docs/guides/sms/migrate) nell'ordine indicato e usa queste corrispondenze per i passaggi 3, 4 e 5.

Due differenze condizionano l'intera migrazione. Bandwidth divide il canale su due host: l'invio risiede sull'host di messaggistica sotto il percorso del tuo account, autenticato tramite HTTP Basic, mentre la registrazione 10DLC risiede sull'host API principale. Bird riunisce invio, registrazione ed eventi di consegna sotto un unico URL base e un'unica chiave bearer. E l'`applicationId` presente su ogni invio Bandwidth contiene la configurazione dei callback; Bird non ha un oggetto equivalente, perché i callback sono una sottoscrizione dello spazio di lavoro e non una proprietà del messaggio.

## Passa questo al tuo agente

Usa questo brief nel tuo agente di codifica. Parte dalla fase di discovery e produce un piano di migrazione revisionabile prima di qualsiasi modifica in produzione.

```text
Help me migrate my SMS integration from Bandwidth 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/bandwidth.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 Bandwidth 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               | Bandwidth                        | Bird                                                                         |
| ---------------------- | -------------------------------- | ---------------------------------------------------------------------------- |
| Destinatario           | `to` (array)                     | `to` (uno per richiesta)                                                     |
| Mittente               | `from`                           | `from`                                                                       |
| Corpo                  | `text`                           | `text`                                                                       |
| Routing dei callback   | `applicationId`                  | un webhook dello spazio di lavoro sottoscritto agli eventi di consegna sotto |
| Intent                 | (nessuno)                        | `category`, obbligatorio per il testo libero                                 |
| Etichetta libera       | `tag` (una stringa)              | `metadata`; `tags` solo se puoi dargli un nome                               |
| Contesto round-trip    | un tuo store, indicizzato per ID | `metadata`: JSON arbitrario, ripetuto su ogni evento                         |
| Priorità di consegna   | `priority`                       | nessun equivalente                                                           |
| Riprovare in sicurezza | (nessuno nella loro specifica)   | header `Idempotency-Key`                                                     |
| Media                  | `media`                          | nessun equivalente: `media_urls` viene rifiutato                             |

Note sulla migrazione:

- **`to` passa da un array a un singolo destinatario.** Bandwidth accetta una lista; Bird invia un messaggio per richiesta. Un ciclo sostituisce l'array e ogni chiamata può portare il proprio `Idempotency-Key`.
- **L'`applicationId` scompare invece di spostarsi.** Serve a indicare a Bandwidth dove inviare i callback. Su Bird è una sottoscrizione dello spazio di lavoro, quindi nulla nell'invio lo referenzia.
- **`tag` e `tags` non sono lo stesso campo.** Il `tag` di Bandwidth è una singola stringa libera; i `tags` di Bird sono coppie `{name, value}` che diventano dimensioni di query. Una singola stringa opaca si trasporta meglio in `metadata`.
- **Nulla nell'API Messages corrisponde a `category`.** Decidi per ogni tipo di messaggio se è `transactional`, `marketing`, `authentication` o `service`.

## Trasferire gli opt-out

**Non esiste una lista da esportare, e questa è la conclusione, non una lacuna di questa guida.**

Al di fuori del toll-free, Bandwidth non gestisce liste di opt-in o opt-out per te. La loro stessa documentazione lo dice chiaramente: l'onere di rispettare i comandi e mantenere le liste ricade sul cliente. Il toll-free è l'eccezione, dove `STOP` e le sue varianti sono applicate a livello di rete indipendentemente dalla tua configurazione; i long code e gli short code non hanno questo trattamento.

Quindi in questa migrazione la lista autorevole è già tua. È una tabella, un flag su un record di contatto o un controllo che il tuo percorso di invio esegue prima di chiamare l'API, e il primo compito è decidere quale di queste fonti è autorevole anziché richiedere un'esportazione a qualcuno. Il tuo log dei messaggi in entrata è il fallback: alcuni opt-out sono nati come messaggi in entrata, mentre altri sono arrivati tramite supporto, moduli o un altro canale di preferenza.

Poi importa attraverso il [ciclo di soppressione](/docs/guides/sms/migrate#4-carry-over-your-opt-out-list). Una soppressione Bird è una coppia mittente-iscritto, quindi un iscritto che hai bloccato su tre mittenti corrisponde a tre record. [Leggere e gestire le soppressioni](/docs/guides/sms/opt-outs-and-keywords#reading-and-managing-suppressions) contiene il comando e la ragione per cui una soppressione manuale blocca ogni categoria, inclusa quella transazionale.

**Decidi chi possiede la lista dopo il cutover, perché qui guadagni qualcosa e puoi perderne traccia.** Bird risponde alle keyword di stop dal proprio catalogo per paese, quindi quando inizi a inviare da qui la piattaforma gestisce le soppressioni per te: un iscritto che invia `STOP` produce un record con reason `keyword_stop` senza che la tua applicazione faccia nulla. Se il tuo codice mantiene una propria lista e continua ad applicarla, le due divergono, e il sintomo più comune è un iscritto che ha ripreso su un lato ma non sull'altro. Mantieni esplicito chi possiede le preferenze dell'audience e sincronizza le modifiche rilevanti in modo deliberato. Le soppressioni per mittente da sole non coprono le preferenze a livello di spazio di lavoro né le richieste al di fuori del catalogo di keyword. Le reason si accumulano anziché fondersi, quindi una coppia importata come `manual` che in seguito invia `STOP` produce due record, e i messaggi restano bloccati fino a quando entrambi 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 errore in base allo stato e alla reason 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 tuo esito normalizzato.

| Esito                                       | Tipo di callback Bandwidth       | Bird                                   |
| ------------------------------------------- | -------------------------------- | -------------------------------------- |
| API ha accettato il messaggio               | la risposta `202`, nessun evento | `sms.accepted`                         |
| Consegnato al carrier                       | `message-sent`                   | `sms.sent`                             |
| Il carrier ha confermato la consegna        | `message-delivered`              | `sms.delivered`                        |
| Non ha mai raggiunto il carrier             | `message-failed`                 | `sms.rejected`                         |
| Il carrier l'ha rifiutato                   | `message-failed`                 | `sms.failed`                           |
| Il carrier ha segnalato la mancata consegna | `message-failed`                 | `sms.undelivered`                      |
| Il carrier ha rinunciato                    | `message-failed`                 | `sms.expired`                          |
| Richiesta rifiutata in ammissione           | errore della richiesta           | errore HTTP; nessun messaggio o evento |

Due aspetti di questa tabella meritano un'azione, non una semplice lettura.

Ricostruisci la gestione degli stati terminali attorno al record del messaggio e ai timestamp degli eventi di Bird. Le consegne dei webhook possono ripetersi o arrivare fuori ordine; il tuo consumer non deve assumere una sola consegna di un unico callback finale. Uno stato di rifiuto e uno stato di consegna fallita possono selezionare eventi Bird diversi anche quando entrambi hanno avuto origine a valle.

`message-sending` non ha una riga perché è solo MMS, e `message-read` è solo RBM; nessuno dei due si attiva per SMS.

Due meccanismi cambiano insieme ai nomi:

- **Le sottoscrizioni sostituiscono l'Application.** Bandwidth instrada i callback in base all'`applicationId` indicata nel messaggio. Bird consegna a endpoint registrati nel tuo spazio di lavoro, ciascuno sottoscritto ai tipi di evento desiderati, quindi un nuovo consumer è una nuova sottoscrizione anziché una nuova Application e un redeploy.
- **Standard Webhooks sostituisce la loro autenticazione dei callback.** Bird invia JSON firmati secondo [Standard Webhooks](https://www.standardwebhooks.com); sostituisci la verifica con la procedura in [Webhooks & events](/docs/guides/webhooks#verify-signatures).

Registra l'endpoint una sola volta, indicando i tipi di evento che il tuo handler vuole ricevere: gli eventi `sms.*` elencati sopra sono la lista a cui sottoscriverti, e non esiste un wildcard che li sostituisca. [Creare un endpoint](/docs/guides/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.

## Cutover

[Destinazioni](/docs/guides/sms/migrate#1-enable-your-destination-countries), [mittenti](/docs/guides/sms/migrate#2-set-up-a-sender) e il [ramp-up del traffico](/docs/guides/sms/migrate#6-test-against-simulated-destinations) sono indipendenti dal provider e trattati nella guida principale. Due elementi specifici di Bandwidth vanno nel piano di cutover: il tuo brand e la tua campaign 10DLC sono registrati presso The Campaign Registry tramite Bandwidth e non diventano automaticamente registrazioni Bird. Conferma la procedura di migrazione o registrazione applicabile prima di inviare lavoro a pagamento. I numeri che possiedi su Bandwidth richiedono un porting che il supporto organizza, secondo i propri tempi e non i tuoi.

Per i requisiti lato Bird, parti da [Registrarsi per il 10DLC](/docs/guides/sms/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.

## Passi successivi

- [Confronto tra Bird e Bandwidth per SMS](/products/sms/compare/bird-vs-bandwidth): valutazione del prodotto e considerazioni per la migrazione

- [Invio di SMS](/docs/guides/sms/sending-sms): il payload verso cui stai migrando, completo
- [Opt-out e keyword](/docs/guides/sms/opt-outs-and-keywords): copertura delle keyword per paese e gestione delle soppressioni
- [Eventi SMS](/docs/guides/sms/events): il vocabolario di eventi a cui si sposta il tuo handler di callback
- [Webhooks & events](/docs/guides/webhooks): configurazione dell'endpoint e verifica Standard Webhooks

## Related resources

- [Choose a sender for your markets](/explained/sms/which-sms-sender-type-should-i-use) (answer)
- [Check your message segments](/tools/sms-segment-calculator) (tool)
- [Compare SMS providers](/products/sms/compare) (product)