Configuração do WhatsApp Business

Com o WhatsApp conectado, as mensagens que os clientes enviam para o seu número do WhatsApp Business aparecem na Caixa de Entrada Social, e sua equipe (ou a Lora) pode respondê-las pelo NextCRM. O NextCRM usa a WhatsApp Business Platform (Cloud API) oficial da Meta. O aplicativo comum WhatsApp Business no celular não pode ser conectado.

Reserve cerca de 30-60 minutos para a primeira configuração. Você trabalha em dois lugares: Meta for Developers / configurações do negócio da Meta, e Implantação > Redes sociais no NextCRM.

O que o NextCRM suporta no WhatsApp

• Recebido: mensagens de texto, respostas de botões e legendas de imagens e documentos. Outros tipos de mensagem (por exemplo áudios ou figurinhas) aparecem como um marcador, como [audio]. Os arquivos de mídia em si não são baixados.
• Enviado: respostas em texto pela Caixa de Entrada Social, respostas da Lora no piloto automático e campanhas de WhatsApp.
• Não suportado: envio de modelos de mensagem aprovados (templates), confirmações de entrega e leitura, e importação de conversas anteriores à conexão.

Antes de começar

• Você precisa da função Administrador do Workspace ou Gerente de Vendas e de um plano com a Caixa de Entrada Social.
• Uma conta empresarial da Meta (portfólio empresarial) com acesso de administrador.
• Um número de telefone para o WhatsApp. Ele não pode estar em uso no aplicativo WhatsApp ou WhatsApp Business em um celular, ou você precisa migrá-lo para a plataforma antes. Para testes, a Meta oferece um número de teste gratuito.

Onde obter cada valor

Depois que você clica em Configurar no cartão do WhatsApp, o ícone (i) ao lado de cada campo mostra as mesmas informações.

Campo no NextCRM	Onde obter	Link
Segredo do aplicativo	Meta for Developers > My Apps > seu app > App settings > Basic > App secret (clique em Show). A Meta assina cada webhook com ele.	https://developers.facebook.com/apps
Token de acesso	Um token permanente de um usuário do sistema: configurações do negócio da Meta > Usuários > Usuários do sistema > Gerar novo token, com whatsapp_business_messaging e whatsapp_business_management.	https://business.facebook.com/settings/system-users
ID do número de telefone	O ID do número, não o número de telefone em si: Meta for Developers > seu app > WhatsApp > API Setup, mostrado abaixo do número de origem (From).	https://developers.facebook.com/apps
Token de verificação	Uma senha criada por você. Informe o mesmo valor em Meta for Developers > seu app > Webhooks (WhatsApp: WhatsApp > Configuration) como Verify token.	https://developers.facebook.com/apps
URL do Webhook	Aparece no cartão depois do primeiro salvamento. Cole-a sem alterações nas configurações de webhook do provedor como URL de callback.	https://developers.facebook.com/apps

Ordem de configuração: crie o app da Meta com WhatsApp (passo 1) > crie um token de acesso permanente (passo 2) > cole os valores e um token de verificação no NextCRM e salve (passo 3) > conecte o webhook na Meta (passo 4) > envie uma mensagem de teste (passo 5).

Passo 1: Criar o app da Meta com WhatsApp

1. Abra o Meta for Developers e crie um app. Escolha o tipo empresarial ou o caso de uso que oferece o WhatsApp e conecte-o ao seu portfólio empresarial.
2. Adicione o produto WhatsApp ao app.
3. Abra a página API Setup (Configuração da API; o nome pode variar um pouco) do WhatsApp. Lá você encontra:

• o Phone number ID (ID do número de telefone) do número de teste ou do seu próprio número,
• o WhatsApp Business Account ID (ID da conta do WhatsApp Business),
• um token de acesso temporário para testes.

4. Nas configurações básicas do app, copie o App secret (chave secreta do aplicativo). O NextCRM não precisa do App ID nem do WhatsApp Business Account ID.

Observação: Copie o Phone number ID, não o número de telefone em si. É um número longo que a Meta mostra ao lado ou abaixo do número de telefone.

Passo 2: Criar um token de acesso permanente

O token temporário da página API Setup para de funcionar depois de cerca de 24 horas. Para o uso diário, crie um token para um usuário do sistema:

1. Abra as configurações do negócio da Meta e vá em Usuários > Usuários do sistema (Users > System users).
2. Adicione um usuário do sistema (um usuário do sistema administrador serve) ou escolha um existente.
3. Atribua ativos ao usuário do sistema: o seu app e a sua conta do WhatsApp, com controle total.
4. Gere um novo token, escolha o seu app e, se a sua conta oferecer, a opção de token que nunca expira.
5. Selecione as permissões, por exemplo whatsapp_business_messaging e whatsapp_business_management.
6. Copie o token e guarde-o em segurança. A Meta mostra o token apenas uma vez.

Passo 3: Inserir os dados no NextCRM

::video[/help/videos/{lang}/social-connect.webm]{caption="Vídeo: o painel Como conectar e onde colar cada valor" captions="/help/videos/{lang}/social-connect.vtt" poster="/help/videos/{lang}/social-connect.jpg"}

1. Abra Implantação > Redes sociais (abrir a etapa Redes sociais), encontre o cartão WhatsApp e clique em Configurar. Os campos, o quadro Entrega de conector ao vivo e o painel Como conectar WhatsApp só aparecem depois desse clique.
2. Preencha os campos:

Campo no NextCRM	O que colar
Segredo do aplicativo	O App secret do seu app da Meta (obrigatório: a Meta assina cada webhook com ele)
Token de acesso	O token permanente do usuário do sistema do Passo 2 (obrigatório)
Token de verificação	Uma senha criada por você, por exemplo uma sequência longa e aleatória (obrigatório)
ID do número de telefone	O Phone number ID da página API Setup (obrigatório)

Os campos marcados com * são obrigatórios.

3. Clique em Salvar. A URL do Webhook na área Entrega de conector ao vivo agora termina com ?hook= e um código do seu workspace. O campo ID da conta do provedor mostra o ID do seu número de telefone.
4. Clique em Desativado no topo do cartão para que apareça Ativado. As mensagens só são aceitas enquanto o cartão estiver ativado.

Passo 4: Conectar o webhook na Meta

1. No seu app da Meta, abra WhatsApp > Configuration (Configuração) e edite o webhook.
2. Callback URL: cole a URL do Webhook do NextCRM sem alterações. Exemplo:

https://…/api/social/webhooks/whatsapp?hook=hook_EXEMPLO123

3. Verify token: informe o mesmo token de verificação que você salvou no NextCRM.
4. Clique em Verify and save (Verificar e salvar). A Meta chama o NextCRM, e o NextCRM confirma quando o token confere.
5. Nos campos do webhook, assine o campo messages.

Por que o Segredo do aplicativo importa: a Meta envia o token de verificação somente nessa verificação. Cada mensagem seguinte é assinada pela Meta com o seu Segredo do aplicativo, e o NextCRM rejeita mensagens cuja assinatura não confere; por isso o segredo precisa ser do mesmo app. Não adicione o token de verificação à URL de callback; URLs de callback antigas que terminam com &token=... continuam funcionando enquanto esse token conferir com o salvo.

Passo 5: Testar

1. Se você usa o número de teste, adicione o seu celular como destinatário permitido na página API Setup. O número de teste só conversa com uma pequena lista de números cadastrados ali.
2. Envie uma mensagem de WhatsApp do seu celular para o número da empresa.
3. Abra a Caixa de Entrada Social (abrir a Caixa de Entrada Social). A conversa aparece em WhatsApp, normalmente em poucos segundos.
4. Responda pelo NextCRM e confira se a resposta chega ao seu celular.

Número de teste ou número real: o número de teste é gratuito e bom para verificar a configuração, mas não pode ser usado com clientes reais. Para entrar em produção, adicione o seu próprio número no WhatsApp Manager, verifique-o e conclua o que a Meta pedir, como a verificação da empresa e a aprovação do nome de exibição. Depois substitua o ID do número de telefone no NextCRM e clique em Salvar.

A janela de atendimento de 24 horas

O WhatsApp só permite mensagens livres até 24 horas após a última mensagem do cliente. Depois disso, as empresas precisam usar modelos de mensagem aprovados previamente.

• Responda aos clientes na Caixa de Entrada Social em até 24 horas após a última mensagem deles.
• O NextCRM envia apenas texto, não modelos. Fora da janela, a Meta pode aceitar a mensagem, mas não entregá-la. O NextCRM não recebe relatórios de entrega, então a mensagem pode aparecer como enviada no NextCRM mesmo que o cliente nunca a receba.
• Se precisar falar com alguém depois de 24 horas, use um modelo em uma ferramenta da Meta ou peça para o cliente enviar uma mensagem primeiro.

Campanhas de WhatsApp

Em Campanhas > Nova Campanha > WhatsApp (abrir campanhas de WhatsApp) você envia uma mensagem de texto para os leads de um funil. O editor é o mesmo assistente de 4 etapas das campanhas de e-mail (Dados básicos, Público, Mensagem, Agendar e enviar).

O selo no topo mostra Conectado somente quando o cartão do WhatsApp está ativado, tem token de acesso e ID do número de telefone, e a Meta aceitou as credenciais. Caso contrário, ele mostra Não configurado, Salvo, não verificado ou Credenciais recusadas. Se o WhatsApp não estiver pronto quando você clicar em Agendar campanha ou Enviar campanha, aparece a janela Conexão necessária com Cancelar, Salvar como rascunho e Salvar rascunho e Abrir configurações do WhatsApp (usuários que não podem abrir as configurações veem, no lugar do último botão, uma dica para pedir a um administrador); a sua campanha é mantida como rascunho.

As campanhas usam o mesmo envio em texto das respostas, então a regra das 24 horas vale: as mensagens da campanha normalmente só chegam a leads que escreveram para o seu número de WhatsApp nas últimas 24 horas. Os leads precisam de um telefone em formato internacional, por exemplo +5511912345678. Números sem código do país são tratados como +1 (EUA/Canadá).

Erros comuns

• A Meta não consegue validar a URL de callback ou o verify token: o token de verificação na Meta não confere com o salvo no NextCRM, ou você copiou a URL do Webhook antes do primeiro salvamento (falta a parte ?hook=). Salve no NextCRM, copie a URL de novo e tente outra vez.
• A verificação funciona, mas nenhuma mensagem chega: confira se o Segredo do aplicativo do mesmo app está salvo (a Meta assina cada mensagem com ele), se o cartão está Ativado e se você assinou messages. Se mensagens de teste da Meta chegam, mas as reais não, verifique se o seu app está inscrito na sua conta do WhatsApp Business.
• O cartão mostra o chip Precisa de atenção: clique em Configurar para ver os detalhes. Normalmente falta o segredo do aplicativo, o token de acesso, o token de verificação ou o ID do número de telefone (cole-os e clique em Salvar), ou a Meta recusou o token de acesso.
• A resposta fica como "queued" com um aviso de que a entrega precisa de credenciais válidas: falta o token de acesso ou o ID do número de telefone, então nada foi enviado. Complete os dados e envie de novo.
• "Provider credentials are invalid, expired, or missing required permissions.": o token está errado, expirou (por exemplo o token de teste de 24 horas) ou não tem permissões do WhatsApp. Crie um token de usuário do sistema como no Passo 2.
• "Provider rejected the message with status 400.": a Meta não aceitou a mensagem, por exemplo porque o destinatário não está na lista do número de teste ou o formato do número está errado.
• "Provider rate limit reached. Please wait and try again.": mensagens demais em pouco tempo. Aguarde um momento.

Artigos relacionados

• Visão geral das conexões sociais
• Conectar o Facebook (Messenger e comentários da Página)
• Campanhas de e-mail
• Solução de problemas