# 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](/docs/guides/sms/migrate) 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`](/docs/api/reference/create-sms-message) 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.

```text
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](/docs/guides/sms/sending-sms#reserved-fields) 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](/docs/guides/sms/sending-sms#batch-sending) 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](/docs/guides/verify/migrate).

## 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](/docs/guides/sms/migrate#4-carry-over-your-opt-out-list) 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](https://www.standardwebhooks.com). 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}`](/docs/api/reference/get-sms-message) e riconcilia gli addebiti con la fatturazione. L'[Stats API](/docs/guides/sms/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](/docs/guides/sms/migrate#1-enable-your-destination-countries), [mittenti](/docs/guides/sms/migrate#2-set-up-a-sender) e la [rampa di traffico](/docs/guides/sms/migrate#6-test-against-simulated-destinations) 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](/products/sms): workflow di prodotto e percorsi di implementazione

- [Invio SMS](/docs/guides/sms/sending-sms): il payload verso cui stai migrando, completo
- [Opt-out e keyword](/docs/guides/sms/opt-outs-and-keywords): ciò che Bird gestisce per te e come amministrare le soppressioni
- [Eventi SMS](/docs/guides/sms/events): il vocabolario degli eventi verso cui si sposta il tuo handler di stato
- [Webhook ed eventi](/docs/guides/webhooks): configurazione degli 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)