# Migrar SMS de outro provedor

Use este guia para mover SMS de produção de outro provedor para Bird. Duas coisas bloqueiam o primeiro envio aqui que seu provedor atual trata de forma diferente, por isso vêm antes do código: os países para os quais você envia e o remetente de onde você envia. Depois disso, porte a chamada de envio, transfira sua lista de opt-out, redirecione relatórios de entrega para webhooks e teste contra destinos simulados antes de mover o tráfego real.

Checklist da migração:

1. [Habilite seus países de destino](#1-habilite-seus-países-de-destino)
2. [Configure um remetente](#2-configure-um-remetente)
3. [Mapeie a chamada de envio](#3-mapeie-a-chamada-de-envio) para `POST /v1/sms/messages`
4. [Transfira sua lista de opt-out](#4-transfira-sua-lista-de-opt-out)
5. [Redirecione relatórios de entrega para webhooks](#5-redirecione-relatórios-de-entrega-para-webhooks)
6. [Teste contra destinos simulados](#6-teste-contra-destinos-simulados) antes da virada

Os passos 3, 4 e 5 dependem de qual provedor você está deixando. Seu [guia do provedor](#migrando-de-um-provedor-específico) tem o mapeamento campo a campo do payload, a tradução de status e eventos, e onde obter sua lista de opt-out.

Comece pelos passos 1 e 2. O registro de remetente é o caminho crítico em uma migração de SMS: a análise da operadora e do registro pode demorar mais que a mudança de código. Avalie ambos antes de definir uma data de virada.

## 1. Habilite seus países de destino

Seu espaço de trabalho tem uma lista de destinos permitidos que nega por padrão e começa apenas com o país de origem da sua organização habilitado. Um envio para qualquer outro lugar retorna `422 SMSDestinationNotEnabled` antes que Bird resolva um remetente, então uma integração que você portou fielmente ainda falha na primeira mensagem internacional até você abrir o país.

Habilite todos os países para os quais você envia em [**SMS** > **Destinations**](https://bird.com/dashboard/w/sms/destinations). Extraia a lista dos logs de mensagens do seu provedor atual em vez de confiar na memória: um país que você esquecer é uma falha silenciosa no dia da virada, e um país que você habilitar mas nunca usar é uma exposição desnecessária. Negar por padrão também é o que limita o dano de SMS pumping, em que tráfego fraudulento para faixas premium é cobrado de você.

## 2. Configure um remetente

Em um envio de texto livre, `from` é o remetente que seu destinatário vê, e assume uma de três formas: um sender ID alfanumérico, um número de telefone em E.164 que seu espaço de trabalho possui, ou um short code. Quais formas funcionam depende do país de destino, e um remetente que não é válido lá é rejeitado com um `422` indicando o motivo. [Enviando SMS](/docs/guides/sms/sending-sms#sender) tem as regras por forma.

Como obter cada um:

- **Sender IDs alfanuméricos** você cria em [**SMS** > **Senders**](https://bird.com/dashboard/w/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**](https://bird.com/dashboard/w/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](/products/sms/numbers) 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.

Um [envio via template de sistema](/docs/guides/sms/templates) usa um formato de solicitação diferente. Ele ainda precisa do destino e da permissão do destinatário aplicáveis. Ele fornece o corpo, a categoria e o remetente, então `from` não é aceito junto com ele e Bird escolhe um remetente válido para o destino.

## 3. Mapeie a chamada de envio

O endpoint de envio único é [`POST /v1/sms/messages`](/docs/api/reference/create-sms-message). Monte um payload JSON com `to`, `from`, `text` e `category`, e uma chamada bem-sucedida retorna `202 Accepted` com um ID de mensagem prefixado por `sms_`. A entrega acontece após a resposta e chega a você por eventos de webhook e pelos endpoints de leitura. O payload completo está em [Enviando SMS](/docs/guides/sms/sending-sms); o mapeamento campo a campo do seu payload atual está no seu [guia do provedor](#migrando-de-um-provedor-específico).

Antes de portar o código, considere estas diferenças:

- **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](/docs/guides/sms/sending-sms#batch-sending) 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`](/docs/guides/sms/sending-sms#segments-and-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](/docs/guides/sms/sending-sms#reserved-fields), 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](/products/sms/marketing/campaigns) 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](/docs/guides/idempotency).

## 4. Transfira sua lista de opt-out

Importe seus opt-outs **antes** do primeiro envio de produção. Enviar mensagem para alguém que pediu ao seu provedor antigo para parar é a falha de conformidade que arruina uma migração, e nem a operadora nem o regulador se importa com qual fornecedor perdeu o registro.

Uma supressão Bird cobre um **par remetente-e-assinante**, que pode ser mais restrito que o bloqueio por serviço, perfil ou conta do seu provedor antigo. Preserve a revogação real da pessoa em todos os remetentes e programas relevantes. Adicione cada par com [`POST /v1/sms/suppressions`](/docs/api/reference/create-sms-suppression):

```bash
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
```

A mesma importação é executada a partir do CLI como `bird sms suppressions add --destination +15550001234 --originator +15557654321`.

Duas coisas para saber sobre a importação:

- **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](/docs/guides/sms/opt-outs-and-keywords#opting-out-of-every-sender) 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.

Revise o comportamento existente de palavras-chave e preferências antes de desativar o código. Bird responde a palavras-chave suportadas e registra supressões onde seu catálogo de países se aplica. Mantenha o tratamento para solicitações não suportadas, preferências mais amplas e outros canais de contato. Palavras-chave e respostas de campanha personalizadas usam [Keyword rules](https://bird.com/dashboard/w/sms/keyword-rules). Veja [Opt-outs and keywords](/docs/guides/sms/opt-outs-and-keywords) para cobertura e escopo.

## 5. Redirecione relatórios de entrega para webhooks

Registre um endpoint com [`POST /v1/webhooks`](/docs/api/reference/create-webhook) e inscreva-o em uma lista explícita de tipos de evento. Esta é a mudança estrutural que a maioria dos provedores exige: em vez de uma URL de callback por mensagem ou por número, seu espaço de trabalho tem endpoints, e cada endpoint se inscreve nos eventos que deseja.

Os nomes de evento de Bird seguem `resource.action`. O caminho feliz é `sms.accepted`, depois `sms.sent`, depois `sms.delivered`, com `sms.undelivered`, `sms.failed`, `sms.expired` e `sms.rejected` cobrindo o restante, e `sms.received` trazendo respostas aos seus números. A tradução do vocabulário de status do seu provedor atual está no seu [guia do provedor](#migrando-de-um-provedor-específico), e os payloads por evento estão em [eventos SMS](/docs/guides/sms/events).

A correlação porta sem problemas. Cada evento carrega `sms_id`, `workspace_id`, `to` e `from`, e repete `tags` e `metadata` do envio, então seu handler lê seus próprios identificadores direto do evento em vez de buscar a mensagem.

Duas mecânicas para portar com o handler:

- **Entregas são assinadas conforme [Standard Webhooks](https://www.standardwebhooks.com)**, 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](/docs/guides/webhooks#verify-signatures).
- **A entrega é at-least-once e sem ordem garantida.** Deduplique por `webhook-id` e ordene pelo `timestamp` do payload, nunca pela ordem de chegada.

Mensagens de entrada seguem o mesmo modelo. Inscreva-se em `sms.received` uma vez para o espaço de trabalho em vez de configurar uma URL de entrada por número, e lembre que Bird ainda emite `sms.received` para uma resposta que correspondeu a uma palavra-chave de parada, após registrar a supressão.

## 6. Teste contra destinos simulados

Bird sintetiza resultados de entrega para um conjunto de destinos de teste, então você pode exercitar seu caminho de envio portado e seu handler de webhook contra respostas reais de API e entregas assinadas reais sem um aparelho. Estes são os mesmos números que vários provedores usam para credenciais de teste, e uma mensagem para um deles nunca chega a uma operadora.

| Destino        | O que sua integração vê                                    |
| -------------- | ---------------------------------------------------------- |
| `+15005550001` | Rejeitado na submissão com `invalid_destination`           |
| `+15005550002` | `sms.sent`, depois `sms.undelivered` com `unreachable`     |
| `+15005550003` | `sms.sent`, depois `sms.failed` com `provider_unavailable` |
| `+15005550004` | `sms.sent`, depois `sms.failed` com `blocked_by_carrier`   |
| `+15005550006` | `sms.sent`, depois `sms.delivered`                         |
| `+15005550009` | `sms.sent`, depois `sms.failed` com `recipient_opted_out`  |

Três condições se aplicam, e as duas primeiras pegam as pessoas de surpresa em um espaço de trabalho novo:

- 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.

Um smoke test funcional envia para `+15005550006` e verifica que seu handler percorre `sms.accepted` até `sms.sent` até `sms.delivered`; envia para `+15005550002` e `+15005550009` e verifica que seu tratamento de falha e opt-out dispara no código `error` correto; e envia uma mensagem real para um aparelho que você controla para confirmar que o remetente e o corpo renderizam como esperado.

Depois, faça a virada por fatia de tráfego em vez de tudo de uma vez. Mova uma pequena porcentagem de envios de produção para Bird, monitore o [log de SMS](/docs/guides/sms/sms-log) e as [métricas](/docs/guides/sms/tracking-and-metrics) quanto a taxas de entrega e códigos de erro em comparação com o que seu provedor antigo reportava para as mesmas rotas, e aumente a fatia conforme os números se mantêm. Mantenha a integração antiga implantável até que o primeiro período de faturamento completo pareça correto.

## Migrando de um provedor específico

- [Twilio](/docs/guides/sms/migrate/twilio): `PascalCase` form-encoded para JSON, Messaging Services para remetentes, `StatusCallback` para webhooks inscritos
- [Plivo](/docs/guides/sms/migrate/plivo): `src` e `dst` para `from` e `to`, Powerpacks para remetentes, pares DND para supressões
- [Telnyx](/docs/guides/sms/migrate/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](/docs/guides/sms/migrate/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](/docs/guides/sms/migrate/sinch): batches para envios individuais, `body` para `text`, membership de grupo reconstruída como supressões
- [Infobip](/docs/guides/sms/migrate/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](/docs/guides/sms/migrate/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](/products/sms/compare): avalie o fluxo de trabalho do produto e as considerações de migração

- [Enviando SMS](/docs/guides/sms/sending-sms): o payload completo de envio, remetentes, segmentos e o modelo assíncrono 202
- [Opt-outs and keywords](/docs/guides/sms/opt-outs-and-keywords): o que Bird responde por você e como gerenciar supressões
- [Eventos SMS](/docs/guides/sms/events): o vocabulário de eventos e payloads por evento
- [Webhooks & events](/docs/guides/webhooks): configuração de endpoint, verificação de assinatura, retentativas e replay

## Related resources

- [Choose a sender for your markets](/explained/sms/which-sms-sender-type-should-i-use) (answer)
- [Check your message segments](/tools/sms-segment-calculator) (tool)