Migrare SMS da Telnyx
Questa pagina mappa l'API Messages API di Telnyx, i messaging profile e i webhook di consegna su Bird. Segui la guida principale alla migrazione in ordine e usa queste corrispondenze per i passaggi 3, 4 e 5.
La chiamata di invio è la più simile a quella di Bird fra tutti i provider qui elencati: JSON, una bearer key e gli stessi nomi di campo. POST https://api.telnyx.com/v2/messages accetta from, to e text, e lo stesso vale per POST /v1/sms/messages. Quello che non si trasferisce è il messaging profile. Telnyx lo usa come unità di quasi tutto: pool di mittenti, URL del webhook, ambito dell'opt-out e configurazione delle keyword. Bird distribuisce queste funzioni fra mittenti, sottoscrizioni ai webhook e soppressioni. La maggior parte del lavoro in questa migrazione consiste nello scomporre quell'oggetto.
Passa questo al tuo agent
Usa questo brief nel tuo coding agent. Inizia con la fase di discovery e produce un piano di migrazione verificabile prima di qualsiasi modifica in produzione.
Esempio di codice
Help me migrate my SMS integration from Telnyx 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/telnyx.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 Telnyx 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 | Telnyx | Bird |
|---|---|---|
| Destinatario | to | to (uno per richiesta) |
| Mittente | from o messaging_profile_id | from |
| Corpo | text | text |
| Intent | (nessuno) | category, obbligatorio per il testo libero |
| Report di consegna | URL del webhook sul profilo | un webhook dello spazio di lavoro sottoscritto agli eventi di consegna indicati sotto |
| Contesto round-trip | un tuo archivio, indicizzato per ID | metadata: JSON arbitrario, ripetuto in ogni evento |
| Etichette filtrabili | (nessuna) | tags: coppie {name, value} |
| Invii ripetibili sicuri | (non documentato) | header Idempotency-Key |
| Media | media_urls | nessun equivalente: media_urls viene rifiutato |
Note sul porting:
- Un messaging profile ID diventa un semplice valore mittente. Telnyx risolve il pool di numeri e le relative regole di invio dietro al profilo. Bird accetta il mittente direttamente in from, quindi sceglilo per ogni invio, oppure usa un invio tramite template, che seleziona un mittente valido per la destinazione e rifiuta from.
- Nulla nell'API Messages API corrisponde a category. Decidi per ogni tipo di messaggio se si tratta di transactional, marketing, authentication o service. Il traffico di autenticazione in particolare va etichettato come tale, anziché lasciarlo in un default di marketing.
- Rivedi separatamente la semantica dei tentativi. La documentazione di invio di Telnyx non prevede una chiave di idempotenza, quindi un timeout ti lascia nel dubbio. Invia l'header Idempotency-Key fin dal primo porting.
Trasferire gli opt-out
Questo è il passaggio che sorprende, e il primo numero da calcolare è quante soppressioni diventa la tua lista.
Telnyx limita un opt-out all'intero messaging profile: un iscritto che invia STOP a un qualsiasi numero del profilo viene bloccato per tutti i numeri di quel profilo, e un invio verso di lui restituisce l'errore 40300, "Blocked due to STOP message". Per mantenere liste di opt-out separate per programmi diversi si usano profili separati.
Bird limita una soppressione alla coppia mittente-iscritto. Quindi un singolo opt-out Telnyx su un profilo con dodici numeri diventa dodici soppressioni Bird, e un profilo con cento numeri ne diventa cento. Conta prima di importare: il moltiplicatore è il numero di mittenti che stai trasferendo da quel profilo e determina se l'importazione è un ciclo di centinaia o di decine di migliaia.
Mantieni la revoca a livello di profilo su tutti i mittenti pertinenti. L'archiviazione a livello di mittente non è un'autorizzazione a riprendere un programma con un altro numero. Verifica se una preferenza a livello di spazio di lavoro è la rappresentazione corretta della richiesta effettiva della persona.
Importa tramite il ciclo di soppressione. Leggere e gestire le soppressioni contiene il comando e il motivo per cui una soppressione manuale blocca ogni categoria, incluse le transazionali.
Ricrea le keyword personalizzate e le risposte automatiche configurate tramite autoresp_configs come regole keyword Bird. Un invio verso una coppia soppressa viene rifiutato all'ammissione con E12077 SMSRecipientSuppressed; un opt-out a valle è un risultato di consegna recipient_opted_out separato. Gestisci entrambi i percorsi quando sostituisci l'errore Telnyx 40300.
Le ragioni si accumulano anziché fondersi, e questo conta una volta che il traffico è attivo: una coppia che hai importato come manual e che poi invia STOP ottiene un secondo record con ragione keyword_stop, e i messaggi restano bloccati finché ogni record per quella coppia non è terminato. Riattivare un iscritto importato in precedenza significa rimuovere entrambi i record.
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 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 prove di consegna resta sconosciuta. Conserva lo stato grezzo del provider e il codice insieme al tuo risultato normalizzato.
| Risultato | Telnyx | Bird |
|---|---|---|
| API ha accettato il messaggio | queued | sms.accepted |
| Passato al carrier | sent, su message.sent | sms.sent |
| Il carrier ha confermato la consegna | delivered, su message.finalized | sms.delivered |
| Consegna fallita | delivery_failed | sms.undelivered |
| Errore permanente | sending_failed | sms.failed |
| Richiesta rifiutata all'ammissione | errore di richiesta | errore HTTP; nessun messaggio o evento |
| Finestra di validità scaduta | (nessuno) | sms.expired |
Cambia la struttura dell'evento, non solo le parole. Telnyx invia un singolo webhook message.finalized con lo stato finale in un campo status, quindi il tuo handler si ramifica su un valore dentro un unico tipo di evento. Bird emette tipi di evento distinti, e ti sottoscrivi a quelli che vuoi, così la ramificazione esce dal tuo codice ed entra nella sottoscrizione. Per questo la colonna di sinistra sopra riporta un evento e uno stato insieme, mentre la colonna di destra riporta solo un evento.
Altre due meccaniche cambiano insieme ai nomi:
- Le sottoscrizioni sostituiscono l'URL del webhook sul profilo. Telnyx invia gli aggiornamenti di consegna all'URL del messaging profile, quindi la destinazione è una proprietà del profilo attraverso cui ogni messaggio è stato inviato. Bird consegna a endpoint che il tuo spazio di lavoro registra, ciascuno sottoscritto ai tipi di evento desiderati, quindi un secondo consumatore è una seconda sottoscrizione anziché una modifica a un oggetto condiviso.
- Standard Webhooks sostituisce lo schema di firma di Telnyx. Bird invia JSON firmati secondo Standard Webhooks; sostituisci la verifica con la procedura in Webhooks & events.
Registra l'endpoint una sola volta, indicando i tipi di evento che il tuo handler vuole ricevere: gli eventi sms.* sopra elencati sono la lista a cui sottoscriversi, e non esiste un carattere jolly che li rappresenti tutti. Creare un endpoint contiene il comando e l'unica cosa da fare correttamente alla prima chiamata, cioè salvare il signing secret che la risposta mostra una sola volta.
Bird riporta un errore con un codice error standardizzato come invalid_destination, content_rejected, provider_unavailable o recipient_opted_out; l'elenco completo si trova nella pagina degli eventi. Mappa i tuoi alert su quei codici.
Passaggio al nuovo sistema
Destinazioni, mittenti e la rampa di traffico sono indipendenti dal provider e trattati nella guida principale. Due elementi specifici di Telnyx vanno inseriti nel piano di cutover: il tuo brand e la tua campagna 10DLC sono registrati presso The Campaign Registry tramite Telnyx e non diventano automaticamente registrazioni Bird. Conferma la procedura di migrazione o registrazione applicabile prima di avviare lavoro a pagamento. I numeri di tua proprietà su Telnyx 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: spiega il significato di ogni campo, i tipi di entità riconosciuti dal registro e la chiamata ai requisiti che indica cosa fornire prima di creare il brand, che è il passaggio a pagamento.
Prossimi passi
-
Confronto tra Bird e Telnyx per SMS: valutazione del prodotto e considerazioni sulla migrazione
-
Invio di 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 a cui il tuo webhook handler passa
-
Webhooks & events: configurazione degli endpoint e verifica Standard Webhooks
Risorse correlate
Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.