# Migrare SMS da Twilio

Questa pagina mappa l'API Programmable Messaging di Twilio, i Messaging Service e le status callback 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'intero porting. L'`POST /2010-04-01/Accounts/{AccountSid}/Messages.json` di Twilio accetta parametri `PascalCase` form-encoded autenticati con Account SID e Auth Token; [`POST /v1/sms/messages`](/docs/api/reference/create-sms-message) accetta JSON autenticato con una chiave bearer API verso il tuo host regionale. Un Twilio Messaging Service può inoltre raggruppare selezione del sender, gestione degli opt-out e configurazione delle callback. Mappa ogni comportamento separatamente sull'owner Bird: rinominare il SID in un valore sender non preserva l'intero servizio.

## Passa questo al tuo agente

Usa questo brief nel tuo coding agent. Inizia con la fase di discovery e produce un piano di migrazione revisionabile prima di qualsiasi modifica in produzione.

```text
Help me migrate my SMS integration from Twilio 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 https://bird.com/docs/guides/sms/migrate/twilio.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 Twilio 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                     | Twilio                            | Bird                                                                                                     |
| ---------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Destinatario                 | `To`                              | `to` (uno per richiesta)                                                                                 |
| Mittente                     | `From` o `MessagingServiceSid`    | `from`                                                                                                   |
| Corpo                        | `Body`                            | `text`                                                                                                   |
| Template di contenuto        | `ContentSid` + `ContentVariables` | rivedi il contenuto separatamente; i template di sistema Bird non sono un'importazione di Twilio Content |
| Intent                       | (nessuno)                         | `category`, obbligatorio per il testo libero                                                             |
| Etichette filtrabili         | (nessuna)                         | coppie `tags`: `{name, value}`                                                                           |
| Contesto di andata e ritorno | un tuo store, indicizzato per SID | `metadata`: JSON arbitrario, ripetuto in ogni evento                                                     |
| Report di consegna           | `StatusCallback`                  | un webhook dello spazio di lavoro sottoscritto agli eventi di consegna seguenti                          |
| Traslitterazione             | `SmartEncoded`                    | `options.smart_encoding` (default `false`)                                                               |
| Retry sicuri                 | (nessuno su Messages)             | header `Idempotency-Key`                                                                                 |
| Pianificazione               | `ScheduleType` + `SendAt`         | nessun equivalente: `scheduled_at` viene rifiutato                                                       |
| Media                        | `MediaUrl`                        | nessun equivalente: `media_urls` viene rifiutato                                                         |
| Validità                     | `ValidityPeriod`                  | nessun equivalente: `validity_period` viene rifiutato                                                    |
| Accorciamento link           | `ShortenUrls`                     | nessun equivalente                                                                                       |

I tre campi rifiutati sono [riservati](/docs/guides/sms/sending-sms#reserved-fields) e rispondono a `422 SMSUnsupportedFeature`. Per ora mantieni la pianificazione e la gestione dei media dove sono.

Note sul porting:

- **Risolvi i comportamenti del Messaging Service separatamente.** Twilio risolve il pool di sender, lo sticky sender e il geomatch dietro il SID. Bird accetta direttamente il sender in `from`, quindi scegli il sender per ogni invio oppure usa un [invio tramite template](/docs/guides/sms/templates), che seleziona un sender valido per la destinazione e rifiuta `from`.
- **Un limite di caratteri diventa un [limite di segmenti](/docs/guides/sms/sending-sms#segments-and-encoding).** Le lunghezze sono simili per il testo GSM-7, ma il comportamento in caso di errore no: Bird non tronca mai, quindi un corpo troppo lungo viene rifiutato con un `422` anziché tagliato.
- **Nulla nell'API Messages corrisponde a `category`.** Decidi per ogni tipo di messaggio se è `transactional`, `marketing`, `authentication` o `service`. Il traffico di autenticazione in particolare va etichettato come tale, anziché lasciato in un default marketing.
- **Le credenziali di test di Twilio corrispondono a destinazioni simulate.** I numeri magici con cui già testi, inclusi `+15005550006` e `+15005550001`, producono esiti sintetizzati anche qui, con due differenze: non c'è una credenziale di test separata e gli invii vengono fatturati. Gli esiti sono elencati nella [guida principale](/docs/guides/sms/migrate#6-test-against-simulated-destinations).

## Trasferisci gli opt-out

Twilio può limitare un opt-out a un numero o a un Messaging Service. Una richiesta a livello di servizio può coprire più sender. Preserva questa ampiezza quando importi nelle soppressioni sender-e-subscriber di Bird, oppure usa la preferenza dello spazio di lavoro appropriata per una richiesta realmente a livello di spazio di lavoro.

La [documentazione Advanced Opt-Out](https://www.twilio.com/docs/messaging/tutorials/advanced-opt-out) di Twilio indica che il reporting dei numeri bloccati non è esposto tramite la Console né tramite REST API. Richiedi un'esportazione attraverso il processo di supporto disponibile e riconciliala con i tuoi record di preferenza, i log in ingresso e le richieste di supporto. Un log di sole keyword potrebbe essere incompleto.

Importa il risultato verificato attraverso il [workflow di soppressione](/docs/guides/sms/migrate#4-carry-over-your-opt-out-list). Una soppressione manuale blocca ogni categoria per quella coppia, quindi controlla l'ambito previsto anziché restringerlo o ampliarlo silenziosamente.

`21610` di Twilio segnala un destinatario che ha fatto opt-out. In Bird, una coppia soppressa viene rifiutata all'ammissione con `E12077 SMSRecipientSuppressed`, prima che il messaggio esista. L'errore di consegna `recipient_opted_out` segnala invece un opt-out a valle. Verifica la [copertura delle keyword di Bird](/docs/guides/sms/opt-outs-and-keywords) prima di dismettere un handler esistente, e preserva i meccanismi di opt-out esterni al catalogo integrato.

## 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 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 unknown. Conserva lo stato e il codice grezzi del provider insieme al tuo esito normalizzato.

| Esito                                       | Twilio `MessageStatus`  | Bird                                   |
| ------------------------------------------- | ----------------------- | -------------------------------------- |
| API ha accettato il messaggio               | `queued`, `accepted`    | `sms.accepted`                         |
| Consegnato al carrier                       | `sending`, `sent`       | `sms.sent`                             |
| Il carrier ha confermato la consegna        | `delivered`             | `sms.delivered`                        |
| Il carrier ha segnalato la mancata consegna | `undelivered`           | `sms.undelivered`                      |
| Errore permanente                           | `failed`                | `sms.failed`                           |
| Richiesta rifiutata all'ammissione          | errore di richiesta     | errore HTTP; nessun messaggio o evento |
| Finestra di validità scaduta                | (nessuno)               | `sms.expired`                          |
| Pianificato o cancellato                    | `scheduled`, `canceled` | nessun equivalente al momento          |

Tre meccaniche cambiano insieme ai nomi:

- **Gli endpoint sostituiscono gli URL di callback.** Twilio invia le notifiche allo `StatusCallback` sul messaggio o sul Messaging Service. Bird consegna a endpoint che il tuo spazio di lavoro registra, ciascuno sottoscritto ai tipi di evento desiderati, quindi un nuovo consumer è una nuova sottoscrizione, non un redeploy.
- **JSON firmato sostituisce i post form-encoded.** Twilio invia `application/x-www-form-urlencoded` con un header `X-Twilio-Signature`; Bird invia JSON firmato secondo [Standard Webhooks](https://www.standardwebhooks.com). Sostituisci la verifica con la procedura in [Webhooks ed eventi](/docs/guides/webhooks#verify-signatures).
- **I messaggi in ingresso arrivano come eventi.** Il webhook per-numero "A message comes in" di Twilio si aspetta una risposta TwiML che la tua app può usare per auto-rispondere. Bird emette `sms.received` verso lo stesso endpoint sottoscritto di tutto il resto, e non c'è un corpo di risposta che invii una replica: rispondi chiamando l'endpoint di invio, oppure lascia che le [regole keyword](/docs/guides/sms/opt-outs-and-keywords) rispondano per te.

Registra l'endpoint una sola volta, indicando i tipi di evento che il tuo handler vuole ricevere: gli eventi `sms.*` nella tabella qui sopra sono la lista a cui sottoscriversi, e non esiste un wildcard che li sostituisca. [Crea un endpoint](/docs/guides/webhooks#create-an-endpoint) contiene il comando, il motivo per cui il catalogo va enumerato, e l'unica cosa da fare bene alla prima chiamata, cioè salvare il signing secret che la risposta mostra una sola volta.

I codici di errore numerici di Twilio non hanno una corrispondenza uno a uno. Bird riporta un errore con un codice `error` standardizzato come `invalid_destination`, `content_rejected`, `provider_unavailable` o `recipient_opted_out`; la lista completa è nella [pagina degli eventi](/docs/guides/sms/events#failure-events). Mappa i tuoi alert su questi anziché sui codici della serie 30000.

## Cutover

[Destinazioni](/docs/guides/sms/migrate#1-enable-your-destination-countries), [sender](/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. Due elementi specifici di Twilio appartengono al piano di cutover: il tuo brand e la tua campaign 10DLC sono registrati presso The Campaign Registry tramite Twilio e non diventano automaticamente registrazioni Bird. Conferma la procedura di migrazione o registrazione applicabile prima di inviare lavoro a pagamento. I numeri di tua proprietà su Twilio richiedono un porting che il supporto organizza, con i suoi tempi e non con i tuoi.

Per i requisiti lato Bird, parti da [Registrarsi per 10DLC](/docs/guides/sms/10dlc): copre il significato di ogni campo, i tipi di entità riconosciuti dal registro e la chiamata ai requisiti che ti dice cosa fornire prima di creare il brand, che è il passaggio a pagamento.

## Prossimi passi

- [Confronta Bird e Twilio per SMS](/products/sms/compare/bird-vs-twilio): valutazione del prodotto e considerazioni sulla migrazione

- [Inviare SMS](/docs/guides/sms/sending-sms): il payload verso cui stai migrando, nella sua interezza
- [Opt-out e keyword](/docs/guides/sms/opt-outs-and-keywords): copertura keyword per paese e gestione delle soppressioni
- [Eventi SMS](/docs/guides/sms/events): il vocabolario degli eventi verso cui si sposta il tuo handler di stato
- [Webhooks 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)