Migrar SMS de outro provedor

1. Habilite seus países de destino
2. Configure um remetente
3. Mapeie a chamada de envio para POST /v1/sms/messages
4. Transfira sua lista de opt-out
5. Redirecione relatórios de entrega para webhooks
6. Teste contra destinos simulados antes da virada

1. Habilite seus países de destino

2. Configure um remetente

• Sender IDs alfanuméricos você cria em SMS > Senders. Quando o país de destino exige que o sender ID seja registrado, envie o registro lá e aguarde a aprovação antes de direcionar tráfego para ele.
• Tráfego comercial nos EUA via long codes locais precisa da marca e campanha 10DLC aplicável, configuradas em SMS > 10DLC, enquanto números toll-free e short codes dedicados têm seus próprios programas de verificação ou aplicação. Os EUA não aceitam sender IDs alfanuméricos, então um sender ID europeu que funciona em todo lugar não tem equivalente nos EUA.
• Números são obtidos pelo fluxo de Numbers, com disponibilidade e provisionamento gerenciado dependentes do tipo e destino. Consulte números SMS para o caminho correto; adicionar um sender alfanumérico não adquire um número.
• Manter seus números atuais não é autoatendimento: Bird não tem um fluxo de portabilidade que você possa conduzir pelo dashboard. Se seus assinantes respondem a números que você possui, solicite a portabilidade ao suporte antes de agendar uma data de virada, e planeje para que a portabilidade e a mudança de código sejam eventos separados.

3. Mapeie a chamada de envio

• Um destinatário por solicitação. Bird não tem array de destinatários. Se seu provedor atual distribui uma chamada para vários números, isso se torna uma chamada por destinatário, ou um batch de mensagens independentes em uma única solicitação.
• category é obrigatório em texto livre, e pode ser transactional, marketing, authentication ou service. A maioria dos provedores infere a intenção a partir da campanha ou do remetente; aqui você declara por mensagem, e quando o país de destino exige que o remetente seja registrado, esse registro é aprovado para uma categoria e um envio fora dela é rejeitado com 422 SenderCategoryNotPermitted. O status active do remetente não consegue informar isso antecipadamente, porque é reportado sem referência a nenhuma categoria; consulte os requisitos por país. Acerte na portabilidade em vez de padronizar tudo com um único valor.
• O corpo é limitado em segmentos, e Bird não trunca. Um corpo mais longo é rejeitado com 422. Caracteres não GSM-7 reduzem pela metade o que cabe em um segmento, então se seu provedor atual transliterava silenciosamente aspas curvas e travessões, ative options.smart_encoding para manter as contagens de segmentos com as quais você está acostumado. Está desativado por padrão porque altera o corpo que você compôs.
• Use tags para dimensões de filtro e metadata para contexto. Tags são pares {name, value} pelos quais você pode filtrar e segmentar analytics; metadata é JSON arbitrário que Bird armazena, retorna em leituras e repete em cada evento de webhook. Um campo de referência de cliente único no seu provedor antigo geralmente mapeia para metadata.
• Agendamento de envio individual e MMS de saída precisam de um plano separado. scheduled_at, media_urls, validity_period e personalization por destinatário são campos reservados, rejeitados com 422 SMSUnsupportedFeature. Essas partes da sua integração não migram junto com o resto: mantenha envios agendados na sua própria fila e chame o endpoint de envio no horário de submissão desejado. Para campanhas de audiência, avalie Broadcasts separadamente; um broadcast não é uma renomeação de campo de endpoint.
• Use Idempotency-Key para retentativas limitadas. Envie uma chave única por mensagem lógica e reutilize-a para retentativas da mesma solicitação dentro da janela de replay de três horas. Replays reduzem solicitações duplicadas, mas não são uma garantia de entrega exatamente uma vez. Veja Idempotency.

4. Transfira sua lista de opt-out

while IFS=, read -r destination originator; do
  curl -s -X POST https://us1.platform.bird.com/v1/sms/suppressions \
    -H "Authorization: Bearer $BIRD_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{\"destination\": \"$destination\", \"originator\": \"$originator\"}"
done < opt-outs.csv

• Ambas as pontas são obrigatórias para supressões específicas de remetente. Um opt-out para todo o espaço de trabalho pertence ao preference owner separado. A chamada é idempotente: 201 registra uma nova supressão, 200 retorna a manual já existente, então reexecutar uma importação parcial é seguro.
• Pares importados recebem reason: manual, que bloqueia todas as categorias incluindo transacional. Isso é mais restritivo que uma supressão que Bird registra a partir de uma palavra-chave de parada. Se um assinante cancelou apenas marketing, decida deliberadamente se deve importar esse par.

5. Redirecione relatórios de entrega para webhooks

• Entregas são assinadas conforme Standard Webhooks, usando os headers webhook-id, webhook-timestamp e webhook-signature com um HMAC-SHA256 sobre {id}.{timestamp}.{raw body}. Provedores que assinam com esquema próprio precisam trocar a verificação; a receita está em Webhooks & events.
• A entrega é at-least-once e sem ordem garantida. Deduplique por webhook-id e ordene pelo timestamp do payload, nunca pela ordem de chegada.

6. Teste contra destinos simulados

• Estes são números dos EUA, então os Estados Unidos devem estar habilitados em Destinations, e from deve ser um remetente válido para os EUA. Um sender ID alfanumérico é rejeitado lá.
• Um envio simulado é cobrado na tarifa normal do destino. Nada chega a um aparelho, mas a cobrança na carteira é real, então dimensione seu smoke test de acordo.
• O resultado vem apenas do destino. Não há credencial de teste separada nem modo de teste para desativar.

Migrando de um provedor específico

• Twilio: PascalCase form-encoded para JSON, Messaging Services para remetentes, StatusCallback para webhooks inscritos
• Plivo: src e dst para from e to, Powerpacks para remetentes, pares DND para supressões
• Telnyx: o envio mais próximo do de Bird, messaging profiles desmembrados em remetentes e inscrições, opt-outs no nível de perfil para pares
• Bandwidth: dois hosts para um, callbacks applicationId para webhooks do espaço de trabalho, e uma lista de opt-out que sua própria aplicação já mantém
• Sinch: batches para envios individuais, body para text, membership de grupo reconstruída como supressões
• Infobip: um payload de três níveis achatado, uma URL base por conta para um host regional, uma Blocklist expandida para pares
• Bird Connectivity Platform: o rest.messagebird.com API, originator e recipients para from e to, callbacks GET reportUrl para webhooks assinados

Próximos passos

• Comparar provedores de SMS: avalie o fluxo de trabalho do produto e as considerações de migração
• Enviando SMS: o payload completo de envio, remetentes, segmentos e o modelo assíncrono 202
• Opt-outs and keywords: o que Bird responde por você e como gerenciar supressões
• Eventos SMS: o vocabulário de eventos e payloads por evento
• Webhooks & events: configuração de endpoint, verificação de assinatura, retentativas e replay