API de Nuvem

Plataforma do WhatsApp Business > API de Nuvem

Visão geral

A API de Nuvem hospedada pela Meta permite que as empresas de grande e médio porte se comuniquem em escala com os clientes. Com a API, as empresas podem criar sistemas que conectam milhares de clientes com agentes ou bots, oferecendo uma comunicação programática e manual. Além disso, as empresas podem integrar a API a diversos sistemas de back-end, como plataformas de CRM e marketing.

Protocolo HTTP

Como a API de Nuvem é baseada na Graph API, as solicitações são expressas usando o protocolo HTTP e combinações de parâmetros de URL, cabeçalhos e corpos de solicitação. Este é um exemplo comum de chamada para a API de Nuvem a partir da linha de comando baseada em UNIX:

curl 'https://graph.facebook.com/v17.0/106540352242922/messages' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer EAAJB...' \
-d '
{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+16505555555",
  "type": "text",
  "text": {
    "preview_url": true,
    "body": "Here'\''s the info you requested! https://www.meta.com/quest/quest-3/"
  }
}'

Caso você não conheça a Graph API, leia a documentação correspondente para aprender o básico. As principais diferenças entre a Graph API e a API de Nuvem são os tipos de token de acesso que você usará, as permissões de recursos, a sintaxe da solicitação e a sintaxe de webhooks. Essas distinções são descritas em mais detalhes nas seções apropriadas da documentação da API de Nuvem.

Recursos

Você interagirá com os recursos a seguir ao usar a API:

Portfólio empresarial

Para usar a API, você precisa ter um portfólio empresarial. Se não tiver um, será preciso criá-lo como parte do nosso processo de introdução. Os portfólios empresariais servem como um contêiner de contas do WhatsApp Business (WABA) e números de telefone.

Para saber mais sobre portfólios empresariais, leia nosso artigo Sobre os portfólios empresariais no Meta Business Suite da Central de Ajuda.

Contas do WhatsApp Business

Uma conta do WhatsApp Business representa uma empresa na Plataforma do WhatsApp Business e é composta principalmente por metadados sobre um negócio específico. A maioria dos outros recursos do WhatsApp, como números de telefone do WhatsApp Business e modelos de mensagem do WhatsApp estão associados a um WABA.

Você pode criar um WABA seguindo as etapas descritas no documento Introdução. Para saber mais sobre as WABAs e as limitações relacionadas, consulte Contas do WhatsApp Business.

Números de telefone do WhatsApp Business

Um número de telefone do WhatsApp Business (número de telefone comercial) representa um número de telefone real que, uma vez registado para uso com a API de Nuvem, pode ser usado para trocar mensagens com usuários do WhatsApp via API.

Os números de telefone comercial são compostos principalmente por metadados sobre o próprio número e sua empresa. Esses dados podem ser exibidos no cliente do WhatsApp quando os usuários interagem com o número de telefone da sua empresa.

Você pode criar um número de telefone comercial seguindo as etapas descritas no documento Introdução. Existem restrições e limitações relacionadas aos números de telefone comercial e ao uso deles. Para saber mais, consulte Business Phone Numbers.

Modelos de mensagem do WhatsApp

Os modelos de mensagem do WhatsApp são modelos personalizáveis que você pode criar via API usando diferentes componentes. Depois de criados, eles são automaticamente analisados e, se forem aprovados, poderão ser usados em mensagens de modelo.

Há dois tipos básicos de mensagens que você pode enviar usando a API: mensagens em formato livre e mensagens de modelo. Quando comparamos os dois tipos, as mensagens de modelo são mais restritivas porque exigem o uso de um modelo de mensagem do WhatsApp que já tenha sido aprovado. No entanto, como os modelos precisam passar por um processo de análise e receber aprovação antes de serem usados, as mensagens de modelo têm menos probabilidade de receber feedback negativo dos destinatários. Isso é uma vantagem, já que um número alto de comentários negativos pode impedir seu app de enviar mensagens aos clientes.

Para saber mais sobre os modelos, consulte Modelos.

Webhooks

Os webooks são basicamente cargas JSON enviadas para um ponto de extremidade público no seu servidor usando o protocolo HTTP. A API de Nuvem depende totalmente dos webhooks. Isso porque o conteúdo de qualquer mensagem enviada por um usuário do WhatsApp ao seu número de telefone comercial é transmitido como um webhook, e todas as atualizações de status de entrega de mensagens enviadas são registradas via webhook.

Temos um exemplo de app de webhook que você pode clonar no Glitch e usar para testes. O app faz um dump de cargas de webhooks diretamente para uma console, permitindo que você veja o conteúdo. Em algum momento, você precisará criar um ponto de extremidade próprio no seu servidor para processar webhooks de acordo com a lógica da sua empresa.

Consulte Webhooks da Meta para saber mais sobre os webhooks e entender como processá-los. Leia também o documento Webhooks for WhatsApp Business Accounts.

Recursos de teste

Depois de concluir as primeiras etapas descritas no documento Introdução, uma WABA e um número de telefone comercial de teste serão criados automaticamente para você.

As WABAs e os números de telefone de teste são úteis para fazer experimentos, já que ignoram a maioria dos limites de mensagens e não exigem uma forma de pagamento registada para enviar mensagens de modelo.

Será possível excluir seu portfólio empresarial e os respectivos recursos de teste se:

  • você for um administrador do portfólio empresarial associada ao app;
  • nenhum outro app estiver associado ao portfólio empresarial;
  • o portfólio empresarial não estiver associada a nenhuma outra WABA;
  • a WABA não estiver associada a nenhum outro número de telefone comercial.

Para excluir seu portfólio empresarial e os respectivos recursos de teste:

  1. Acesse Painel de Apps > WhatsApp > Configuração.
  2. Encontre a seção Conta de teste .
  3. Clique no botão Excluir.

Autenticação e autorização

Tokens de acesso

A API é compatível com três tipos de token:

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

Confira nossos tokens de acesso para determinar qual deles você deve usar. Importante: os tokens devem ser transmitidos via cabeçalhos de solicitação , e não como um parâmetro da string de consulta.

Permissões

A API depende das seguintes permissões da Graph API. A combinação exata de permissões necessária depende de quais pontos de extremidade seu app acessará.

  • business_management — necessária para interagir com um portfólio empresarial.
  • whatsapp_business_management: necessária para interagir com uma WABA e as respectivas análises ou com qualquer um dos modelos ou números de telefone comercial associados.
  • whatsapp_business_messaging: necessária para trocar mensagens com usuários do WhatsApp.

Normalmente, essas permissões são concedidas durante a geração de tokens de acesso no Meta Business Suite. Consulte as seções sobre geração de tokens no documento Tokens de acesso.

Controle de versões

O controle de versões da Graph API usa o protocolo de controle de versões. Isso significa que todas as solicitações de pontos de extremidade podem incluir um número de versão. Cada versão fica disponível por aproximadamente dois (2) anos até se tornar obsoleta.

Taxa de transferência de dados

Para cada número de telefone comercial registrado, a API de Nuvem é compatível com até 80 mensagens por segundo (mps). Esse limite pode aumentar para até 1.000 mps por atualização automática.

A taxa de transferência de dados inclui mensagens enviadas e recebidas, assim como todos os tipos de mensagem. Independentemente da taxa de transferência de dados, os números de telefone comercial ainda estarão sujeitos ao limite de volume do caso de uso da empresa e aos limites de modelos de mensagem da conta do WhatsApp Business.

Se você tentar enviar mais mensagens do que o permitido pelo nível de taxa de transferência de dados atual, a API retornará o código de erro 130429 até que você volte ao nível permitido. Além disso, os níveis de taxa de transferência de dados são destinados a campanhas de mensagens envolvendo diferentes números de telefone de usuário do WhatsApp. Se tentar enviar muitas mensagens ao mesmo número de usuário do WhatsApp, você poderá receber um erro de limite de volume de emparelhamento.

Taxa de transferência de dados mais alta

Se você atender aos requisitos de qualificação, atualizaremos a taxa de transferência de dados do seu número de telefone comercial para 1.000 mps sem custos. Isso não gerará cobranças adicionais nem afetará os preços.

O processo de atualização pode levar até 1 minuto. Durante esse período, o número de telefone não poderá ser usado na nossa plataforma. Se ele for usado em chamadas de API, o código de erro 131057 será retornado. Assim que o número de telefone comercial for atualizado, futuras alterações na taxa de transferência de dados serão feitas automaticamente sem tempo de inatividade.

Requisitos de qualificação

Webhooks

Seus servidores de webhook devem suportar 3 vezes a capacidade do tráfego de mensagens de saída e 1 vez a capacidade do tráfego de mensagens de entrada esperado. Por exemplo, se considerarmos um envio de 1.000 mps a uma taxa de resposta esperada de 30%, seus servidores deverão ser capazes de processar até 3.000 webhooks de status de mensagem, mais 300 webhooks adicionais de mensagens recebidas.

Tentamos entregar os webhooks simultaneamente; por isso, recomendamos que você configure e faça um teste de carga do servidor de webhook para processar solicitações concomitantes com o padrão de latência descrito a seguir:

  • Latência mediana não superior a 250 ms.
  • Menos de 1% de latência excede 1 s.

Tentaremos entregar os webhooks com falha novamente por até 7 dias, com retirada exponencial.

Mensagens de mídia

Para aproveitar ao máximo a taxa de transferência de dados superior, recomendamos carregar os ativos de mídia nos nossos servidores e usar os IDs de mídia retornados nas mensagens de mídia em vez de hospedar os ativos nos seus servidores e usar as respectivas URLs. Caso você prefira ou precise hospedar os ativos em servidores próprios, recomendamos usar o armazenamento em cache de mídia.

Como obter o nível da taxa de transferência de dados

Use o ponto de extremidade WhatsApp Business Phone Number para obter o nível da taxa de transferência de dados atual de um número de telefone:

GET /<WHATSAPP_BUSINESS_PHONE_NUMBER_ID>?fields=throughput

Migração

Se você migrar um número de telefone comercial que tenha multiconexão executando 2 ou mais fragmentos da API Local para a API de Nuvem, ele será atualizado automaticamente para uma taxa de transferência de dados mais alta.

Limites de volume

Consulte Limites de volume da API de Gerenciamento do WhatsApp Business.

Além desses limites de volume, há limites mais detalhados em recursos individuais, como modelos de mensagem e números de telefone comercial de teste:

Métricas disponíveis

O usuário da API de Nuvem pode ver o número de mensagens enviadas e entregues, além de outras métricas. Consulte Obter métricas de uma conta para obter mais informações.

Dimensionamento

Na infraestrutura da Meta, a API de Nuvem faz o dimensionamento e aplica ajustes de modo automático para processar a carga de trabalho de acordo com o respectivo limite de volume aplicável (volume de mensagens e número de WABAs).

Privacidade e segurança de dados

Consulte nossa Visão geral sobre Privacidade e Segurança para obter mais informações.

Criptografia

Com a API de Nuvem, todas as mensagens do WhatsApp continuam sendo protegidas pela criptografia do protocolo Signal desde antes de deixarem o dispositivo. Isso significa que as mensagens com uma WABA são entregues com segurança ao destino escolhido pela empresa.

A API de Nuvem aplica técnicas padrão de criptografia da indústria para proteger dados em trânsito e em repouso. Ela usa a Graph API para enviar mensagens e Webhooks a fim de receber eventos. Ambos operam com HTTPS padrão da indústria protegido por TLS. Consulte o documento técnico Visão Geral da Criptografia para saber mais.

Consulte o documento técnico Visão Geral da Criptografia para saber mais.

Limites de volume de emparelhamento

Os números de telefone comerciais podem enviar 1 mensagem a cada 6 segundos ao mesmo número de telefone de usuário do WhatsApp (0,17 mensagem por segundo). Isso equivale a cerca de10 mensagens por minuto ou 600 mensagens por hora. Se você exceder esse limite, a API retornará o código de erro 131056 até que você volte a estar no limite.

Se necessário, você pode enviar até 45 mensagens em 6 segundos como uma série. Ao enviar uma série, você estará pegando emprestado do limite de volume de emparelhamento. Por isso, você não poderá enviar mais mensagens ao usuário até o término do tempo que normalmente levaria para enviar o número de mensagens da série. Por exemplo, leva cerca de 2 minutos para enviar 20 mensagens (não em série); portanto, ao enviar uma série de 20, você precisará esperar cerca de 2 minutos para enviar outra mensagem ao usuário.

Para não precisar calcular o tempo de espera: se o envio da mensagem falhar após uma série, recomendamos que você tente novamente em 4^X segundos, em que X = 0 e aumenta em 1 após cada tentativa com falha, até que a solicitação seja concluída.

Ferramentas

Gerenciador do WhatsApp

O Gerenciador do WhatsApp é nosso app para web que permite fazer o gerenciamento manual dos recursos do WhatsApp (como WABAs, números de telefone comercial e modelos) e facilita a visualização de insights, da classificação de qualidade ou de limites relacionados aos recursos. A maioria das funcionalidades oferecidas no Gerenciador do WhatsApp também está disponível via API, com algumas exceções.

Há diferentes formas de acessar o Gerenciador do WhatsApp. Todos os métodos consideram que você já concluiu as etapas da Introdução à API de Nuvem.

Via Meta Business Suite

  1. Entre no Meta Business Suite.
  2. Caso você tenha vários portfólios empresariais, use o menu suspenso à esquerda para selecionar a conta que possui ou pode acessar a WABA a ser carregada no Gerenciador do WhatsApp.
  3. No menu à esquerda, navegue até Contas > Contas do WhatsApp.
  4. Selecione a WABA.
  5. Na aba Resumo, clique no botão Gerenciador do WhatsApp.

Via Painel de Apps

  1. Acesse Meus apps.
  2. Selecione o app associado à WABA a ser carregada no Gerenciador do WhatsApp.
  3. No menu à esquerda, navegue até WhatsApp > Início rápido.
  4. Clique no bloco Informações da conta na seção WhatsApp Business.

Via URL

Você pode acessar diretamente a Visão Geral do Gerenciador do WhatsApp, que mostra todas as WABAs pertencentes a ou compartilhadas com determinado portfólio empresarial nesta URL:

https://business.facebook.com/wa/manage/home/

Por padrão, a visão geral carrega a última WABA que você criou ou a que recebeu acesso. Porém, é possível usar o menu suspenso à esquerda para selecionar o portfólio empresarial proprietário da WABA a ser acessada. Assim, você sairá da visão geral e precisará usar o menu à esquerda para navegar até Contas > Contas do WhatsApp e selecionar a WABA. Depois disso, acesse Configurações > Gerenciador do WhatsApp.

Caso você tenha vários portfólios empresariais, inclua a identificação da conta no fim da URL e adicione aos favoritos para facilitar o acesso:

https://business.facebook.com/wa/manage/home/?business_id=<META_BUSINESS_ACCOUNT_ID>

Postman

Confira a coleção do Postman sobre a API de Nuvem com perguntas comuns no nosso workspace da Plataforma do WhatsApp Business.