Sign inGet Started

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.

Fra tutti i provider qui elencati, la chiamata di invio di Telnyx è la più simile a quella di Bird: 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. Il messaging profile invece cambia forma. Telnyx lo usa come unità di quasi tutto: pool di mittenti, URL del webhook, ambito dell'opt-out e configurazione delle keyword. Un messaging profile di Bird contiene la parte di invio: il mittente per ogni paese di destinazione più un mittente predefinito, i numeri che ricevono le risposte, le impostazioni predefinite di invio e un URL di callback. Opt-out e keyword restano fuori dal profilo, come soppressioni e regole keyword. La maggior parte del lavoro in questa migrazione consiste nel decidere dove finisce ciascuna parte di un profilo Telnyx.

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 platform support 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

FunzioneTelnyxBird
Destinatariototo (uno per richiesta)
Mittentefrom o messaging_profile_idfrom, oppure messaging_profile_id che indica un messaging profile di Bird
Corpotexttext
Intent(nessuno)category, obbligatorio per il testo libero, a meno che il profilo non imposti un valore predefinito
Report di consegnaURL del webhook sul profiloil options.callback_url del profilo, oppure un webhook dello spazio di lavoro sottoscritto agli eventi di consegna indicati sotto
Contesto round-tripun tuo archivio, indicizzato per IDmetadata: JSON arbitrario, ripetuto in ogni evento
Etichette filtrabili(nessuna)tags: coppie {name, value}
Nuovi tentativi sicuri(non documentato)header Idempotency-Key
Mediamedia_urlsmedia_urls; un oggetto o un media seleziona MMS

MMS richiede testo o media, un destinatario +1 e un numero abilitato a MMS di proprietà del tuo spazio di lavoro. Usa una sola unità di messaggio, con tariffe MMS separate. Invio di SMS spiega il requisito dell'URL pubblico per i media e i limiti di dimensione dei carrier.

Note sul porting:

  • Un messaging profile ID corrisponde a un ID di messaging profile Bird. Crea un messaging profile con il mittente per ogni paese di destinazione, oppure un mittente predefinito, e indicalo in messaging_profile_id. Se ometti from, Bird invia dal mittente del profilo per il paese di destinazione. Un profilo Bird contiene un mittente per paese di destinazione, quindi un pool di numeri Telnyx diventa un solo mittente scelto per ogni paese. Un from indicato nell'invio ha la precedenza, e un invio tramite template seleziona comunque un mittente valido per la destinazione e rifiuta from.
  • Nella Messages API non c'è nulla che corrisponda 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 nuovi tentativi. La documentazione di invio di Telnyx non prevede una chiave di idempotenza, quindi dopo un timeout non sai se riprovare sia sicuro. 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. Per riattivare un iscritto importato in precedenza devi 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.

RisultatoTelnyxBird
API ha accettato il messaggioqueuedsms.accepted
Passato al carriersent, su message.sentsms.sent
Il carrier ha confermato la consegnadelivered, su message.finalizedsms.delivered
Consegna fallitadelivery_failedsms.undelivered
Errore permanentesending_failedsms.failed
Richiesta rifiutata all'ammissioneerrore di richiestaerrore HTTP; nessun messaggio o evento
Finestra di validità scaduta(nessuno)sms.expired quando il carrier segnala la scadenza; sms.rejected o sms.failed quando validity_period scade prima della consegna al carrier

Cambiano sia i nomi degli eventi sia la loro struttura. 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 invece 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:

  • Un callback URL del profilo o 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. Il options.callback_url di un profilo Bird mantiene questa struttura: gli eventi dei messaggi inviati con il profilo arrivano a quell'URL al posto dei tuoi endpoint webhook, e le risposte arrivano al suo inbound.callback_url quando è impostato. Se il profilo imposta callback_events, un evento in uscita che non vi è incluso non raggiunge né l'URL né i tuoi endpoint, quindi elenca gli eventi di consegna di cui il tuo handler ha bisogno. Callback URL di SMS spiega instradamento, nuovi tentativi e replay. Senza un callback URL, Bird consegna agli 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. Un callback URL usa lo stesso schema con il signing secret di callback del tuo spazio di lavoro, che devi ruotare prima di poter verificare.

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 passaggio: 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

Continua con la documentazione, le guide e gli esempi per questo argomento.