API de Nuvem

Plataforma do WhatsApp Business > API de Nuvem > Guias

Como migrar da API de Nuvem para a API Local

A API Local está sendo descontinuada. Consulte o documento Descontinuação da API Local para ver mais informações e saber como migrar para nossa API de Nuvem de última geração.

Este documento explica como migrar números de telefone comercial da API de Nuvem para a API Local. Para migrar da API Local para a API de Nuvem, consulte Como migrar da API Local para a API de Nuvem.

Importante: migrar um número de telefone comercial de uma API para outra não equivale a migrar um número de uma conta do WhatsApp Business (WABA, pelas iniciais em inglês) para outra.

A migração NÃO afeta:

  • o nome de exibição, o status de verificação nem a classificação de qualidade do número de telefone comercial;
  • os modelos usados pelo número de telefone comercial nem os respectivos status;
  • a propriedade, o status de conta comercial oficial nem o limite de mensagens da WABA.

Porém, para apoiar o processo de migração, você deve estar ciente das diferenças entre as APIs e precisa tomar as medidas adequadas antes de executar as etapas descritas neste documento.

Boas práticas

Depois de garantir que seu app pode lidar com todas as diferenças entre as APIs, recomendamos começar a migração com um número de telefone comercial de baixo volume e verificar se todas as funcionalidades que você pretende oferecer com a API de Local funcionam corretamente. Quando terminar essa verificação, migre os outros números.

Também recomendamos que você faça a migração quando o tráfego para sua implantação da API Local estiver baixo.

Diferenças entre as APIs

Confirme que seu app é capaz de lidar com essas diferenças antes de iniciar o processo de migração.

Webhooks

As estruturas de carga dos webhooks da API de Nuvem e da API de Gerenciamento do WhatsApp Business são diferentes das da API Local. Recomendamos que você crie um ponto de extremidade de webhook que possa gerenciar webhooks da API Local de forma exclusiva.

Consulte os documentos a seguir para entender as diferenças de carga:

Quando a migração para a API de Local for concluída, os webhooks da API de Nuvem do número de telefone comercial não serão mais entregues, e a entrega dos webhooks da API Local será iniciada.

Mídia

Não será possível usar os IDs de mídias que foram carregadas na API de Nuvem ao enviar mensagens com a API Local. Por isso, carregue novamente a mídia usando a API Local para gerar novos IDs ou use as respectivas URLs caso a mídia esteja hospedada em um servidor público. Consulte Como enviar mensagens de mídia.

Códigos de erro

Os códigos de erro da API de Nuvem e da API de Gerenciamento do WhatsApp Business são diferentes dos da API Local. Consulte estes documentos:

Mensagens push-to-talk

A API Local identifica mensagens push-to-talk (PTT) em webhooks definindo messages.type como voice, já a API de Nuvem as identifica definindo messages.audio.voice como true.

Inatividade

O tempo de inatividade começa assim que você fizer o registro (etapa 3) e deve durar apenas alguns segundos. Durante esse período, as mensagens enviadas por usuários do WhatsApp ao número de telefone serão descartadas silenciosamente.

Recomendamos que você faça a migração durante um período em que o número apresente baixa atividade para reduzir esses impactos.

Etapa 1: fazer a integração da API Local

Já que você migrará um número de telefone comercial para a API Local, verifique se o app consegue usar o cliente da API Local e se os webhooks da conta do WhatsApp Business associada ao número foram configurados corretamente.

Etapa 2: preparar-se para migração

Sugerimos interromper o envio de mensagens enquanto você conclui a migração.

Existem alguns requisitos de rede do cliente local da WhatsApp Business API para a conexão aos servidores do WhatsApp. Para garantir que tudo esteja pronto, consulte Configurar e depurar a rede.

Etapa 3: registrar o cliente da API

Registre o número de telefone comercial no cliente da API Local. Para isso, faça uma chamada ao ponto de extremidade /account:

POST /v1/account

{
    "cc": "COUNTRY_CODE",
    "phone_number": "PHONE_NUMBER_WITHOUT_COUNTRY_CODE",
    "method": "sms" or "voice",
    "cert": "VERIFIED_NAME_CERT_IN_BASE64",
    "pin": "EXISTING_6_DIGIT_PIN" # required if two-step verification is enabled
}

Dependendo da resposta recebida, o procedimento de registro poderá ser concluído ou exigir mais uma etapa. Se o processo for bem-sucedido, você receberá um dos seguintes códigos de status HTTP. Siga as instruções correspondentes à resposta recebida:

  • 201 Created – a conta já existe. Você já se registrou e nenhuma ação é necessária.
  • 202 Accepted – a conta não existe. Dependendo do método selecionado na solicitação, confira seu número para SMS ou para ligação de voz e verifique se recebeu o código de registro. A resposta incluirá uma carga retornada contendo o vname decodificado com base no parâmetro cert para que você confirme se o nome de exibição certo está sendo definido. Se estiver correto, acesse Verificar para finalizar o processo.

Veja aqui todos os campos disponíveis para esse ponto de extremidade.

Depois da conclusão do registro, o cliente da API Local receberá as mensagens.

Etapa 4: definir fragmentos

Quando o cliente estiver registrado, você poderá definir fragmentos, caso necessário.

Etapa 5: iniciar o envio de mensagens

Você está com tudo pronto para enviar mensagens aos clientes. Veja os guias de envio de mensagens para mais orientações.