Primeiros passos para parceiros de soluções

Este guia mostra as etapas que um parceiro de solução precisa seguir para oferecer a API de Nuvem aos clientes. Estas são as quatro etapas principais:

1. Preparar e planejar
2. Configurar ativos
3. Assinar contratos
4. Criar integração

Depois de concluir o processo, acompanhe as atualizações mensais.

Preparar e planejar

Ler a documentação

Antes de iniciar, recomendamos a leitura da documentação para desenvolvedores e da coleção do Postman. Dessa forma, você pode entender o funcionamento da API de Nuvem e aprender sobre os primeiros passos e a migração de números.

Planejar a integração e a migração

Para integrar novos clientes à API de Nuvem, é preciso usar o cadastro incorporado. Caso ainda não esteja usando, integre e inicie o cadastro incorporado. O cadastro incorporado é a forma mais rápida e fácil de registrar clientes, que podem começar a enviar mensagens em menos de cinco minutos.

Depois, decida quais clientes você quer migrar primeiro para a API de Nuvem. Em geral, recomendamos migrar todos os clientes da API Local para a API de Nuvem, mas as necessidades de cada cliente podem variar. Para decidir quais clientes migrar, considere o seguinte:

Depois de determinar quais clientes migrar, você pode definir um plano e um cronograma de migração.

Ao criar o plano, lembre-se de projetar o sistema para dois cenários: integração de novos clientes e migração dos clientes atuais da API Local para a de Nuvem. Para o cenário de migração, inclua fazer backup da instância atual da API Local e migrar esses números para a API de Nuvem.

Planejar a comunicação com os clientes

Primeiro, é necessário decidir se os clientes atuais serão notificados sobre a migração. Depois, você precisa determinar se há necessidade de criar ou atualizar a documentação de suporte para a configuração da API de Nuvem.

Definir os preços

Como a Meta cobre os custos de hospedagem da API de Nuvem, é necessário decidir se os seus preços serão atualizados de acordo.

Configurar ativos

Para usar a API de Nuvem, os parceiros de soluções precisam ter os seguintes ativos:

Assinar contratos

Aceitação dos Termos de Serviço

Para acessar a API de Nuvem de Mensagens do WhatsApp Business, é necessário primeiro aceitar os Termos de Serviço do WhatsApp Business em nome da sua empresa.

Para isso, acesse o Gerenciador do WhatsApp e aceite os termos no banner informativo.

Caso já seja um parceiro beta da API de Nuvem, você terá um período de carência de 90 dias. Isso significa que é necessário aceitar os termos antes de 5 de julho de 2022 para não perder o acesso.

Para novas empresas da API de Nuvem, inclusive as que estão migrando da API Local, será preciso aceitar os termos de serviço antes de começar a usar a API de Nuvem. Até que você aceite os termos, as chamadas de inscrição falharão.

Criar integração

Etapa 1: obter token de acesso do usuário do sistema

As chamadas da Graph API usam tokens de acesso para autenticação. Para saber mais, consulte Tokens de acesso. Recomendamos que você use o usuário do sistema para gerar o token.

Para gerar um token de acesso do usuário do sistema:

1. Acesse Gerenciador de Negócios > Configurações do negócio > Usuários > Usuários do sistema para ver o usuário do sistema criado por você.
2. Clique no usuário e selecione Adicionar ativos. Essa ação abre uma nova janela.
3. Em Selecionar o tipo de ativo, no painel lateral à esquerda, selecione Apps. Na opção Selecionar ativos, escolha o app da Meta que você quer usar (o app deve ter as permissões corretas). Habilite Desenvolver app para o app escolhido.
4. Selecione Salvar alterações para salvar suas configurações e retornar à tela principal do usuário do sistema.
5. Agora, está tudo pronto para gerar o token. Na tela principal do usuário do sistema, clique em Gerar token e selecione o app da Meta. Depois de fazer isso, você verá uma lista de permissões disponíveis. Selecione whatsapp_business_management e whatsapp_business_messaging. Clique em Gerar token.
6. Uma nova janela abrirá com o usuário do sistema, o app atribuído e o token de acesso. Salve o token.
7. Se você quiser, será possível clicar no token para ver o depurador de token. No depurador, você verá as duas permissões selecionadas. Também é possível colar o token diretamente no Depurador de Token de Acesso.

Etapa 2: configurar Webhooks

Com Webhooks configurados, você recebe notificações HTTP em tempo real da Plataforma do WhatsApp Business. Isso significa que você receberá uma notificação quando um cliente enviar uma mensagem ou quando houver mudanças na sua WABA, por exemplo.

Para configurar seu Webhook, é necessário criar um servidor da web que usa a internet com uma URL que atenda aos requisitos da Meta e do WhatsApp. Consulte Como criar um ponto de extremidade para ver instruções de como fazer isso. Se você precisar de um ponto de extremidade para teste, é possível gerar um ponto de extremidade de Webhook de teste.

Configuração do app

Quando o ponto de extremidade estiver pronto, configure-o para ser usado pelo seu app da Meta:

O Webhooks precisa ser configurado apenas uma vez em cada app. É possível usar o mesmo Webhook para receber diferentes tipos de evento de várias contas do WhatsApp Business. Para saber mais, consulte a seção sobre Webhooks.

Etapa 3: cadastrar sua WABA

Para garantir que você receberá as notificações referentes à conta correta, cadastre seu app:

curl -X POST \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/subscribed_apps' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Se você receber a resposta abaixo, todos os eventos de Webhook referentes aos números de telefone da conta serão enviados para o ponto de extremidade de Webhook que foi configurado.

{
  "success": true
}

Etapa 4: obter o ID do número de telefone

Para enviar mensagens, é necessário cadastrar o número de telefone que você quer usar. Esse é o número de telefone comercial mencionado em Antes de começar.

Para seguir com o cadastro, é necessário localizar o ID do número de telefone. Para isso, faça a seguinte chamada de API:

curl -X GET \
'https://graph.facebook.com/v19.0/WHATSAPP_BUSINESS_ACCOUNT_ID/phone_numbers' \
-H 'Authorization: Bearer ACCESS_TOKEN'

Se o pedido for bem-sucedido, a resposta incluirá todos os números de telefone conectados à sua WABA:

{
  "data": [
    {
      "verified_name": "Jasper's Market",
      "display_phone_number": "+1 631-555-5555",
      "id": "1906385232743451",
      "quality_rating": "GREEN"
    },
    {
      "verified_name": "Jasper's Ice Cream",
      "display_phone_number": "+1 631-555-5556",
      "id": "1913623884432103",
      "quality_rating": "NA"
    }
  ]
}

Salve o ID do número de telefone que você quer cadastrar. Para mais informações sobre esse ponto de extremidade, consulte Ler números de telefone.

Exceção na migração

Etapa 5: cadastrar número de telefone

É possível fazer o cadastro com o ID do número de telefone em mãos. Na chamada de cadastro da API, você realiza duas ações ao mesmo tempo:

1. Cadastra o telefone.
2. Habilita a confirmação em duas etapas por meio de um código de cadastro de 6 dígitos. Esse código deve ser configurado por você. Salve e memorize esse código, pois ele pode ser solicitado posteriormente.

A configuração da autenticação de dois fatores é obrigatória para usar a API de Nuvem. Se não fizer isso, você receberá uma mensagem de falha na integração:

Exemplo de solicitação:

curl -X POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/register' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp","pin": "6_DIGIT_PIN"}'

Exemplo de resposta:

{
  "success": true
}

Usuários do cadastro incorporado

Etapa 6: receber uma mensagem do app do consumidor

Quando um cliente participante envia uma mensagem para a empresa, você tem 24 horas de mensagens gratuitas com ele. Esse espaço de tempo é chamado de janela de atendimento ao cliente. Para fins de teste, queremos habilitar essa janela para que você envie quantas mensagens quiser.

A partir de um app iOS ou Android, envie uma mensagem ao número de telefone que você acabou de cadastrar. Quando ela for enviada, você receberá uma mensagem no seu Webhook com uma notificação no formato abaixo.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "id": "WHATSAPP_BUSINESS_ACCOUNT_ID",
      "changes": [
        {
          "value": {
            "messaging_product": "whatsapp",
            "metadata": {
              "display_phone_number": "16315551234",
              "phone_number_id": "PHONE_NUMBER_ID"
            },
            "contacts": [
              {
                "profile": {
                  "name": "Kerry Fisher"
                },
                "wa_id": "16315555555"
              }
            ],
            "messages": [
              {
                "from": "16315555555",
                "id": "wamid.ABGGFlA5FpafAgo6tHcNmNjXmuSf",
                "timestamp": "1602139392",
                "text": {
                  "body": "Hello!"
                },
                "type": "text"
                }
            ]
          },
        "field": "messages"
        }
      ]
    }
  ]
}

Etapa 7: enviar uma mensagem de teste

Quando habilita a janela de atendimento ao cliente, você pode enviar uma mensagem de teste para o número de telefone do consumidor que usou na etapa anterior. Para isso, faça a seguinte chamada de API:

curl -X  POST \
'https://graph.facebook.com/v19.0/FROM_PHONE_NUMBER_ID/messages' \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-d '{"messaging_product": "whatsapp", "to": "16315555555","text": {"body" : "hello world!"}}'

Se a chamada for bem-sucedida, a resposta incluirá um ID da mensagem. Use esse ID para acompanhar o progresso das mensagens por meio de Webhooks. O ID pode ter até 128 caracteres.

Exemplo de resposta:

{
  "id":"wamid.gBGGFlaCGg0xcvAdgmZ9plHrf2Mh-o"
}

Acompanhar atualizações mensais

Lançaremos atualizações da API de Nuvem na primeira terça-feira de cada mês. Essas atualizações incluem novos recursos e melhorias. A API de Nuvem é atualizada de forma automática. Por isso, não é necessária nenhuma ação adicional para usar os novos recursos.

Perguntas frequentes

Tópicos gerais

Implementação técnica

What is the architecture of the Cloud API?

The Cloud API architecture significantly simplifies the Solution Partner's operational and infrastructure requirements to integrate with WhatsApp Business Platform. First, it removes the infrastructure requirements to run Business API docker containers (CAPEX savings). Second, it obviates the need of operational responsibilities to manage the deployment (OPEX savings). For details, refer to the architecture diagram comparing the On-Premises and Cloud API deployments.

Link permanente

Privacidade e segurança de dados

Conformidade com normas