Migrar SMS do Plivo
Esta página mapeia a Message API, Powerpacks e callbacks de entrega do Plivo para o Bird. Siga o guia principal de migração na ordem e use estes mapeamentos para os passos 3, 4 e 5.
O envio é a parte fácil. Ambos aceitam JSON com nomes de campo em minúsculas, e ambos mantêm o registro 10DLC junto ao envio em vez de em um host separado. Duas coisas mudam. A POST https://api.plivo.com/v1/Account/{auth_id}/Message/ do Plivo autentica com Auth ID e Auth Token via HTTP Basic; o POST /v1/sms/messages recebe uma chave bearer API contra seu host regional, sem segmento de conta no path. E um Powerpack do Plivo agrupa pool de números, comportamento de sticky sender e estado de opt-out em um único objeto; o Bird separa tudo isso entre senders, suppressions e keyword rules, então não há nada para recriar como Powerpack.
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 mudança em produção.
Exemplo de código
Help me migrate my SMS integration from Plivo 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/plivo.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 Plivo 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 | Plivo | Bird |
|---|---|---|
| Destinatário | dst | to (um por solicitação) |
| Remetente | src ou powerpack_uuid | from |
| Corpo | text | text |
| Seletor de canal | type: sms, mms, whatsapp | o próprio endpoint; /v1/sms/messages é SMS |
| Intenção | (nenhum) | category, obrigatório em texto livre |
| Relatórios de entrega | url + method, por mensagem | um webhook do espaço de trabalho; apenas JSON POST, veja abaixo |
| Contexto de ida e volta | seu próprio armazenamento, indexado por UUID | metadata: JSON arbitrário, ecoado em cada evento |
| Labels filtráveis | (nenhum) | tags: pares {name, value} |
| Retentativas seguras | (não documentado) | header Idempotency-Key |
| Mídia | media_urls | sem equivalente: media_urls é rejeitado |
Notas de portabilidade:
- Um UUID de Powerpack se torna um valor simples de sender. O Plivo resolve o pool de números, o sticky sender e a presença local por trás do UUID. O Bird recebe o próprio sender em from, então escolha-o por envio, ou use um envio por template, que seleciona um sender válido para o destino e rejeita from.
- type não tem equivalente porque o endpoint já o carrega. O Plivo seleciona o canal por solicitação; SMS, WhatsApp e outros canais do Bird são endpoints separados. Um código que alterna type em tempo de execução se divide em chamadas a endpoints diferentes.
- Nada na Message API corresponde a category. Decida por tipo de mensagem se é transactional, marketing, authentication ou service. Tráfego de autenticação em particular deve ser rotulado como tal, em vez de ficar em um padrão de marketing.
- Revise a semântica de retentativa separadamente. A referência de envio do Plivo não documenta chave de idempotência nem mecanismo de deduplicação, então um timeout ali deixa você no escuro. Envie o header Idempotency-Key desde a primeira portabilidade para reduzir o risco de solicitações duplicadas dentro da janela de replay de três horas; não é uma garantia de entrega exatamente uma vez.
Transfira os opt-outs
O serviço DND do Plivo bloqueia mensagens de saída de um número Plivo para um destino assim que esse destino responde com uma palavra-chave de opt-out. Um envio bloqueado retorna sinalizado com o código de erro 200 do Plivo, que é um dos códigos de erro de mensagem deles e não um status HTTP, por mais que pareça. Esse pareamento é como uma suppression do Bird também funciona: um sender e um subscriber, então o escopo importado deve cobrir cada sender e programa incluído na solicitação da pessoa.
Uma coisa se expande, e é o motivo para contar antes de importar. Dentro de uma campanha 10DLC nos EUA, o Plivo trata um opt-out de qualquer número como um opt-out de todos os números vinculados àquela campanha. O Bird armazena pares, então um subscriber que fez opt-out de uma campanha com quatro números se torna quatro suppressions em vez de uma. Calcule em quantos pares sua lista se transforma antes de começar, porque isso decide se a importação é um loop de dezenas ou de milhares.
Extrair a lista é uma exportação pelo console, não uma chamada API: filtre os números no console do Plivo, selecione-os e use Export CSV no menu Choose Action. Importe o resultado pelo loop de suppression. Leitura e gerenciamento de suppressions traz o comando e o motivo pelo qual uma suppression manual bloqueia todas as categorias, incluindo transacional.
O Bird trata palavras-chave de parada suportadas por meio de seu catálogo específico por país. Um envio para um par suprimido é recusado na admissão com E12077 SMSRecipientSuppressed. Um opt-out reportado pela operadora é um resultado de entrega recipient_opted_out separado. Substitua o tratamento do código de erro 200 do Plivo pelos caminhos de admissão e entrega apropriados, e recrie quaisquer respostas personalizadas como keyword rules.
Isso importa novamente mais tarde, quando o tráfego estiver fluindo. Os motivos se acumulam em vez de se fundir: um par que você importou como manual e que depois envia STOP recebe um segundo registro com motivo keyword_stop, e as mensagens continuam bloqueadas até que cada registro daquele par tenha terminado. Então retomar um subscriber que você importou significa remover ambos, e uma retomada que limpa apenas o registro de keyword parece bem-sucedida mas não muda nada.
Traduza os 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 solicitação API recusada não cria mensagem; uma rejeição após a aceitação pode produzir sms.rejected, incluindo rejeição pela operadora. Evidência de entrega ausente permanece como desconhecida. Preserve o status e código brutos do provedor junto ao seu resultado normalizado.
| Resultado | Plivo message_state | Bird |
|---|---|---|
| API aceitou a mensagem | queued | sms.accepted |
| Entregue à operadora | sent | sms.sent |
| Operadora confirmou entrega | delivered | sms.delivered |
| Operadora reportou não entrega | undelivered | sms.undelivered |
| Falha permanente | failed | sms.failed |
| Recusado antes do envio | rejected | sms.rejected |
| Janela de validade expirada | (nenhum) | sms.expired |
Duas mecânicas mudam junto com os nomes:
- Endpoints substituem URLs de callback por mensagem. O Plivo recebe uma url em cada envio, então o destino é escolhido por quem escreve a chamada. O Bird entrega a endpoints que seu espaço de trabalho registra, cada um inscrito nos tipos de evento que deseja, então um novo consumidor é uma nova inscrição em vez de uma mudança em cada ponto de chamada.
- Posts JSON assinados substituem um callback GET, se foi isso que você escolheu. O method do Plivo seleciona GET ou POST para o relatório de entrega; o Bird faz POST de um evento JSON e não oferece GET. Se você configurou method=GET, seu handler lê o resultado dos parâmetros de query string, e esse handler é uma reescrita, não um recadastramento. O mesmo vale no guia ao lado, no caminho da Connectivity Platform.
- Um esquema de assinatura substitui três headers. O Plivo assina callbacks com X-Plivo-Signature-V2, X-Plivo-Signature-Ma-V2 e X-Plivo-Signature-V2-Nonce. O Bird envia JSON assinado conforme Standard Webhooks, então o verificador é substituído, não ajustado: troque-o pela receita em Webhooks & events.
Registre o endpoint uma vez, nomeando os tipos de evento que seu handler deseja: os eventos sms.* acima são a lista para se inscrever, e não há wildcard que os substitua. Criar um endpoint traz o comando e a única coisa a acertar na primeira chamada, que é armazenar o signing secret que a resposta mostra apenas uma vez.
Os valores numéricos error_code do Plivo não têm mapeamento um-para-um. 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. Mapeie seus alertas para esses.
Migração
Destinos, senders e o ramp de tráfego são independentes de provedor e cobertos no guia principal. Dois itens específicos do Plivo pertencem ao plano de migração.
Sua marca e campanha 10DLC estão registradas no The Campaign Registry por meio do Plivo e não se tornam automaticamente registros Bird. Confirme o procedimento de migração ou registro aplicável antes de submeter trabalho pago. A cadeia é mais curta aqui. O Plivo registra primeiro um perfil e depois uma marca vinculada a ele, sob /v1/Account/{auth_id}/10dlc/; o Bird não tem objeto de perfil, então os detalhes comerciais que o Plivo mantém no perfil são fornecidos na própria marca. Comece por Registrar para 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 é a etapa cobrada.
Números que você possui no Plivo precisam de uma portabilidade que o suporte organiza, no cronograma deles, não no seu. Comece cedo e ela acontece em paralelo com a mudança de código.
Próximos passos
-
Compare Bird e Plivo para SMS: avaliação de produto e considerações de migração
-
Enviando SMS: o payload para o qual você está migrando, na íntegra
-
Opt-outs e keywords: cobertura de keywords por país e gerenciamento de suppressions
-
Eventos SMS: o vocabulário de eventos para o qual seu handler de callback migra
-
Webhooks & events: configuração de endpoint e verificação Standard Webhooks
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.