Migrar SMS do Bandwidth
Esta página mapeia a API Messages do Bandwidth, Applications e callbacks de mensagem para o Bird. Siga o guia principal de migração na ordem indicada e use estes mapeamentos para os passos 3, 4 e 5.
Duas diferenças definem toda a portabilidade. O Bandwidth divide o canal em dois hosts: o envio fica no host de mensagens sob o caminho da sua conta, autenticado via HTTP Basic, enquanto o registro 10DLC fica no host principal da API. O Bird reúne envio, registro e eventos de entrega sob uma única URL base e uma única chave bearer. E o applicationId em cada envio do Bandwidth carrega a configuração de callback; o Bird não tem objeto equivalente, porque callbacks são uma assinatura do espaço de trabalho e não uma propriedade da mensagem.
Passe isto para o 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 Bandwidth 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/bandwidth.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 Bandwidth 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 | Bandwidth | Bird |
|---|---|---|
| Destinatário | to (array) | to (um por solicitação) |
| Remetente | from | from |
| Corpo | text | text |
| Roteamento de callback | applicationId | um webhook do espaço de trabalho inscrito nos eventos de entrega abaixo |
| Intenção | (nenhum) | category, obrigatório em texto livre |
| Rótulo livre | tag (uma string) | metadata; tags apenas se você conseguir nomeá-lo |
| Contexto de ida e volta | seu próprio armazenamento, indexado por ID | metadata: JSON arbitrário, ecoado em cada evento |
| Prioridade de entrega | priority | sem equivalente |
| Retentativas seguras | (nenhuma na especificação deles) | header Idempotency-Key |
| Mídia | media | sem equivalente: media_urls é rejeitado |
Notas de portabilidade:
- to deixa de ser um array e passa a ser um destinatário. O Bandwidth aceita uma lista; o Bird envia uma mensagem por solicitação. Um loop substitui o array, e cada chamada pode levar seu próprio Idempotency-Key.
- O applicationId desaparece em vez de ser movido. Ele existe para dizer ao Bandwidth onde postar callbacks. No Bird isso é uma assinatura do espaço de trabalho, então nada no envio o referencia.
- tag e tags não são o mesmo campo. O tag do Bandwidth é uma string livre; os tags do Bird são pares {name, value} que se tornam dimensões de consulta. Uma string opaca é geralmente melhor transportada em metadata.
- Nada na API Messages corresponde a category. Decida por tipo de mensagem se é transactional, marketing, authentication ou service.
Transfira os opt-outs
Não existe lista para exportar, e essa é a conclusão em vez de uma lacuna neste guia.
Fora do toll-free, o Bandwidth não mantém listas de opt-in ou opt-out para você. A própria orientação deles diz claramente: a responsabilidade de cumprir os comandos e manter as listas é do cliente. Toll-free é a exceção, onde STOP e suas variantes são aplicados na camada de rede independentemente da sua configuração; long codes e short codes não recebem esse tratamento.
Portanto, nesta migração a lista oficial já é sua. Ela é uma tabela, um flag em um registro de contato ou uma verificação que o seu fluxo de envio executa antes de chamar a API, e a primeira tarefa é decidir qual desses é o oficial em vez de solicitar uma exportação de alguém. O seu próprio log de mensagens recebidas é o fallback: alguns opt-outs começaram como mensagens recebidas, enquanto outros vieram por suporte, formulários ou outro canal de preferência.
Depois importe pelo loop de supressão. Uma supressão no Bird é um par remetente-e-assinante, então um assinante que você parou em três remetentes são três registros. Leitura e gerenciamento de supressões traz o comando e a razão pela qual uma supressão manual bloqueia todas as categorias, incluindo transacional.
Decida quem é o dono da lista após a virada, porque é aqui que você ganha algo e pode perder o controle. O Bird responde a palavras-chave de parada a partir do seu próprio catálogo por país, então assim que você estiver enviando por aqui a plataforma mantém as supressões para você: um assinante que envia STOP produz um registro com razão keyword_stop sem que a sua aplicação faça nada. Se o seu código mantém sua própria lista e continua aplicando-a, as duas divergem, e o sintoma comum é um assinante que retomou de um lado e não do outro. Mantenha o dono da preferência de audiência explícito e sincronize as alterações relevantes deliberadamente. Supressões por remetente sozinhas não cobrem preferências em todo o espaço de trabalho nem solicitações fora do catálogo de palavras-chave. Razões se acumulam em vez de mesclar, então um par que você importou como manual que depois envia STOP mantém dois registros, e as mensagens permanecem paradas até que ambos tenham terminado.
Traduza os status de entrega
Use esta tabela para comparar conceitos de ciclo de vida, não para renomear eventos mecanicamente. O Bird escolhe um evento de falha a partir do status e da razão reportados. Uma solicitação API recusada não cria mensagem; uma rejeição após aceitação pode produzir sms.rejected, incluindo uma rejeição pela operadora. Evidência de entrega ausente permanece como desconhecida. Preserve o status e o código brutos do provedor junto com o seu resultado normalizado.
| Resultado | Tipo de callback do Bandwidth | Bird |
|---|---|---|
| API aceitou a mensagem | a resposta 202, sem evento | sms.accepted |
| Entregue à operadora | message-sent | sms.sent |
| Operadora confirmou a entrega | message-delivered | sms.delivered |
| Nunca chegou à operadora | message-failed | sms.rejected |
| Operadora rejeitou | message-failed | sms.failed |
| Operadora reportou não entrega | message-failed | sms.undelivered |
| Operadora desistiu | message-failed | sms.expired |
| Solicitação recusada na admissão | erro de solicitação | erro HTTP; sem mensagem ou evento |
Duas coisas nessa tabela merecem ação em vez de serem ignoradas.
Reconstrua o tratamento de estado terminal com base no registro de mensagem e nos timestamps de evento do Bird. Entregas de webhook podem se repetir ou chegar fora de ordem; o seu consumidor não deve presumir uma única entrega de um callback final. Um status de rejeição e um status de falha na entrega podem selecionar eventos Bird diferentes mesmo quando ambos se originaram a jusante.
message-sending não tem linha porque é exclusivo do MMS, e message-read é exclusivo de RBM; nenhum dos dois dispara para SMS.
Duas mecânicas mudam junto com os nomes:
- Assinaturas substituem o Application. O Bandwidth roteia callbacks pelo applicationId que a mensagem nomeou. O Bird entrega a endpoints que o seu espaço de trabalho registra, cada um inscrito nos tipos de evento que deseja, então um novo consumidor é uma nova assinatura em vez de um novo Application e um redeploy.
- Standard Webhooks substitui a autenticação de callback deles. O Bird envia JSON assinados conforme o Standard Webhooks; troque a verificação pela receita em Webhooks e eventos.
Registre o endpoint uma vez, nomeando os tipos de evento que o seu handler deseja: os eventos sms.* acima são a lista a assinar, e não há curinga que os substitua. Criar um endpoint traz o comando e o único detalhe para acertar na primeira chamada, que é armazenar o segredo de assinatura que a resposta mostra apenas uma vez.
Virada
Destinos, remetentes e a rampa de tráfego são independentes de provedor e cobertos no guia principal. Dois itens específicos do Bandwidth pertencem ao plano de virada: a sua marca e campanha 10DLC estão registradas no The Campaign Registry através do Bandwidth e não se tornam automaticamente registros no Bird. Confirme o procedimento de migração ou registro aplicável antes de submeter trabalho pago. Números que você possui no Bandwidth precisam de uma portabilidade que o suporte organiza, no cronograma dele e não no seu.
Para os requisitos do lado do 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 informa o que fornecer antes de criar a marca, que é o passo cobrado.
Próximos passos
-
Comparar Bird e Bandwidth 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 o seu handler de callback migra
-
Webhooks e eventos: 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.