Integração Meta — WhatsApp Cloud API

Administrador 8 min de leitura

É a tela onde o SNDesk é ligado à conta oficial do WhatsApp da empresa na Meta. Aqui ficam as credenciais do aplicativo, o número usado no atendimento e o webhook que traz as mensagens para dentro do sistema. A tela também permite testar a ligação, registrar o número, trocar o nome que o cliente vê no WhatsApp, ligar as chamadas de voz e acompanhar os avisos e erros enviados pela Meta.

Antes de começar

A tela é exclusiva de usuários com nível de administrador. As informações pedidas aqui são criadas na Meta — o roteiro completo do lado da Meta (portfólio de negócios, aplicativo, conta do WhatsApp Business, número e usuário do sistema) está em WhatsApp Integrado › Passo a passo dentro da Meta.

Os quatro passos da configuração

O formulário segue a ordem em que as informações são obtidas na Meta. Preencha os quatro blocos e clique em Salvar configuração antes de usar as ações da tela.

1. Credenciais do app

App ID e App Secret ficam em Configurações do app › Básico no Meta for Developers. O App Secret é necessário para o SNDesk configurar o webhook sozinho. A Versão da Graph API só deve ser alterada com orientação do suporte.

2. Conta e número

WABA ID (a conta do WhatsApp Business), o número com DDI e o ID do número (Phone Number ID), todos em WhatsApp › Configuração da API. O campo Nome verificado é só leitura: mostra o nome que a Meta tem registrado para o número.

3. Token de acesso

Use um token permanente de usuário do sistema com as permissões whatsapp_business_management e whatsapp_business_messaging. Token temporário de teste expira em poucas horas e derruba o envio de mensagens.

4. Webhook

A URL de callback já vem preenchida com o endereço do seu SNDesk. Gere ou informe o Webhook Token (verify token) e guarde-o: ele valida a ligação com a Meta. Abaixo do campo a tela lista os eventos que o SNDesk assina.

Ações da tela

Depois de salvar, use as ações na ordem abaixo. O retorno de cada uma aparece logo abaixo dos botões.

Botão O que faz
Testar conexão Confere as credenciais e o número na Meta e atualiza o nome verificado exibido na tela.
Validar token Mostra se o token ainda é válido e se tem as permissões que o SNDesk precisa.
Configurar webhook Inscreve o aplicativo e a conta para enviarem os eventos ao SNDesk. Repita sempre que um recurso novo pedir um evento a mais (por exemplo, chamadas de voz ou troca do nome de exibição).
Registrar número Registra o número na Cloud API com o PIN de 6 dígitos da verificação em duas etapas. Necessário na ativação e depois que a Meta aprova um novo nome de exibição.

Webhook deste subdomínio

Quando o mesmo aplicativo da Meta atende mais de um SNDesk, use Status do webhook para ver para onde os eventos estão indo, Usar webhook deste subdomínio para que esta conta entregue os eventos na URL desta tela, e Remover assinatura para desligar a entrega.

Nome de exibição do número

É o nome que o cliente vê no WhatsApp quando conversa com a empresa. A troca é feita pela Meta, que analisa o nome antes de liberar; o SNDesk envia o pedido e acompanha o andamento, sem precisar entrar no WhatsApp Manager.

Nome atual

O nome em uso hoje e o status dele na Meta.

Troca solicitada

O nome pedido, se houver, e o andamento da análise.

Novo nome

Campo para digitar o nome e o botão Solicitar troca.

Como trocar

  1. Digite o novo nome no campo Novo nome e clique em Solicitar troca. Confirme o envio.
  2. A troca aparece como Em análise. Use Atualizar status para consultar a Meta; a decisão também chega na aba Alertas da tela.
  3. Quando o status ficar Aprovado, clique em Registrar número informando o PIN de 6 dígitos. Só depois disso o novo nome entra em uso.
Status Significado
Em análiseA Meta está avaliando o nome pedido.
AprovadoO nome foi aceito. Falta registrar o número de novo com o PIN.
Liberado sem análiseO nome pode ser usado sem passar pela análise.
RecusadoA Meta não aceitou o nome. Ajuste e peça de novo.
Expirado / Sem certificadoO número precisa de atenção na conta da Meta antes de ser usado na API — procure o suporte.

Regras da Meta para o nome

  • Deve ter relação com a empresa e seguir as políticas comerciais do WhatsApp.
  • Pelo menos 3 caracteres.
  • Não pode ser um endereço de site (por exemplo, www.suaempresa.com.br).
  • No máximo 10 trocas a cada 30 dias.

Registre o número em até 14 dias depois da aprovação

O novo nome só passa a valer depois que o número é registrado de novo com o PIN. Registrar antes da aprovação não tem efeito. Se passarem 14 dias da aprovação sem o registro, o nome volta para análise.

Para que a decisão da Meta apareça na aba Alertas, clique uma vez em Configurar webhook depois que este recurso for liberado no seu SNDesk.

Números da conta

Buscar números na Meta lista todos os números de WhatsApp que o token enxerga nas WABAs da conta. Para cada um você marca se ele fica Liberado (pode ser escolhido para iniciar uma conversa na Nova conversa), qual é o Principal (vira o número da configuração: chatbot, fila, avisos e todo envio automático saem por ele) e um Apelido curto para o operador. O limite de números liberados é do plano. Clientes que escrevem para um número não liberado continuam sendo atendidos normalmente, e a resposta sai sempre pelo número em que o cliente escreveu.

Template inicial por número

Quando a janela de 24 horas fecha, a resposta do operador vai como template. Template pertence à WABA, não à conta: o template inicial da configuração só existe na WABA dela. Se um número fica em outra WABA, escolha na coluna Template inicial um dos templates aprovados dessa WABA: a lista de cada número traz só os templates da WABA dele, e os que servem (uma variável no corpo, onde entra a mensagem do operador) vêm primeiro; os outros aparecem apagados com o motivo. A opção Automático mostra qual template será usado: o da configuração se ele estiver aprovado na WABA do número; senão, um template aprovado simples dessa WABA. Se a lista ficar em vermelho, a WABA não tem nenhum template que sirva: crie um na Meta e clique em Buscar números na Meta para a lista ser lida de novo. Sem isso, a resposta fora da janela de 24 horas falha com o código 132001 (aba Erros).

Chamadas de voz

Os botões Status, Habilitar e Desabilitar ligam o botão de ligação no perfil do número. A Meta exige limite de envio de pelo menos 2.000 mensagens por dia e o evento de chamadas assinado no webhook — por isso, clique em Configurar webhook de novo depois de habilitar. Ligar para o cliente depende da permissão dele, pedida pelo operador no chat.

Alertas, Testes e Erros

Alertas

Avisos enviados pela Meta: queda de qualidade do número, revisão da conta, status e qualidade de templates e a decisão sobre a troca do nome de exibição.

Testes

Uma bateria de verificações da integração: credenciais, token, número, conta, webhook, templates, chamadas de voz e recebimento de mensagens.

Erros

O registro central dos erros devolvidos pela Meta (envios, mídia, chamadas, chatbot) e das falhas de entrega. Filtre por Origem (o fluxo que gerou o erro), por Código da Meta (ex.: 131047 — janela de 24 h fechada), por texto (destino, mensagem ou número da conversa) ou só os não lidos; a lista vem em páginas de 50. Use Marcar como lidos depois de tratar — com um filtro ativo, o botão marca só o que está filtrado.

Próximo recomendado

Com a integração ligada, confira o funcionamento do canal no atendimento e os recursos de administração das conversas.