Migrar SMS do Twilio
Esta página mapeia a API Programmable Messaging do Twilio, os Messaging Services e os status callbacks para Bird. Siga o guia principal de migração na ordem e use esses mapeamentos para os passos 3, 4 e 5.
Duas diferenças definem toda a portabilidade. A POST /2010-04-01/Accounts/{AccountSid}/Messages.json do Twilio recebe parâmetros PascalCase codificados como formulário, autenticados com seu Account SID e Auth Token; a POST /v1/sms/messages recebe JSON autenticado com uma chave bearer API contra seu host regional. E um Twilio Messaging Service pode agrupar seleção de remetente, tratamento de opt-out e configuração de callback. Mapeie cada comportamento separadamente para o proprietário Bird; renomear o SID para um valor de remetente não preserva o serviço inteiro.
Passe isto para seu agente
Use este resumo no seu agente de codificação. 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 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.Mapeie a chamada de envio
| O que faz | Twilio | Bird |
|---|---|---|
| Destinatário | To | to (um por requisição) |
| Remetente | From ou MessagingServiceSid | from |
| Corpo | Body | text |
| Template de conteúdo | ContentSid + ContentVariables | revise o conteúdo separadamente; os templates de sistema Bird não são uma importação do Twilio Content |
| Intenção | (nenhum) | category, obrigatório em texto livre |
| Labels filtráveis | (nenhum) | pares tags: {name, value} |
| Contexto de ida e volta | seu próprio armazenamento, indexado por SID | metadata: JSON arbitrário, ecoado em cada evento |
| Relatórios de entrega | StatusCallback | um webhook do espaço de trabalho inscrito nos eventos de entrega abaixo |
| Transliteração | SmartEncoded | options.smart_encoding (padrão false) |
| Retentativas seguras | (nenhum no Messages) | header Idempotency-Key |
| Agendamento | ScheduleType + SendAt | sem equivalente: scheduled_at é rejeitado |
| Mídia | MediaUrl | sem equivalente: media_urls é rejeitado |
| Validade | ValidityPeriod | sem equivalente: validity_period é rejeitado |
| Encurtamento de link | ShortenUrls | sem equivalente |
Os três campos rejeitados são reservados e respondem a 422 SMSUnsupportedFeature. Mantenha o agendamento e o tratamento de mídia onde estão por enquanto.
Notas de portabilidade:
- Resolva os comportamentos do Messaging Service separadamente. O Twilio resolve o pool de remetentes, sticky sender e geomatch por trás do SID. Bird recebe o próprio remetente em from, então escolha o remetente por envio, ou use um envio por template, que seleciona um remetente válido para o destino e rejeita from.
- Um limite de caracteres se torna um limite de segmentos. Os comprimentos ficam próximos para texto GSM-7, mas a falha é diferente: Bird nunca trunca, então um corpo acima do limite é rejeitado com 422 em vez de cortado.
- 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 em um padrão de marketing.
- As credenciais de teste do Twilio mapeiam para destinos simulados. Os números mágicos com que você já testa, incluindo +15005550006 e +15005550001, produzem resultados sintetizados aqui também, com duas diferenças: não existe credencial de teste separada, e os envios são cobrados. Os resultados estão listados no guia principal.
Migre os opt-outs
O Twilio pode limitar um opt-out a um número ou a um Messaging Service. Uma solicitação abrangendo o serviço pode cobrir múltiplos remetentes. Preserve essa abrangência ao importar para as supressões de remetente-e-assinante da Bird, ou use a preferência de espaço de trabalho apropriada para uma solicitação genuinamente abrangendo todo o espaço de trabalho.
A documentação de Advanced Opt-Out do Twilio diz que o relatório de números bloqueados não é exposto pelo Console ou pela REST API. Solicite uma exportação pelo processo de suporte disponível e reconcilie com seus próprios registros de preferência, logs de entrada e solicitações de suporte. Um log de palavras-chave sozinho pode estar incompleto.
Importe o resultado revisado pelo fluxo de supressão. Uma supressão manual bloqueia todas as categorias para aquele par, então verifique o escopo pretendido em vez de silenciosamente estreitá-lo ou ampliá-lo.
O 21610 do Twilio sinaliza um destinatário com opt-out. Na Bird, um par suprimido é recusado na admissão com E12077 SMSRecipientSuppressed, antes de existir uma mensagem. O erro de entrega recipient_opted_out em vez disso relata um opt-out downstream. Verifique a cobertura de palavras-chave da Bird antes de desativar qualquer handler existente, e preserve mecanismos de opt-out fora do catálogo integrado.
Traduza os 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 a partir do status e motivo reportados. Uma requisição API recusada não cria mensagem; uma rejeição após aceitação pode produzir sms.rejected, incluindo rejeição pela operadora. Evidência de entrega ausente permanece como desconhecida. Preserve o status e o código brutos do provedor junto com seu resultado normalizado.
| Resultado | MessageStatus Twilio | Bird |
|---|---|---|
| API aceitou a mensagem | queued, accepted | sms.accepted |
| Entregue à operadora | sending, sent | sms.sent |
| Operadora confirmou a entrega | delivered | sms.delivered |
| Operadora reportou não entrega | undelivered | sms.undelivered |
| Falha permanente | failed | sms.failed |
| Requisição recusada na admissão | erro de requisição | erro HTTP; sem mensagem ou evento |
| Janela de validade expirada | (nenhum) | sms.expired |
| Agendado ou cancelado | scheduled, canceled | sem equivalente ainda |
Três mecânicas mudam junto com os nomes:
- Endpoints substituem URLs de callback. O Twilio posta na StatusCallback da mensagem ou do Messaging Service. Bird entrega para endpoints que seu espaço de trabalho registra, cada um inscrito nos tipos de evento que deseja, então um novo consumidor é uma nova inscrição em vez de um redeploy.
- JSON assinado substitui posts codificados como formulário. O Twilio envia application/x-www-form-urlencoded com um header X-Twilio-Signature; Bird envia JSON assinado conforme Standard Webhooks. Troque a verificação pela receita em Webhooks & events.
- Mensagens de entrada chegam como eventos. O webhook "A message comes in" por número do Twilio espera uma resposta TwiML que seu app pode usar para responder automaticamente. Bird emite sms.received para o mesmo endpoint inscrito de tudo o mais, e não há corpo de resposta que envie uma réplica: responda chamando o endpoint de envio, ou deixe as regras de palavras-chave responderem por você.
Registre o endpoint uma vez, nomeando os tipos de evento que seu handler deseja: os eventos sms.* na tabela acima são a lista para inscrição, e não há curinga que os substitua. Criar um endpoint tem o comando, por que o catálogo precisa ser enumerado, e a única coisa a acertar na primeira chamada, que é armazenar o segredo de assinatura que a resposta mostra uma única vez.
Os códigos de erro numéricos do Twilio não têm mapeamento um-para-um. 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 esses em vez dos códigos na faixa 30000.
Corte para produção
Destinos, remetentes e a rampa de tráfego são independentes de provedor e cobertos no guia principal. Dois itens específicos do Twilio pertencem ao plano de cutover: sua marca e campanha 10DLC estão registradas no The Campaign Registry através do Twilio 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 Twilio precisam de uma portabilidade que o suporte organiza, no cronograma dele e não no seu.
Para os requisitos do lado Bird, comece por Registrar para 10DLC: ele cobre o que cada campo significa, os tipos de entidade que o registro reconhece e a chamada de requisitos que diz o que fornecer antes de criar a marca, que é a etapa cobrada.
Próximos passos
-
Comparar Bird e Twilio para SMS: avaliação de produto e considerações de migração
-
Enviando SMS: o payload para o qual você está migrando, na íntegra
-
Opt-outs e palavras-chave: cobertura de palavras-chave por país e gerenciamento de supressão
-
Eventos SMS: o vocabulário de eventos para o qual seu handler de status 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.