# Migrar SMS da Bird Connectivity Platform

Esta página mapeia a API da Connectivity Platform Bird em `rest.messagebird.com`, aquela que você talvez ainda conheça como MessageBird API, para Bird. Siga o [guia principal de migração](/docs/guides/sms/migrate) na ordem e use esses mapeamentos nos passos 3, 4 e 5.

Ambas as plataformas são da Bird, e a API é a parte que muda. Três diferenças afetam todas as chamadas. As requisições vão para o seu host regional, `https://us1.platform.bird.com` ou `https://eu1.platform.bird.com`, em vez de um host global único. A autenticação usa uma chave bearer API (`Authorization: Bearer bk_us1_…`) em vez de `Authorization: AccessKey`. E o envio é assíncrono: [`POST /v1/sms/messages`](/docs/api/reference/create-sms-message) retorna `202 Accepted` com a mensagem enfileirada, enquanto a Connectivity Platform retornava o objeto da mensagem já com o status por destinatário anexado.

## Passe isso 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.

```text
Help me migrate my SMS integration from Bird Connectivity Platform 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/connectivity-platform.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 Connectivity Platform 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             | Connectivity Platform | Bird                                                                    |
| --------------------- | --------------------- | ----------------------------------------------------------------------- |
| Destinatário          | `recipients` (até 50) | `to`, um por requisição                                                 |
| Remetente             | `originator`          | `from`                                                                  |
| Corpo                 | `body`                | `text`                                                                  |
| Intenção              | (nenhum)              | `category`, obrigatório em texto livre                                  |
| Codificação           | `datacoding`          | detectada automaticamente                                               |
| Transliteração        | (nenhum)              | `options.smart_encoding` (padrão `false`)                               |
| Referência do cliente | `reference`           | `metadata`, ou `tags` quando você filtra por ele                        |
| Relatórios de status  | `reportUrl`           | um webhook do espaço de trabalho inscrito nos eventos de entrega abaixo |
| Retentativas seguras  | (nenhum)              | header `Idempotency-Key`                                                |
| Agendamento           | `scheduledDatetime`   | sem equivalente: `scheduled_at` é rejeitado                             |
| Validade              | `validity`            | sem equivalente: `validity_period` é rejeitado                          |
| Seleção de rota       | `gateway`             | Bird seleciona a rota                                                   |
| Classe da mensagem    | `mclass`              | sem equivalente                                                         |
| Binário e flash       | `type`, `typeDetails` | somente texto                                                           |

Ambos os campos rejeitados são [reservados](/docs/guides/sms/sending-sms#reserved-fields) e respondem a `422 SMSUnsupportedFeature`.

Notas de portabilidade:

- **O array de destinatários se torna uma chamada por destinatário.** Uma chamada da Connectivity Platform com 50 destinatários se torna 50 envios, ou um [lote](/docs/guides/sms/sending-sms#batch-sending) de mensagens independentes. O lote não é um fan-out de um único corpo: cada entrada carrega seu próprio destinatário, remetente e texto.
- **`datacoding` não tem equivalente, e isso é intencional.** Bird detecta a codificação a partir do corpo e reporta a contagem de segmentos na mensagem. Se você configurar `datacoding: auto` para manter as mensagens dentro de GSM-7, o comportamento mais próximo é `options.smart_encoding`, que aplica a tabela de substituição documentada de Bird. Não é um transliterador genérico; caracteres não suportados ainda podem exigir codificação Unicode.
- **`reference` se divide em dois campos.** Coloque um identificador interno em `metadata`, que é ecoado em cada evento de webhook, e use `tags` para os rótulos de baixa cardinalidade pelos quais você quer filtrar e segmentar analytics.
- **Mensagens flash, payloads binários e concatenação UDH não são portados.** Se você depende de `mclass` ou `typeDetails` hoje, levante isso com o suporte antes de planejar a virada, não depois.
- **Também usa o Verify API da Connectivity Platform?** A portabilidade é um trabalho separado com seu próprio guia: veja [Migrar Verify de outro provedor](/docs/guides/verify/migrate).

## Transfira os opt-outs

A Connectivity Platform deixava o tratamento de palavras-chave de parada com você, seja via Flows ou na sua própria aplicação processando mensagens de entrada. Bird faz esse trabalho por conta própria: reconhece palavras-chave de stop, start e help nos seus números em países suportados, registra a supressão e a aplica em cada envio. Desative um handler antigo somente depois de confirmar que o catálogo de Bird cobre o comportamento dele e que seu processo de preferências mais amplo ainda funciona.

O que não se desativa é a lista. Exporte o que você mantém hoje, como pares de número do assinante e o originador em que ele deu stop, e importe pelo [loop de supressão](/docs/guides/sms/migrate#4-carry-over-your-opt-out-list) antes do seu primeiro envio em produção. Se você sempre manteve apenas uma lista global de assinantes que fizeram opt-out, importe cada assinante uma vez por originador de onde você ainda envia.

## Traduza os relatórios de status

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 a aceitação pode produzir `sms.rejected`, incluindo uma rejeição pela operadora. Evidência de entrega ausente permanece como desconhecida. Preserve o status bruto do provedor e o código junto com o resultado normalizado.

| Resultado                       | Connectivity Platform | Bird                              |
| ------------------------------- | --------------------- | --------------------------------- |
| Aceito pela API                 | (síncrono)            | `sms.accepted`                    |
| Entregue à operadora            | `sent`, `buffered`    | `sms.sent`                        |
| Operadora confirmou entrega     | `delivered`           | `sms.delivered`                   |
| Entrega falhou                  | `delivery_failed`     | `sms.failed`                      |
| Janela de validade expirou      | `expired`             | `sms.expired`                     |
| Requisição recusada na admissão | erro de requisição    | erro HTTP; sem mensagem ou evento |
| Aguardando envio                | `scheduled`           | sem equivalente ainda             |

O mecanismo de entrega muda mais do que o vocabulário:

- **Posts JSON assinados substituem callbacks GET de `reportUrl`.** Os relatórios de status chegavam como requisições `GET` com o resultado na query string (`status`, `statusReason`, `statusErrorCode`, `mccmnc`, `price[amount]`). Bird `POST` um evento JSON para endpoints que seu espaço de trabalho registra, assinados conforme [Standard Webhooks](https://www.standardwebhooks.com). O handler é uma reescrita, não uma troca de URL.
- **A correlação não depende mais de `reference`.** Um relatório de status só era útil se você tivesse definido uma referência; um evento Bird sempre carrega `sms_id`, ambos os números e seus `metadata` e `tags` ecoados.
- **A semântica de retentativa é diferente.** A Connectivity Platform retentava um relatório com falha até 10 vezes. As entregas de Bird são at-least-once e sem ordem, então desduplique pelo header `webhook-id` e ordene pelo `timestamp` do payload.
- **Reconcilie custos pelo proprietário da mensagem e do billing.** O relatório da Connectivity Platform trazia `price[amount]` e `price[currency]`. Leia o custo registrado da mensagem com [`GET /v1/sms/messages/{id}`](/docs/api/reference/get-sms-message) e reconcilie cobranças com o billing. A [Stats API](/docs/guides/sms/stats-api) serve para métricas de entrega, não como um total de faturamento autoritativo.

Mensagens de entrada funcionam da mesma forma: inscreva-se em `sms.received` uma vez para o espaço de trabalho em vez de apontar cada número para uma URL.

## Virada

[Destinos](/docs/guides/sms/migrate#1-enable-your-destination-countries), [remetentes](/docs/guides/sms/migrate#2-set-up-a-sender) e a [rampa de tráfego](/docs/guides/sms/migrate#6-test-against-simulated-destinations) são independentes de provedor e estão cobertos no guia principal. O item a levantar cedo são seus originadores: sender IDs alfanuméricos são recriados e, quando o país exige, re-registrados aqui, e números que você mantém na Connectivity Platform são transferidos por uma portabilidade que o suporte organiza, não por uma configuração que você alterna.

## Próximos passos

- [Explore Bird SMS](/products/sms): fluxos de produto e caminhos de implementação

- [Enviando SMS](/docs/guides/sms/sending-sms): o payload para o qual você está migrando, na íntegra
- [Opt-outs e palavras-chave](/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 para o qual seu handler de status migra
- [Webhooks & eventos](/docs/guides/webhooks): configuração de endpoint e verificação Standard Webhooks

## 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)
- [Compare SMS providers](/products/sms/compare) (product)