Migrar SMS do Telnyx
Esta página mapeia a API Messages, os messaging profiles e os webhooks de entrega do Telnyx para a Bird. Siga o guia principal de migração na ordem e use estes mapeamentos para os passos 3, 4 e 5.
A chamada de envio é a mais próxima da Bird entre todos os provedores aqui: JSON, uma chave bearer e os mesmos nomes de campo. POST https://api.telnyx.com/v2/messages recebe from, to e text, assim como POST /v1/sms/messages. O que não se transfere é o messaging profile. O Telnyx faz dele a unidade de quase tudo: pool de remetentes, URL de webhook, escopo de opt-out e configuração de palavras-chave. Bird divide isso entre remetentes, assinaturas de webhook e supressões. A maior parte do trabalho nesta migração é desmontar esse objeto.
Passe isto para o seu agente
Use este resumo no seu agente de código. Ele começa com descoberta e produz um plano de migração revisável antes de qualquer alteração em produção.
Exemplo de código
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.Mapear a chamada de envio
| O que faz | Telnyx | Bird |
|---|---|---|
| Destinatário | to | to (um por solicitação) |
| Remetente | from ou messaging_profile_id | from |
| Corpo | text | text |
| Intenção | (nenhum) | category, obrigatório em texto livre |
| Relatórios de entrega | a URL de webhook do profile | um webhook do espaço de trabalho inscrito nos eventos de entrega abaixo |
| Contexto de ida e volta | seu próprio armazenamento, indexado por ID | metadata: JSON arbitrário, ecoado em cada evento |
| Rótulos filtráveis | (nenhum) | tags: pares {name, value} |
| Novas tentativas seguras | (nenhuma documentada) | header Idempotency-Key |
| Mídia | media_urls | sem equivalente: media_urls é rejeitado |
Notas de portabilidade:
- Um messaging profile ID vira um valor de remetente simples. O Telnyx resolve o pool de números e suas regras de envio por trás do profile. Bird recebe o próprio remetente em from, então escolha-o por envio ou use um envio por template, que seleciona um remetente válido para o destino e rejeita from.
- Nada na API Messages corresponde a category. Decida por tipo de mensagem se é transactional, marketing, authentication ou service. Tráfego de autenticação em particular deve ser rotulado como tal, em vez de ficar num padrão de marketing.
- Revise a semântica de novas tentativas separadamente. A referência de envio do Telnyx não documenta chave de idempotência, então um timeout lá deixa você no escuro. Envie o header Idempotency-Key desde a primeira portabilidade.
Transferir opt-outs
Este é o passo que surpreende as pessoas, e o número a calcular primeiro é em quantas supressões a sua lista se transforma.
O Telnyx limita o escopo de um opt-out ao messaging profile inteiro: um assinante que envia STOP para qualquer número do profile é bloqueado em todos os números daquele profile, e um envio para ele responde com o erro 40300, "Blocked due to STOP message". Manter listas de opt-out separadas para programas separados é feito mantendo profiles separados.
Bird limita o escopo de uma supressão ao par remetente-e-assinante. Assim, um opt-out do Telnyx contra um profile com doze números vira doze supressões Bird, e um profile com cem números vira cem. Conte antes de importar: o multiplicador é o número de remetentes que você está trazendo daquele profile, e ele decide se a importação é um loop de centenas ou de dezenas de milhares.
Preserve a revogação abrangente do profile em todos os remetentes relevantes. O armazenamento por remetente não é permissão para retomar um programa com outro número. Verifique se uma preferência abrangente ao espaço de trabalho é a representação adequada para a solicitação real da pessoa.
Importe pelo loop de supressão. Leitura e gerenciamento de supressões contém o comando e o motivo pelo qual uma supressão manual bloqueia todas as categorias, incluindo transacional.
Recrie as palavras-chave personalizadas e respostas automáticas configuradas em autoresp_configs como regras de palavras-chave Bird. Um envio para um par suprimido é recusado na admissão com E12077 SMSRecipientSuppressed; um opt-out downstream é um resultado de entrega recipient_opted_out separado. Trate ambos os caminhos ao substituir o erro 40300 do Telnyx.
Os motivos se acumulam em vez de se fundir, o que importa quando o tráfego está fluindo: um par que você importou como manual e que depois envia STOP ganha um segundo registro com motivo keyword_stop, e as mensagens continuam paradas até que todos os registros daquele par tenham terminado. Retomar um assinante que você importou uma vez significa remover ambos.
Traduzir status de entrega
Use esta tabela para comparar conceitos de ciclo de vida, não para renomear eventos mecanicamente. Bird escolhe um evento de falha com base no status e motivo reportados. Uma solicitação API recusada não cria mensagem; uma rejeição após a aceitação pode produzir sms.rejected, incluindo rejeição da operadora. Evidência de entrega ausente permanece como desconhecida. Preserve o status e o código brutos do provedor junto com o resultado normalizado.
| Resultado | Telnyx | Bird |
|---|---|---|
| API aceitou a mensagem | queued | sms.accepted |
| Entregue à operadora | sent, em message.sent | sms.sent |
| Operadora confirmou a entrega | delivered, em message.finalized | sms.delivered |
| Entrega falhou | delivery_failed | sms.undelivered |
| Falha permanente | sending_failed | sms.failed |
| Solicitação recusada na admissão | erro de solicitação | erro HTTP; sem mensagem nem evento |
| Janela de validade expirada | (nenhum) | sms.expired |
A forma do evento muda, não apenas as palavras. O Telnyx envia um único webhook message.finalized com o estado terminal em um campo status, então seu handler ramifica com base em um valor dentro de um único tipo de evento. Bird emite tipos de evento distintos, e você se inscreve nos que deseja, então a ramificação sai do seu código e vai para a assinatura. Por isso a coluna da esquerda acima nomeia um evento e um status juntos, e a coluna da direita nomeia apenas um evento.
Mais duas mecânicas mudam junto com os nomes:
- Assinaturas substituem a URL de webhook do profile. O Telnyx envia atualizações de entrega para a URL no messaging profile, então o destino é uma propriedade do profile pelo qual toda mensagem foi enviada. Bird entrega a endpoints que seu espaço de trabalho registra, cada um inscrito nos tipos de evento que deseja, então um segundo consumidor é uma segunda assinatura em vez de uma alteração em um objeto compartilhado.
- Standard Webhooks substitui o esquema de assinatura do Telnyx. Bird envia JSON assinados conforme o Standard Webhooks; troque a verificação pela receita em Webhooks & events.
Registre o endpoint uma vez, nomeando os tipos de evento que seu handler deseja: os eventos sms.* acima são a lista para se inscrever, e não existe curinga que substitua todos. Criar um endpoint tem o comando e a única coisa a acertar na primeira chamada, que é armazenar o segredo de assinatura que a resposta exibe uma única vez.
Bird reporta uma falha com um código error padronizado como invalid_destination, content_rejected, provider_unavailable ou recipient_opted_out; a lista completa está na página de eventos. Mapeie seus alertas para eles.
Virada
Destinos, remetentes e a rampa de tráfego são independentes de provedor e cobertos no guia principal. Dois itens específicos do Telnyx pertencem ao plano de virada: sua marca e campanha 10DLC estão registradas no The Campaign Registry através do Telnyx e não se tornam automaticamente registros Bird. Confirme o procedimento de migração ou registro aplicável antes de submeter trabalho pago. Números que você possui no Telnyx precisam de uma portabilidade que o suporte organiza, no cronograma dele, não no seu.
Para os requisitos do lado Bird, comece por Registrar para 10DLC: cobre o que cada campo significa, os tipos de entidade que o registro reconhece e a chamada de requisitos que informa o que fornecer antes de criar a marca, que é o passo cobrado.
Próximos passos
-
Comparar Bird e Telnyx para SMS: avaliação de produto e considerações de migração
-
Enviando SMS: o payload para o qual você está portando, completo
-
Opt-outs e palavras-chave: cobertura de palavras-chave por país e gerenciamento de supressões
-
Eventos SMS: o vocabulário de eventos para o qual seu handler de webhook migra
-
Webhooks & events: configuração de endpoint e verificação Standard Webhooks
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.