# Migrar SMS do Sinch

Esta página mapeia SMS API, grupos e relatórios de entrega do Sinch para Bird. Siga o [guia principal de migração](/docs/guides/sms/migrate) na ordem indicada e use estes mapeamentos para os passos 3, 4 e 5.

Duas diferenças estruturais definem a portabilidade, e ambas custam mais do que as renomeações de campos. O Sinch indexa o envio por um service plan no path da URL e envia um **batch**, então uma mensagem para uma pessoa ainda é um array; o [`POST /v1/sms/messages`](/docs/api/reference/create-sms-message) do Bird aceita um destinatário no seu host regional com uma bearer key e sem segmento de plano. E o registro nos EUA que você não pode pular está em um host diferente do envio, atrás de uma família de credenciais diferente, então um código que acessa o Sinch para ambos está acessando dois lugares.

## Entregue isto ao 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 Sinch 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/sinch.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 Sinch 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            | Sinch                                         | Bird                                                     |
| -------------------- | --------------------------------------------- | -------------------------------------------------------- |
| Destinatário         | `to` (array ou um group ID)                   | `to` (um por solicitação)                                |
| Remetente            | `from`                                        | `from`                                                   |
| Corpo                | `body`                                        | `text`                                                   |
| Roteamento de conta  | service plan, no path da URL                  | a bearer key; sem segmento de path                       |
| Intenção             | (nenhum)                                      | `category`, obrigatório em texto livre                   |
| Relatório de entrega | `delivery_report` + `callback_url`, por batch | um webhook do espaço de trabalho; sem controle por envio |
| Correlação           | `client_reference`                            | `metadata`, ecoado em cada evento                        |
| Labels filtráveis    | (nenhum)                                      | pares `tags`: `{name, value}`                            |
| Retentativas seguras | (não documentado)                             | header `Idempotency-Key`                                 |
| Flash                | `flash_message`                               | sem equivalente                                          |

Notas de portabilidade:

- **Escolha entre envio individual, batch ou broadcast de forma deliberada.** `to` é um array no Sinch e um número único aqui, então use envios individuais ou o endpoint de batch para até 100 mensagens independentes. Uma campanha para audiência pertence ao [fluxo de broadcast](/products/sms/marketing/campaigns). Um batch que nomeava um grupo precisa que a composição do grupo seja resolvida primeiro; veja a seção de opt-out, porque é o mesmo problema.
- **`body` passa a ser `text`.** É a única renomeação que afeta todos os pontos de chamada.
- **`client_reference` não é uma chave de idempotência.** O Sinch o define como um identificador adicionado ao relatório de entrega do batch, então ele correlaciona, mas não deduplica. Se você dependia dele para tornar uma retentativa segura, não estava coberto; `Idempotency-Key` é o que faz isso aqui.
- **Nada corresponde a `category`.** Decida por tipo de mensagem se é `transactional`, `marketing`, `authentication` ou `service`.

## Transfira os opt-outs

**O Sinch registra quem está dentro, e Bird precisa saber quem está fora.** Essa inversão é o trabalho.

O Sinch gerencia destinatários como grupos, e um grupo pode se atualizar automaticamente a partir de palavras-chave, então um assinante que envia `STOP` é removido do grupo e um assinante que envia `SUBSCRIBE` é adicionado. O opt-out é, portanto, codificado como _ausência_ de uma lista, e não como presença em uma, e ausência não é exportável: um número ausente de um grupo pode ter feito opt-out, pode nunca ter entrado, ou pode ter sido removido por uma importação seis meses atrás.

Então reconstrua em vez de exportar. Seu próprio log de mensagens recebidas é a fonte confiável, porque alguns opt-outs começaram como mensagens recebidas, enquanto outros vieram via suporte, formulários ou outro canal de preferência, e essas mensagens existem independentemente do que a composição do grupo diz agora. Onde você manteve sua própria flag de cancelamento de inscrição ao lado do grupo, essa flag é uma evidência melhor do que a composição do grupo. Leve a lista reconstruída para o [fluxo de supressão](/docs/guides/sms/migrate#4-carry-over-your-opt-out-list) e mostre a lista a quem é responsável pela conta antes de importá-la: uma entrada errada aqui bloqueia silenciosamente mensagens que você pretendia enviar.

Uma supressão no Bird é um par remetente-e-assinante, então um assinante que você bloqueia em três remetentes são três registros. [Leitura e gerenciamento de supressões](/docs/guides/sms/opt-outs-and-keywords#reading-and-managing-suppressions) traz o comando e o motivo pelo qual uma supressão manual bloqueia todas as categorias, incluindo transacional.

Uma vez aqui, o Bird responde às palavras-chave de parada por conta própria a partir do seu catálogo por país, então o comportamento de atualização automática do grupo não tem equivalente a reconstruir: um assinante que envia `STOP` produz uma supressão sem que sua aplicação faça nada. Os motivos se acumulam em vez de se fundir, então um par que você importou como `manual` que depois envia `STOP` mantém dois registros, e as mensagens permanecem bloqueadas 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. Bird escolhe um evento de falha com base no status e motivo reportados. Uma solicitação API recusada não cria mensagem; uma rejeição após a aceitação pode produzir `sms.rejected`, incluindo uma rejeição da operadora. Evidência de entrega ausente permanece como desconhecida. Preserve o status e o código brutos do provedor junto com o resultado normalizado.

A [referência de relatórios de entrega](https://developers.sinch.com/docs/sms/api-reference/sms/delivery-reports/getdeliveryreportbybatchid) do Sinch inclui queued, dispatched, delivered e diversos estados finais de falha distintos. Preserve o código e o status no nível do destinatário ao traduzir seus relatórios.

| Conceito Sinch                      | Decisão de integração Bird                                                                                                                 |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `Queued` / `Dispatched`             | Rastreie aceitação e envio à operadora separadamente com `sms.accepted` e `sms.sent`.                                                      |
| `Delivered`                         | Registre o resultado da rede via `sms.delivered`; ele não comprova leitura.                                                                |
| `Failed` / `Rejected` / `Deleted`   | Inspecione o motivo reportado. Eventos de falha do Bird não são selecionados por uma substituição apenas de nome.                          |
| `Aborted` / `Expired` / `Cancelled` | Preserve a causa e o estágio. O API de envio individual do Bird não possui agendamento nem timer de validade para recriar esses controles. |
| `Unknown`                           | Mantenha o resultado como incerto; não conte um recibo ausente e interpretável como entrega.                                               |

O `sms.expired` do Bird segue um relatório de expiração da operadora. Revise seu comportamento existente de expiração e cancelamento separadamente desse evento, em vez de mapear cada timeout para ele.

Note também que status intermediários só são reportados quando o batch solicitou relatório `per_recipient`, que é parte do que muda a seguir.

**Você perde o controle por envio dos relatórios de entrega, e vale dizer isso de forma direta.** Um batch do Sinch escolhe sua própria granularidade de relatório e pode substituir a URL de callback do service plan para aquele envio específico. Bird não tem nenhum dos dois: o relatório é uma assinatura do espaço de trabalho, todo evento inscrito é entregue, e não há substituição por mensagem. Se você usava `delivery_report` para silenciar campanhas com muito tráfego, essa filtragem passa para o seu handler. Se você direcionava os relatórios de uma campanha para um endpoint diferente, isso se torna um endpoint com uma ramificação, ou uma segunda assinatura.

Registre o endpoint uma vez, nomeando os tipos de evento que seu handler deseja: os eventos `sms.*` acima são a lista para assinar, e não há wildcard que os substitua. Bird envia JSON assinados conforme [Standard Webhooks](https://www.standardwebhooks.com); [Criar um endpoint](/docs/guides/webhooks#create-an-endpoint) traz o comando e a única coisa a acertar na primeira chamada, que é armazenar o signing secret que a resposta mostra uma única vez.

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](/docs/guides/sms/events#failure-events).

## Migração final

[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. Dois itens específicos do Sinch pertencem ao plano de migração final.

Sua marca e campanha 10DLC estão registradas no The Campaign Registry através do Sinch e não se tornam automaticamente registros no Bird. Confirme o procedimento de migração ou registro aplicável antes de enviar trabalho pago. **É aqui também que a integração simplifica.** No Sinch, a API de registro é um host separado do envio e usa credenciais de projeto em vez do token do service plan, e a própria documentação do Sinch diz que HTTP Basic ali é destinado apenas para fins de teste e tem limitação de requisições severa, então uma integração de produção constrói um fluxo de token OAuth para isso. No Bird, `/v1/sms/10dlc/*` fica ao lado de `/v1/sms/messages` sob uma única URL base e uma única chave, então esse ciclo de vida de token é aposentado em vez de portado. Comece por [Registrar para 10DLC](/docs/guides/sms/10dlc), que cobre o que cada campo significa e a chamada de requisitos que informa o que você precisa fornecer antes de criar a marca, que é a etapa cobrada.

Números que você possui no Sinch precisam de uma portabilidade que o suporte organiza, no cronograma dele, não no seu.

## Próximos passos

- [Compare Bird e Sinch para SMS](/products/sms/compare/bird-vs-sinch): avaliação de produto e considerações de migração

- [Enviando SMS](/docs/guides/sms/sending-sms): o payload para o qual você está migrando, completo
- [Opt-outs e palavras-chave](/docs/guides/sms/opt-outs-and-keywords): cobertura de palavras-chave por país e gerenciamento de supressão
- [Eventos SMS](/docs/guides/sms/events): o vocabulário de eventos para o qual seu handler de relatórios migra
- [Webhooks e 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)