API de Gerenciamento do WhatsApp Business
Voltar para Português (Brasil)
Este documento foi atualizado.
A tradução para Português (Brasil) não foi concluída ainda.
Atualização em inglês: 31 de out

Visão geral

A API de Gerenciamento do WhatsApp Business permite que você crie e gerencie ativos de negócios relacionados ao WhatsApp, como as contas do WhatsApp Business e os modelos de mensagem. Ela se baseia na API de Marketing e aproveita alguns dos seus pontos de extremidade. Por isso, esta documentação pode conter links para a documentação da API de Marketing, quando necessário.

Requisitos

Tokens de acesso

A plataforma é compatível com os seguintes tipos de token de acesso. O tipo de token depende de quem usará seu app e se você é ou não um parceiro de solução.

Tokens de acesso de usuário do sistema

Os tokens de acesso de usuário do sistema representam você, sua empresa ou organização ou pessoas dentro da sua empresa ou organização. A principal vantagem desses tokens é que eles não expiram e podem representar serviços automatizados dentro da sua empresa que não exigem nenhuma entrada do usuário.

Os tokens de acesso de usuário do sistema são o único tipo de token que pode ser usado pelos parceiros de soluções para compartilhar linhas de crédito com clientes integrados.

Antes de gerar um token de acesso de usuário do sistema, você deve criar um usuário do sistema. A maioria dos pontos de extremidade verifica se o usuário identificado pelo token tem acesso ao recurso consultado. Caso o usuário não tenha acesso ao recurso, a solicitação será rejeitada com o código de erro 200.

Os usuários do sistema podem ser destinados a funcionários ou administradores.

Usuários do sistema para funcionários

Os usuários do sistema para funcionários devem ter acesso a contas individuais do WhatsApp Business pertencentes ou compartilhadas com a empresa da Meta. Se o app precisar acessar apenas algumas contas do WhatsApp Business que pertencem a você, um usuário do sistema para funcionário deverá ser suficiente.

Depois de criado, conceda acesso aos ativos de negócios no nível parcial ou total a cada conta do WhatsApp Business que o usuário do sistema precisa acessar.

Usuários administradores do sistema

Por padrão, os usuários administradores do sistema têm acesso total a todas as contas do WhatsApp Business e aos respectivos ativos pertencentes a ou compartilhados com você ou sua empresa.

Os usuários administradores do sistema serão úteis se o app precisar acessar contas do WhatsApp Business recém-compartilhadas com sua empresa. Caso esteja usando um usuário do sistema para funcionário, será preciso conceder acesso aos ativos de negócios manualmente a cada conta do WhatsApp Business que foi compartilhada com você.

É possível substituir o acesso padrão aos ativos de negócios de um usuário administrador do sistema concedendo acesso parcial a contas do WhatsApp Business. Consulte Acesso aos ativos de negócios para saber como configurar e substituir acessos.

Como criar usuários do sistema

Para criar um usuário do sistema:

  1. Acesse o Meta Business Suite.
  2. Encontre a conta empresarial no menu suspenso no canto superior esquerdo. Clique em Configurações (ícone de engrenagem).
  3. Clique em Configurações do negócio.
  4. Navegue até Usuários > Usuários do sistema.
  5. Clique no botão Adicionar e crie um usuário do sistema do tipo administrador ou funcionário.

Como gerar tokens de acesso de usuário do sistema

Para gerar um token de acesso de usuário do sistema depois de criar um usuário desse tipo:

  1. Acesse o Meta Business Suite.
  2. Encontre a conta empresarial no menu suspenso no canto superior esquerdo. Clique em Configurações (ícone de engrenagem).
  3. Clique em Configurações do negócio.
  4. Navegue até Usuários > Usuários do sistema.
  5. Selecione o usuário do sistema apropriado na lista.
  6. Clique no botão Gerar novo token.
  7. Selecione o app que usará o token.
  8. Selecione as permissões da Graph API necessárias para o app funcionar corretamente e gere o token.

Tokens de acesso do usuário do sistema de integração comercial

Os tokens de acesso de usuário do sistema de integração comercial têm como escopo clientes individuais e devem ser usados por provedores de tecnologia e parceiros de soluções ao acessar dados de clientes integrados.

Esses tokens são úteis para apps que realizam ações programáticas e automatizadas nas contas do WhatsApp Business dos clientes, sem precisar depender da entrada de um usuário do app nem exigir uma nova autenticação no futuro.

Para gerar tokens de acesso de usuário do sistema de integração comercial, será preciso implementar o Cadastro Incorporado (configurado com o Login do Facebook para Empresas) e trocar o código retornado a você quando um cliente concluir o fluxo.

Consulte os documentos sobre Cadastro Incorporado e tokens de acesso de usuário do sistema de integração comercial para saber mais sobre esses tokens e entender como eles são gerados.

Tokens de acesso do usuário

Embora os tokens de acesso do usuário sejam compatíveis e possam ser usados por todos os desenvolvedores de apps, você provavelmente só os usará quando acessar o Painel de Apps pela primeira vez para enviar sua primeira mensagem. No entanto, ao desenvolver seu app, a tendência é que você mude para um token de acesso de usuário do sistema (e, eventualmente, para um token de acesso de usuário do sistema de integração comercial, caso você seja um provedor de tecnologia ou parceiro de solução). Isso ocorre porque os tokens de acesso do usuário expiram rapidamente, o que significa que você terá que gerar um novo em intervalos de poucas horas.

Existem várias maneiras de gerar um token de acesso do usuário:

  • Acesse Painel de Apps > WhatsApp > Configuração da API. Esse painel gera um novo token de acesso do usuário sempre que você o visita. O token tem escopo automático para seu usuário, já que você fez login com sua conta de desenvolvedor ao acessar o painel.
  • Use o Explorador da Graph API.
  • Implemente o Login do Facebook.

Como usar tokens em solicitações

Ao fazer solicitações de API, inclua o token no cabeçalho da solicitação de autorização, antecedido por Bearer. Por exemplo:

curl 'https://graph.facebook.com/v18.0/102290129340398/message_templates' \
-H 'Authorization: Bearer EAAJB...' \

Acesso aos ativos de negócios

Depois de criar um usuário do sistema, você precisa definir os níveis de acesso aos ativos de negócios. Muitos pontos de extremidade exigem que o usuário do sistema cujo token está incluído nas solicitações de API tenha acesso parcial ou total aos ativos de negócios na conta do WhatsApp Business que está sendo consultada (ou aos ativos relacionados). Caso não tenha acesso, os pontos de extremidade retornarão o código de erro 200.

Lembre-se de que, ao definir o acesso aos ativos de negócios de um usuário do sistema em uma conta do WhatsApp Business como parcial, você poderá restringir ainda mais o acesso a determinados ativos ou ações na conta em questão. Por exemplo, se você tem uma empresa grande e quer que um departamento específico tenha apenas acesso de leitura ao modelo de uma conta do WhatsApp Business e aos dados do número de telefone comercial, crie um usuário do sistema para esse departamento e defina o acesso detalhado para somente visualização.

Para definir o acesso a ativos de negócios em uma conta do WhatsApp Business:

  1. Acesse o Meta Business Suite.
  2. Encontre a conta empresarial no menu suspenso no canto superior esquerdo. Clique em Configurações (ícone de engrenagem).
  3. Navegue até Contas > Contas do WhatsApp.
  4. Selecione a conta do WhatsApp Business apropriada.
  5. Selecione a aba Acesso à conta do WhatsApp.
  6. Clique no botão Adicionar pessoas.
  7. Selecione o usuário do sistema apropriado e atribua os níveis de acesso adequados na conta do WhatsApp Business.

Testar pontos de extremidade

Para testar os pontos de extremidade, recomendamos o uso do cURL ou da coleção do Postman. É possível usar o Explorador da Graph API, mas ele passa os tokens como parâmetros de string de consulta, o que não é recomendado. Em vez disso, passe os tokens em cabeçalhos de solicitação.

Obter informações sobre uma empresa

Para obter informações sobre uma empresa, envie uma solicitação GET para o ponto de extremidade WhatsAppBusinessAccount, em que <WHATSAPP_BUSINESS_ACCOUNT_ID> é a identificação da conta do WhatsApp Business.

Exemplo de solicitação

curl -i -X GET 'https://graph.facebook.com/v21.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Exemplo de resposta

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "timezone_id": "1",
  "message_template_namespace": "05155c78_261e_4b2f_82b3_d7958d4cf75f"
}

Para obter informações específicas sobre uma empresa (como nome, modelo de mensagem e número de telefone), envie uma solicitação GET para o ponto de extremidade WhatsAppBusinessAccount, sendo <WHATSAPP_BUSINESS_ACCOUNT_ID> a identificação da conta do WhatsApp Business. Além disso, defina o parâmetro fields como uma lista de itens que você quer que seja retornada.

Exemplo de solicitação

curl -i -X GET 'https://graph.facebook.com/v21.0/<WHATSAPP_BUSINESS_ACCOUNT_ID>?fields=id,name,message_templates,phone_numbers' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>'

Exemplo de resposta

{
  "id": "<WHATSAPP_BUSINESS_ACCOUNT_ID>",
  "name": "Your WhatsApp Business Account Name",
  "message_templates": {
    "data": [
      {
        "name": "hello_world",
        "components": [
          {
            "type": "HEADER",
            "format": "TEXT",
            "text": "Hello World"
          },
          {
            "type": "BODY",
            "text": "Welcome and congratulations!! This message demonstrates your ability to send a message notification from WhatsApp Business Platform. Thank you for taking the time to test with us."
          },
          {
            "type": "FOOTER",
            "text": "WhatsApp Business Team"
          }
        ],
        "language": "en_US",
        "status": "APPROVED",
        "category": "ACCOUNT_UPDATE",
        "id": "307191531401674"
      },
      {
        "name": "sample_flight_confirmation",
        "components": [
          {
            "type": "HEADER",
            "format": "DOCUMENT"
          },
          {
            "type": "BODY",
            "text": "Confirmamos tu vuelo a {{1}}-{{2}} para el {{3}}."
          },
          {
            "type": "FOOTER",
            "text": "Este mensaje proviene de un negocio no verificado."
          }
        ],
        "language": "es",
        "status": "APPROVED",
        "category": "TICKET_UPDATE",
      },
      ...

Limites de volume

As solicitações feitas pelo app para a API de Gerenciamento do WhatsApp Business são computadas conforme a contagem do app. A contagem de chamadas de um app é o número de chamadas que ele pode fazer durante uma hora. Para a API de Gerenciamento do WhatsApp Business a seguir, o seu app pode fazer 200 chamadas por hora em cada conta do WhatsApp Business (WABA). Para WABAs ativas com pelo menos um número de telefone registrado, esse limite é de 5 mil chamadas por hora.
Tipo de chamada Ponto de extremidade

GET

/{whatsapp-business-account-id}

GET, POST e DELETE

/{whatsapp-business-account-id}/assigned_users

GET

/{whatsapp-business-account-id}/phone_numbers

GET, POST e DELETE

/{whatsapp-business-account-id}/message_templates

GET, POST e DELETE

/{whatsapp-business-account-id}/subscribed_apps

GET

/{whatsapp-business-account-to-number-current-status-id}

Para as APIs de linhas de crédito a seguir, é possível fazer 5 mil chamadas por hora para cada app.
Tipo de chamada Ponto de extremidade

GET

/{business-id}/extendedcredits

POST

/{extended-credit-id}/whatsapp_credit_sharing_and_attach

GET e DELETE

/{allocation-config-id}

GET

/{extended-credit-id}/owning_credit_allocation_configs

Para evitar atingir os limites de volume, recomendamos o uso de webhooks para acompanhar atualizações ao status de modelos de mensagem, números de telefone e WABAs.

Se quiser verificar a sua taxa de uso, consulte Cabeçalhos.

Saiba mais

Próximas etapas