# Migrar SMS da Infobip

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

Duas diferenças fazem a maior parte do trabalho. O payload da Infobip é construído para o caso de envio em massa, então uma mensagem para uma pessoa é um array de mensagens, cada uma contendo um array de destinos, com o texto dois níveis abaixo em `content.text`; o [`POST /v1/sms/messages`](/docs/api/reference/create-sms-message) recebe `from`, `to` e `text` no nível raiz. E a sua base URL da Infobip é personalizada por conta, no formato `xxxxx.api.infobip.com`, autenticada com `Authorization: App <key>`. O Bird envia a partir de um host regional com uma bearer key, então o host que o seu código armazena muda ao mesmo tempo que o formato do payload.

## Passe isso para o seu agente

Use este resumo no seu agente de código. 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 Infobip 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/infobip.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 Infobip 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.
```

## Mapear a chamada de envio

A tabela de renomeação é curta porque a mudança de formato é o trabalho:

| O que faz               | Infobip                              | Bird                                                                    |
| ----------------------- | ------------------------------------ | ----------------------------------------------------------------------- |
| Destinatário            | `messages[].destinations[].to`       | `to` (um por requisição)                                                |
| Remetente               | `messages[].sender`                  | `from`                                                                  |
| Corpo                   | `messages[].content.text`            | `text`                                                                  |
| Intenção                | (nenhum)                             | `category`, obrigatório em texto livre                                  |
| Relatórios de entrega   | `webhooks.delivery`, por mensagem    | um webhook do espaço de trabalho inscrito nos eventos de entrega abaixo |
| Contexto de ida e volta | `webhooks.callbackData`              | `metadata`, mas veja a nota de tamanho abaixo                           |
| Agrupamento de campanha | `options.campaignReferenceId`        | `tags`, apenas para filtragem; veja abaixo                              |
| Flash                   | `options.flash`                      | sem equivalente                                                         |
| Validade                | `options.validityPeriod`             | sem equivalente: `validity_period` é rejeitado                          |
| Janela de entrega       | `options.deliveryTimeWindow`         | sem equivalente                                                         |
| Retentativas seguras    | (nenhuma nos clientes gerados deles) | header `Idempotency-Key`                                                |

Notas de portabilidade:

- **Três níveis viram nenhum.** O aninhamento existe para transportar muitas mensagens e muitos destinos em uma requisição. Ao enviar uma mensagem para uma pessoa, o Bird recebe os três campos no nível raiz, então o builder que monta os arrays é excluído em vez de traduzido.
- **`callbackData` é maior que `metadata`.** A Infobip aceita até 4.000 caracteres e os retorna no relatório de entrega. O `metadata` do Bird tem limite de 2 KB serializado e é ecoado em cada evento da mensagem, não apenas no terminal. O eco é a melhor parte; o limite não é, então qualquer coisa perto do limite precisa ser reduzida a uma chave que você possa consultar em vez de carregada inteira.
- **`campaignReferenceId` é contexto de relatório, não uma migração de campanha.** Os `tags` do Bird são pares `{name, value}` que se tornam dimensões de consulta, para que você possa fatiar analytics por campanha como fazia. O que não vem com eles é um objeto de campanha: uma tag não cria nem configura um broadcast. Avalie o [fluxo de campanha](/products/sms/marketing/campaigns) separadamente ao migrar campanhas de audiência.
- **`campaignReferenceId` não é uma chave de idempotência.** A Infobip o define como um ID para rastrear o desempenho de uma campanha, então ele agrupa mas não deduplica. Se você dependia dele para tornar uma retentativa segura, não estava coberto; o header `Idempotency-Key` é o que faz isso aqui.
- **Nada corresponde a `category`.** As opções de mensagem da Infobip cobrem validade, janela de entrega, flash e configurações regionais, e nenhuma delas declara por que a mensagem está sendo enviada. Decida por tipo de mensagem se é `transactional`, `marketing`, `authentication` ou `service`.
- **Dois campos de opção não têm destino.** `validityPeriod` é [reservado](/docs/guides/sms/sending-sms#reserved-fields) e responde a `422 SMSUnsupportedFeature`; `deliveryTimeWindow` não tem equivalente, então janelas de agendamento passam para o seu próprio dispatcher.

## Transportar opt-outs

A Infobip mantém uma **Blocklist**: uma lista dos destinatários que optaram por não receber sua comunicação, gerenciada através da API da Blocklist ou pelo People na interface web, com o envio para qualquer pessoa nela recusado. Gatilhos de palavra-chave adicionam automaticamente, então um assinante que envia `STOP` vai parar lá sem que sua aplicação faça nada.

Isso torna a exportação a mais fácil de qualquer provedor neste conjunto, e a expansão a maior. **Uma entrada da Blocklist é um assinante para toda a conta; uma supressão do Bird é um par de remetente e assinante.** Então cada entrada se torna tantas supressões quantos remetentes você tiver: uma Blocklist de mil entradas e seis remetentes são seis mil registros. Calcule o multiplicador antes de começar, porque é a diferença entre uma importação que leva um minuto e uma que precisa de lotes e log de progresso.

Preserve o escopo original da Blocklist. Não restrinja uma revogação durante a migração só porque o novo modelo técnico pode expressar pares mais estreitos. Uma preferência aplicável a todo o espaço de trabalho pode representar uma solicitação mais ampla; ela é um proprietário separado das supressões por remetente. Verifique ambos ao decidir a elegibilidade.

Importe pelo [loop de supressão](/docs/guides/sms/migrate#4-carry-over-your-opt-out-list). [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 toda categoria, incluindo transacional.

Uma vez que você estiver aqui, o Bird responde às palavras-chave de parada por conta própria a partir do seu catálogo por país, então os gatilhos de palavra-chave que você configurou não têm equivalente para reconstruir, e os personalizados se tornam [regras de palavra-chave](/docs/guides/sms/opt-outs-and-keywords#campaign-keywords). Os motivos se empilham 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 continuam bloqueadas até que ambos tenham terminado.

## Traduzir 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 motivo reportados. Uma requisição API recusada não cria mensagem; uma rejeição após aceitação pode produzir `sms.rejected`, incluindo rejeição da operadora. Evidência de entrega ausente permanece desconhecida. Preserve o status bruto do provedor e o código junto com o resultado normalizado.

A Infobip reporta um grupo de status e um nome de status em cada relatório de entrega, e o Bird emite um tipo de evento:

| Resultado                      | Grupo de status Infobip | Bird              |
| ------------------------------ | ----------------------- | ----------------- |
| API aceitou a mensagem         | `PENDING`               | `sms.accepted`    |
| Entregue à operadora           | `PENDING`               | `sms.sent`        |
| Operadora confirmou entrega    | `DELIVERED`             | `sms.delivered`   |
| Operadora reportou não entrega | `UNDELIVERABLE`         | `sms.undelivered` |
| Falha permanente               | `REJECTED`              | `sms.failed`      |
| Recusada antes do envio        | `REJECTED`              | `sms.rejected`    |
| Janela de validade expirou     | `EXPIRED`               | `sms.expired`     |

`EXPIRED` é a linha para ler com atenção, porque cobre duas coisas diferentes do lado deles e apenas uma delas existe aqui. A Infobip expira uma mensagem quando o período de validade da própria plataforma termina, cujo padrão é 48 horas, ou quando a operadora retorna expired como status final. O Bird não define nenhuma janela de validade própria e não executa nenhum timer que encerre uma mensagem, então `sms.expired` só vem do recibo de entrega da operadora. A metade reportada pela operadora é mapeável; a metade do timer da plataforma não tem equivalente, e uma mensagem que teria expirado no relógio deles permanece em trânsito aqui até a operadora decidir.

`REJECTED` aparece duas vezes de propósito. A Infobip o usa tanto para uma mensagem que ela mesma recusou quanto para uma que a operadora retornou como rejeitada, que são os eventos do Bird escolhidos a partir do resultado de processamento ou da operadora e seu motivo; uma rejeição da operadora pode produzir `sms.rejected`. O nome do status dentro do grupo é o que os diferencia, então um handler que ramificava apenas pelo grupo precisa do nome uma vez que estiver aqui. `PENDING` também cobre duas linhas, porque é o grupo em que a mensagem fica desde a aceitação até um relatório terminal chegar.

Três mecânicas mudam junto com os nomes:

- **Assinaturas substituem webhooks por mensagem.** A Infobip nomeia um webhook em cada mensagem, então o destino é escolhido por quem escreve a chamada, e o tipo de conteúdo é escolhido junto. O Bird entrega JSON a endpoints que seu espaço de trabalho registra, cada um inscrito nos tipos de evento que deseja, então um segundo consumidor é uma segunda assinatura em vez de uma alteração em cada ponto de chamada.
- **Você perde a escolha por mensagem, incluindo XML.** A Infobip permite que uma mensagem escolha JSON ou XML e anexe até 4.000 caracteres de dados de callback. O Bird envia apenas JSON, e `callbackData` se torna `metadata`, que é ecoado em cada evento daquela mensagem em vez de apenas no relatório.
- **Pull vira push.** A Infobip permite que você busque relatórios em um endpoint de reports e também os receba. O Bird não tem polling equivalente para eventos; inscreva-se, e leia o estado da mensagem pelo API quando precisar sob demanda.

Registre o endpoint uma vez, nomeando os tipos de evento que seu handler quer: os eventos `sms.*` acima são a lista para se inscrever, e não existe curinga que os substitua. O Bird envia JSON assinados conforme o [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 segredo de assinatura que a resposta mostra exatamente uma vez.

O 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). Mapeie seus alertas para esses em vez dos pares numéricos de grupo e nome da Infobip.

## 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. Três itens específicos da Infobip pertencem ao plano de virada.

**O host muda, e é configuração em vez de código.** Sua base URL da Infobip é emitida por conta; o Bird envia a partir de um host regional escolhido quando seu espaço de trabalho foi criado. Encontre cada lugar onde esse host está definido antes da virada, incluindo variáveis de ambiente, gerenciadores de segredos e manifestos de deploy, porque um esquecido falha em tempo de execução em vez de no build.

Sua marca e campanha 10DLC estão registradas no The Campaign Registry através da API de registro de números da Infobip e não se tornam automaticamente registros do Bird. Confirme o procedimento de migração ou registro aplicável antes de submeter trabalho pago. Comece por [Registrar para 10DLC](/docs/guides/sms/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.

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

## Próximos passos

- [Comparar Bird e Infobip para SMS](/products/sms/compare/bird-vs-infobip): 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, na íntegra
- [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 de SMS](/docs/guides/sms/events): o vocabulário de eventos para o qual seu handler de relatórios migra
- [Webhooks & eventos](/docs/guides/webhooks): configuração de endpoints e verificação de 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)