# Migrare SMS da un altro provider

Usa questa guida per spostare SMS di produzione da un altro provider a Bird. Due elementi condizionano il primo invio e il tuo provider attuale li gestisce in modo diverso, quindi precedono il codice: i paesi verso cui invii e il mittente da cui invii. Dopo averli configurati, porta la chiamata di invio, trasferisci la tua lista di opt-out, reindirizza i report di consegna ai webhook e testa su destinazioni simulate prima di spostare il traffico reale.

Checklist della migrazione:

1. [Abilita i paesi di destinazione](#1-abilita-i-paesi-di-destinazione)
2. [Configura un mittente](#2-configura-un-mittente)
3. [Mappa la chiamata di invio](#3-mappa-la-chiamata-di-invio) su `POST /v1/sms/messages`
4. [Trasferisci la tua lista di opt-out](#4-trasferisci-la-tua-lista-di-opt-out)
5. [Passa i report di consegna ai webhook](#5-passa-i-report-di-consegna-ai-webhook)
6. [Testa su destinazioni simulate](#6-testa-su-destinazioni-simulate) prima del cutover

I passaggi 3, 4 e 5 dipendono dal provider che stai abbandonando. La tua [guida al provider](#migrare-da-un-provider-specifico) contiene la mappatura campo per campo del payload, la traduzione di stati ed eventi e le istruzioni per esportare la tua lista di opt-out.

Inizia dai passaggi 1 e 2. La registrazione del mittente è l'attività più lunga in una migrazione SMS: la revisione da parte dell'operatore e del registro può durare più della modifica al codice. Valuta entrambi prima di fissare una data di cutover.

## 1. Abilita i paesi di destinazione

Il tuo spazio di lavoro ha una allowlist di destinazioni deny-by-default che parte con il solo paese di residenza della tua organizzazione abilitato. Un invio verso qualsiasi altra destinazione restituisce `422 SMSDestinationNotEnabled` prima che Bird risolva un mittente, quindi un'integrazione portata fedelmente fallisce comunque al primo messaggio internazionale finché non apri il paese.

Abilita tutti i paesi verso cui invii sotto [**SMS** > **Destinations**](https://bird.com/dashboard/w/sms/destinations). Prendi la lista dai log dei messaggi del tuo provider attuale anziché dalla memoria: un paese dimenticato è un buco silenzioso il giorno del cutover, e un paese abilitato ma mai usato è un'esposizione che non ti serve. Il deny-by-default è anche ciò che limita i danni dal SMS pumping, in cui traffico fraudolento verso range premium viene addebitato a te.

## 2. Configura un mittente

In un invio a testo libero, `from` è il mittente che il destinatario vede e può assumere tre forme: un sender ID alfanumerico, un numero di telefono in E.164 di proprietà del tuo spazio di lavoro o uno short code. Le forme disponibili dipendono dal paese di destinazione, e un mittente non valido per quel paese viene rifiutato con un `422` che indica il motivo. [Sending SMS](/docs/guides/sms/sending-sms#sender) contiene le regole per ciascuna forma.

Come si ottiene ciascuno:

- I **sender ID alfanumerici** si creano autonomamente sotto [**SMS** > **Senders**](https://bird.com/dashboard/w/sms/senders). Se il paese di destinazione richiede che il sender ID sia registrato, invia la registrazione e attendi l'approvazione prima di indirizzarvi il traffico.
- Il **traffico business negli USA tramite long code locali** richiede il brand e la campagna 10DLC applicabili, configurati sotto [**SMS** > **10DLC**](https://bird.com/dashboard/w/sms/10dlc), mentre i numeri toll-free e gli short code dedicati hanno i propri programmi di verifica o richiesta. Gli USA non accettano affatto sender ID alfanumerici, quindi un sender ID europeo che funziona ovunque altrove non ha un equivalente negli USA.
- I **numeri** si ottengono tramite il workflow Numbers, con disponibilità e provisioning gestito che dipendono dal tipo e dalla destinazione. Consulta [SMS numbers](/products/sms/numbers) per il percorso corretto; aggiungere un sender alfanumerico non comporta l'acquisizione di un numero.
- **Mantenere i numeri attuali** non è self-service: Bird non ha un flusso di port-in gestibile dalla dashboard. Se i tuoi iscritti rispondono a numeri che possiedi, apri la richiesta di portabilità con il supporto prima di programmare una data di cutover, e prevedi che la portabilità e la modifica al codice siano eventi separati.

Un [invio con template di sistema](/docs/guides/sms/templates) usa un formato di richiesta diverso. Richiede comunque la destinazione e il permesso del destinatario applicabili. Fornisce il corpo, la categoria e il mittente, quindi `from` non è accettato insieme ad esso e Bird sceglie un mittente valido per la destinazione.

## 3. Mappa la chiamata di invio

L'endpoint di invio singolo è [`POST /v1/sms/messages`](/docs/api/reference/create-sms-message). Costruisci un payload JSON con `to`, `from`, `text` e `category`, e una chiamata riuscita restituisce `202 Accepted` con un message ID con prefisso `sms_`. La consegna avviene dopo la risposta e ti raggiunge tramite eventi webhook e gli endpoint di lettura. Il payload completo si trova in [Sending SMS](/docs/guides/sms/sending-sms); la mappatura campo per campo dal tuo payload attuale è nella tua [guida al provider](#migrare-da-un-provider-specifico).

Prima di portare il codice, tieni conto di queste differenze:

- **Un destinatario per richiesta.** Bird non ha un array di destinatari. Se il tuo provider attuale smista una chiamata verso molti numeri, questa diventa una chiamata per destinatario, oppure un [batch](/docs/guides/sms/sending-sms#batch-sending) di messaggi indipendenti in una singola richiesta.
- **`category` è obbligatorio sul testo libero**, e può essere `transactional`, `marketing`, `authentication` o `service`. La maggior parte dei provider deduce l'intento dalla campagna o dal mittente; qui lo dichiari per messaggio, e se il paese di destinazione richiede che il mittente sia registrato, quella registrazione è approvata per una categoria e un invio al di fuori di essa viene rifiutato con `422 SenderCategoryNotPermitted`. Lo stato `active` del mittente non può anticiparlo, perché è riportato senza riferimento ad alcuna categoria; consulta invece i requisiti per paese. Impostalo correttamente durante il porting anziché assegnare tutto a un unico valore.
- **Il corpo è limitato in segmenti e Bird non tronca.** Un corpo più lungo viene rifiutato con un `422`. I caratteri non GSM-7 riducono di più della metà ciò che entra in un segmento, quindi se il tuo provider attuale traslitterava silenziosamente virgolette curve e trattini, imposta [`options.smart_encoding`](/docs/guides/sms/sending-sms#segments-and-encoding) per mantenere i conteggi di segmenti a cui sei abituato. È disattivata per impostazione predefinita perché altera il corpo che hai composto.
- **Usa `tags` per le dimensioni di filtro e `metadata` per il contesto.** I tag sono coppie `{name, value}` su cui puoi filtrare e segmentare le analytics; i metadata sono JSON arbitrari che Bird salva, restituisce nelle letture e ripete in ogni evento webhook. Un singolo campo di riferimento client nel tuo vecchio provider in genere corrisponde a `metadata`.
- **La schedulazione per singolo invio e MMS in uscita richiedono un piano separato.** `scheduled_at`, `media_urls`, `validity_period` e `personalization` per destinatario sono [campi riservati](/docs/guides/sms/sending-sms#reserved-fields), rifiutati con `422 SMSUnsupportedFeature`. Queste parti della tua integrazione non migrano con il resto: mantieni gli invii schedulati nella tua coda e chiama l'endpoint di invio al momento previsto di sottomissione. Per le campagne audience, valuta [Broadcasts](/products/sms/marketing/campaigns) separatamente; un broadcast non è una rinomina di campo dell'endpoint.
- **Usa `Idempotency-Key` per retry limitati.** Invia una chiave univoca per messaggio logico e riutilizzala per i retry della stessa richiesta entro la finestra di replay di tre ore. I replay riducono le richieste duplicate ma non sono una garanzia di consegna exactly-once. Vedi [Idempotency](/docs/guides/idempotency).

## 4. Trasferisci la tua lista di opt-out

Importa gli opt-out **prima** del primo invio di produzione. Inviare un messaggio a chi ha chiesto al tuo vecchio provider di fermarsi è il problema di conformità che fa fallire una migrazione, e né l'operatore né l'autorità di regolamentazione si interessa di quale vendor abbia perso il record.

Una soppressione Bird copre una **coppia mittente-iscritto**, che può essere più restrittiva del blocco a livello di servizio, profilo o account del tuo vecchio provider. Preserva il ritiro effettivo della persona su ogni mittente e programma rilevante. Aggiungi ogni coppia con [`POST /v1/sms/suppressions`](/docs/api/reference/create-sms-suppression):

```bash
while IFS=, read -r destination originator; do
  curl -s -X POST https://us1.platform.bird.com/v1/sms/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"destination\": \"$destination\", \"originator\": \"$originator\"}"
done < opt-outs.csv
```

La stessa importazione si esegue dalla CLI come `bird sms suppressions add --destination +15550001234 --originator +15557654321`.

Due cose da sapere sull'importazione:

- **Entrambi gli estremi sono obbligatori per le soppressioni specifiche per mittente.** Un opt-out a livello di spazio di lavoro appartiene al [preference owner](/docs/guides/sms/opt-outs-and-keywords#opting-out-of-every-sender) separato. La chiamata è idempotente: `201` registra una nuova soppressione, `200` restituisce quella manuale già presente, quindi rieseguire un'importazione parziale è sicuro.
- **Le coppie importate ottengono `reason: manual`, che blocca ogni categoria incluse quelle transazionali.** Questo è più restrittivo di una soppressione che Bird registra autonomamente da una keyword di stop. Se un iscritto ha rinunciato solo al marketing, decidi deliberatamente se importare quella coppia.

Rivedi il comportamento esistente di keyword e preferenze prima di dismettere il codice. Bird risponde alle keyword supportate e registra le soppressioni dove si applica il suo catalogo per paese. Mantieni la gestione delle richieste non supportate, delle preferenze più ampie e degli altri canali di contatto. Le keyword e le risposte personalizzate per campagna usano [Keyword rules](https://bird.com/dashboard/w/sms/keyword-rules). Vedi [Opt-outs and keywords](/docs/guides/sms/opt-outs-and-keywords) per copertura e ambito.

## 5. Passa i report di consegna ai webhook

Registra un endpoint con [`POST /v1/webhooks`](/docs/api/reference/create-webhook) e sottoscrivilo a una lista esplicita di tipi di evento. Questo è il cambiamento strutturale che la maggior parte dei provider richiede: invece di un URL di callback per messaggio o per numero, il tuo spazio di lavoro ha degli endpoint e ciascun endpoint sottoscrive gli eventi che gli interessano.

I nomi degli eventi di Bird seguono `resource.action`. Il percorso ideale è `sms.accepted`, poi `sms.sent`, poi `sms.delivered`, con `sms.undelivered`, `sms.failed`, `sms.expired` e `sms.rejected` che coprono il resto, e `sms.received` che trasporta le risposte ai tuoi numeri. La traduzione dal vocabolario di stato del tuo provider attuale è nella tua [guida al provider](#migrare-da-un-provider-specifico), e i payload per evento sono in [eventi SMS](/docs/guides/sms/events).

La correlazione si porta senza problemi. Ogni evento contiene `sms_id`, `workspace_id`, `to` e `from`, e ripete `tags` e `metadata` dall'invio, quindi il tuo handler legge i tuoi identificatori direttamente dall'evento senza dover cercare il messaggio.

Due meccaniche da portare con l'handler:

- **Le consegne sono firmate secondo [Standard Webhooks](https://www.standardwebhooks.com)**, usando gli header `webhook-id`, `webhook-timestamp` e `webhook-signature` con un HMAC-SHA256 su `{id}.{timestamp}.{raw body}`. I provider che firmano con uno schema proprio richiedono la sostituzione della verifica; la procedura è in [Webhooks & events](/docs/guides/webhooks#verify-signatures).
- **La consegna è at-least-once e non ordinata.** Deduplica su `webhook-id` e ordina per il `timestamp` del payload, mai per ordine di arrivo.

I messaggi in ingresso seguono lo stesso modello. Sottoscrivi `sms.received` una volta per lo spazio di lavoro anziché configurare un URL in ingresso per numero, e ricorda che Bird emette comunque `sms.received` per una risposta che corrisponde a una keyword di stop, dopo aver registrato la soppressione.

## 6. Testa su destinazioni simulate

Bird sintetizza esiti di consegna per un insieme di destinazioni di test, così puoi esercitare il percorso di invio portato e il tuo handler webhook con risposte API reali e consegne firmate reali senza un dispositivo. Sono gli stessi numeri che diversi provider usano per le credenziali di test, e un messaggio verso uno di essi non raggiunge mai un operatore.

| Destinazione   | Cosa vede la tua integrazione                           |
| -------------- | ------------------------------------------------------- |
| `+15005550001` | Rifiutato alla sottomissione con `invalid_destination`  |
| `+15005550002` | `sms.sent`, poi `sms.undelivered` con `unreachable`     |
| `+15005550003` | `sms.sent`, poi `sms.failed` con `provider_unavailable` |
| `+15005550004` | `sms.sent`, poi `sms.failed` con `blocked_by_carrier`   |
| `+15005550006` | `sms.sent`, poi `sms.delivered`                         |
| `+15005550009` | `sms.sent`, poi `sms.failed` con `recipient_opted_out`  |

Si applicano tre condizioni, e le prime due colgono di sorpresa su uno spazio di lavoro nuovo:

- Sono numeri USA, quindi gli **Stati Uniti devono essere abilitati** sotto Destinations, e `from` deve essere un mittente valido per gli USA. Un sender ID alfanumerico viene rifiutato.
- **Un invio simulato viene fatturato** alla tariffa normale della destinazione. Nulla raggiunge un dispositivo, ma l'addebito sul wallet è reale, quindi dimensiona lo smoke test di conseguenza.
- L'esito dipende unicamente dalla destinazione. Non esiste una credenziale di test separata, né una modalità di test da disattivare.

Uno smoke test efficace invia a `+15005550006` e verifica che il tuo handler percorra `sms.accepted` fino a `sms.sent` e poi `sms.delivered`; invia a `+15005550002` e `+15005550009` e verifica che la gestione degli errori e degli opt-out si attivi sul codice `error` corretto; e invia un messaggio reale a un dispositivo che controlli per confermare che il mittente e il corpo siano visualizzati come previsto.

Poi effettua il cutover per quota di traffico anziché tutto in una volta. Sposta una piccola percentuale degli invii di produzione su Bird, monitora il [log SMS](/docs/guides/sms/sms-log) e le [metriche](/docs/guides/sms/tracking-and-metrics) per tassi di consegna e codici di errore rispetto a quanto il tuo vecchio provider riportava per le stesse rotte, e aumenta la quota man mano che i numeri reggono. Mantieni la vecchia integrazione deployabile fino a quando il primo periodo di fatturazione completo non risulta corretto.

## Migrare da un provider specifico

- [Twilio](/docs/guides/sms/migrate/twilio): `PascalCase` form-encoded a JSON, Messaging Services a sender, `StatusCallback` a webhook sottoscritti
- [Plivo](/docs/guides/sms/migrate/plivo): `src` e `dst` a `from` e `to`, Powerpacks a sender, coppie DND a soppressioni
- [Telnyx](/docs/guides/sms/migrate/telnyx): l'invio più simile a quello di Bird, messaging profile scomposti in sender e sottoscrizioni, opt-out a livello di profilo a coppie
- [Bandwidth](/docs/guides/sms/migrate/bandwidth): due host in uno, callback `applicationId` a webhook dello spazio di lavoro, e una lista di opt-out che la tua applicazione già possiede
- [Sinch](/docs/guides/sms/migrate/sinch): batch a invii singoli, `body` a `text`, appartenenze a gruppi ricostruite come soppressioni
- [Infobip](/docs/guides/sms/migrate/infobip): un payload a tre livelli appiattito, un base URL per account a un host regionale, una Blocklist espansa a coppie
- [Bird Connectivity Platform](/docs/guides/sms/migrate/connectivity-platform): `rest.messagebird.com` API, `originator` e `recipients` a `from` e `to`, callback GET `reportUrl` a webhook firmati

## Passaggi successivi

- [Confrontare i provider SMS](/products/sms/compare): valutare il workflow di prodotto e le considerazioni sulla migrazione

- [Sending SMS](/docs/guides/sms/sending-sms): il payload di invio completo, i sender, i segmenti e il modello asincrono 202
- [Opt-outs and keywords](/docs/guides/sms/opt-outs-and-keywords): cosa risponde Bird per te e come gestire le soppressioni
- [Eventi SMS](/docs/guides/sms/events): il vocabolario degli eventi e i payload per evento
- [Webhooks & events](/docs/guides/webhooks): configurazione degli endpoint, verifica della firma, retry e replay

## 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](/sms-api/compare) (product)