API oficial do WhatsApp Business
Conecte uma conta oficial da WhatsApp Business Platform da Meta (Cloud API) ao cshub para enviar transmissões oficiais com modelos, configurar respostas automáticas e manter o número do seu negócio em boa situação com a Meta. Todos os chats para um número WABA chegam ao Chat CRM, junto com os seus outros canais.
No cshub, uma conta WABA (WhatsApp Business Account) pode ter vários números de telefone. Cada número é chamado de device. Na página da conta, você gerencia quatro coisas: devices, modelos, transmissões e chatbots.
Você precisa da WABA ou escanear um QR já basta?
A WABA é para você se precisa de alto volume, modelos aprovados pela Meta ou do selo verde. Para começar rápido, sem verificação da Meta, use o WhatsApp (escanear QR). A comparação está em Sobre os canais.
Antes de começar
- Uma conta Meta Business (Business Manager) que você administra.
- Um número de telefone que não esteja registrado em outra configuração da WhatsApp Business Platform — ou, se você quiser continuar usando o número no app WhatsApp Business do celular, escolha o modo Coexistence ao conectar.
- Para o caminho Manual: um App da Meta com um Usuário do Sistema e um token de acesso de longa duração.
Lista de contas WABA
Abra Conectar WhatsApp na barra lateral e depois a aba API oficial do WhatsApp Business.
Cada cartão mostra o nome da conta, o ID do WABA, o método de conexão (Cadastro Embutido ou Manual), a quantidade de devices e de modelos e o App ID da Meta. O botão ⋮ do cartão abre um menu:
| Menu | O que faz |
|---|---|
| Ver Detalhes | Abre a página da conta (o mesmo que clicar no cartão) |
| Sincronizar da Meta | Busca os números e modelos mais recentes na Meta e resume o resultado, por exemplo quantos devices novos foram encontrados, ou que não houve mudanças vindas da Meta |
| Editar Credenciais | Substitui o App Secret e o token de acesso desta conta |
| Excluir | Remove a conta WABA do cshub (veja Excluir uma conta WABA) |
Conectar uma conta WABA
Clique em Conectar WABA. Há dois caminhos: Inscrição Embutida (o mais fácil) ou Manual.
Opção 1 — Inscrição Embutida (login com o Facebook)
- Se o seu número ainda é usado no app WhatsApp Business do celular e você quer continuar assim, marque Eu também uso o WA Business app no celular (Coexistence) (veja Coexistence).
- Clique em Conectar via Facebook. Uma janela do Facebook se abre.
- Faça login e escolha o seu Business Manager → Conta do WhatsApp Business → número de telefone.
- Quando a janela terminar, preencha Nome de Exibição (opcional) — um nome para diferenciar as contas no painel, por exemplo WABA Loja Principal. Se ficar vazio, é usado o ID do WABA.
- Clique em Finalizar Conexão. Quer escolher de novo? Clique em Cancelar e Escolher Novamente.
O cshub troca automaticamente a permissão do Facebook por um token de longa duração (60 dias) e conecta o webhook, para que as mensagens recebidas cheguem direto ao Chat CRM.
A janela não aparece?
Bloqueadores de anúncios ou de pop-ups podem impedir a janela do Facebook. Permita pop-ups para o cshub e tente de novo. Se ainda assim não funcionar, use a aba Manual.
Opção 2 — Manual (credenciais da Cloud API)
Para contas WABA que já estão ativas e quando você tem acesso ao Meta Developers Console.
Encontre os valores em Meta Developers Console → seu App → WhatsApp → API Setup.
| Campo | Observações |
|---|---|
| ID do App Meta * | O número de 15 a 16 dígitos do seu App da Meta |
| ID do WABA * | O ID da Conta do WhatsApp Business (só números) |
| Segredo do App Meta * | No mínimo 10 caracteres. Fica guardado criptografado |
| Token de Acesso do Usuário do Sistema * | Um token de Usuário do Sistema de longa duração, com no mínimo 20 caracteres. É verificado com a Meta quando você salva |
| Nome de Exibição | O nome no painel. Se ficar vazio, usa o ID do WABA |
| Agentes responsáveis * | Pelo menos 1 membro da equipe. Eles são atribuídos automaticamente a todos os números sincronizados da Meta |
Clique em Conectar WABA.
Se a conexão falhar
| Mensagem | Causa e solução |
|---|---|
| Token Meta inválido | O token expirou ou o App Secret não corresponde ao App ID. Gere um novo token no Meta Business Manager |
| Falha ao inscrever webhook | A conta foi conectada, mas o webhook não está ativo. Abra os detalhes da conta e clique em Reconectar |
| Nenhum número WhatsApp | O WABA ainda não tem número de telefone. Adicione um em Meta Business Manager → WhatsApp Manager → Números de telefone e tente de novo |
| Falha no Embedded Signup | O código do Facebook expirou ou já foi usado. Refaça a janela ou use o Manual |
| WABA já conectado | Este ID do WABA já está em uso em outra conta do cshub. Remova-o lá primeiro ou fale com o suporte |
| Limite do plano atingido | O seu plano chegou ao limite de contas WABA. Veja Faturação e planos |
Modo Coexistence
O Coexistence permite que um número seja usado ao mesmo tempo no app WhatsApp Business do celular e no cshub:
- As mensagens dos clientes chegam no celular e no painel do cshub.
- As mensagens que você envia manualmente pelo celular ficam registradas no histórico do painel, então a sua equipe sabe que o cliente já foi atendido.
- O cshub continua podendo enviar transmissões com modelos e respostas automáticas.
É ideal para pequenos negócios em que o dono ou o atendimento ainda respondem bastante pelo celular, mas querem começar a usar as transmissões e o CRM. As contas nesse modo exibem o selo Coexistence na página de detalhes.
Página de detalhes da conta
Clique no cartão de uma conta (ou em ⋮ → Ver Detalhes).
| Seção | O que tem |
|---|---|
| Status do Webhook | Uma caixa verde Webhook connected significa que as mensagens recebidas e os status de entrega da Meta são encaminhados automaticamente. Se aparecer Webhook not connected yet, clique em Reconectar |
| Show manual webhook setup | Mostra a URL do Webhook e o Verificar Token para colar manualmente em Meta Developers → App → WhatsApp → Configuration, caso a configuração automática não tenha funcionado |
| Manage this account | Atalhos para Devices, Modelos, Transmissões e Chatbots |
| Informações da Conta | ID do App Meta, ID do WABA (dá para copiar), método de conexão e as datas de criação e da última atualização |
Webhook não conectado = nenhuma mensagem recebida
Enquanto o webhook não estiver conectado, os chats dos clientes para o número WABA não chegam ao cshub. Se Reconectar continuar falhando, confira se o token de acesso tem as permissões whatsapp_business_management e whatsapp_business_messaging.
Devices (números)
O cartão Devices abre a lista de números desta conta.
Os números são adicionados automaticamente durante a Inscrição Embutida, ou quando você clica em Sincronizar Meta depois de adicionar um número no Meta Business Manager. Status dos devices:
| Status | Significado |
|---|---|
| Ativo | O número pode enviar e receber mensagens |
| Inativo | O número ainda não pode ser usado |
| Bloqueado pela Meta | A Meta restringiu este número. Confira a Classificação de Qualidade e as suas práticas de envio |
Clique no ícone de detalhes na linha de um número para abrir as configurações dele. São três abas.
Aba Token e Info
O Status da Meta é buscado na última sincronização:
| Item | Significado |
|---|---|
| Exibir Telefone | O número como os clientes o veem |
| Nome Verificado | O nome do negócio aprovado pela Meta |
| Classificação de Qualidade | A saúde do número: Verde (saudável), Amarelo (atenção) ou Vermelho (limitado). Cai quando muitos clientes bloqueiam ou denunciam as suas mensagens |
| Limite de Mensagens | Quantas conversas a Meta deixa você iniciar por dia |
| Webhook | Inscrito significa que as mensagens recebidas são encaminhadas ao cshub |
| Platform Type / Verificação | O tipo de plataforma e o status de verificação na Meta |
Só preencha Sobrescrever Access Token se este número tiver um Usuário do Sistema próprio. Normalmente o token é herdado da conta, então deixe vazio.
Aba Resposta Automática
| Configuração | Observações |
|---|---|
| Método de Auto-Reply | Sem resposta automática, Respostas por palavra-chave, Agente IA ou Palavras-chave primeiro, depois IA. Para os dois últimos, escolha o Agente IA |
| Marcar chat como lido antes de auto-responder | Os clientes veem o check azul antes de a resposta automática chegar |
| Ativar auto-reply apenas em determinados dias | Escolha os dias ativos |
| Ativar auto-reply apenas em determinados horários | Defina um horário de início e de fim (por exemplo, 09:00) |
| Agentes | Os membros da equipe de atendimento que recebem os chats depois que a resposta automática termina, com o respectivo nível de acesso |
| Prompt Adicional (opcional) | Instruções extras para o Agente IA, só para este número |
| Escalonamento (SLA) | Avisa os agentes quando um chat espera demais por uma pessoa |
| Método de atribuição de agente | Como os novos chats são entregues à sua equipe (veja Sobre os canais) |
Clique em Salvar Configuração. As palavras-chave para números WABA são criadas em Chatbots WABA.
Aba Saudação
A saudação é uma mensagem automática de boas-vindas enviada quando um cliente escreve depois de 24 horas sem nenhuma interação. Ative Ativar auto-reply de saudação e escolha o Tipo da Mensagem de Saudação:
- Texto livre — escreva você mesmo, até 1.024 caracteres.
- Template WhatsApp — escolha um modelo Aprovado.
Clique em Salvar Saudação.
Modelos de mensagem
A Meta exige um modelo aprovado para iniciar uma conversa com um cliente (por exemplo, em uma transmissão) ou para mandar mensagem fora da janela de 24 horas depois da última resposta dele.
Já tem modelos no Meta Business Manager? Clique em Sync da Meta para trazê-los. Os modelos excluídos do lado da Meta ficam marcados como Excluído.
| Status do modelo | Significado |
|---|---|
| Aguardando revisão | Acabou de ser enviado e a Meta está analisando |
| Aprovado | Pronto para transmissões, chatbots e saudações |
| Rejeitado | Não passou na análise. Corrija o conteúdo e crie um novo modelo |
| Excluído | Removido do lado da Meta |
Criar um modelo
Clique em Adicionar Template. O Preview WhatsApp à direita é atualizado enquanto você digita.
| Campo | Observações |
|---|---|
| Nome do Template | Letras minúsculas, números e sublinhados, por exemplo order_confirmation. Até 100 caracteres |
| Idioma | O idioma do modelo, por exemplo Indonésio (id) ou Inglês (en) |
| Categoria | Utility (transacional) para atualizações de pedido/conta, Marketing (promocional) para promoções, Autenticação (OTP) para códigos de verificação |
| Tipo de Header | Texto (sem header), Imagem (JPG/PNG até 16 MB), Vídeo (MP4 até 16 MB) ou Documento (PDF até 100 MB). Para cabeçalhos de mídia, envie o arquivo |
| Conteúdo do Body | A mensagem, até 1.098 caracteres. Use 1, 2 para as partes que mudam a cada cliente |
| Variáveis de exemplo | Aparecem automaticamente para cada |
| Footer (opcional) | Um texto pequeno abaixo da mensagem, até 60 caracteres |
| Botões (opcional, máx. 10) | Resposta Rápida, URL, Telefone ou Copiar código |
Clique em Criar Template. O modelo fica em Aguardando revisão até a Meta aprová-lo.
O nome e o idioma não podem ser alterados
Depois de criado, o nome e o idioma de um modelo ficam travados. Se você precisar de outro nome ou idioma, crie um novo modelo.
Transmissões WABA
Envie um modelo Aprovado para muitos contatos de uma vez.
Clique em Criar Broadcast:
| Campo | Observações |
|---|---|
| Nome da Campanha | Um nome para reconhecer a transmissão, por exemplo Promo Eid 2026 |
| Agendamento de Envio | Data e hora do envio; precisa estar no futuro |
| Template (apenas APPROVED) | Só os modelos Aprovados aparecem na lista |
| Devices de Envio | Pelo menos 1 número WABA |
| Filtro de Audiência (opcional) | Filtre os contatos por Categoria, Cidade e Distrito. Vazio = todos os contatos |
| Modo de Rotação | Sequence (devices em ordem) — usa o número 1 até terminar e depois o número 2; Spin (round-robin) — alterna entre os números; Aleatório — um número aleatório para cada contato |
| Delay (segundos) | A pausa entre uma mensagem e outra |
| Limite Entre Descansos | Depois dessa quantidade de mensagens, o envio faz uma pausa para descansar |
| Duração do Descanso (segundos) | Quanto tempo dura esse descanso |
| Metadata JSON | Os valores das variáveis {"1": "Hello "}. O botão JSON Bonito organiza o texto |
| Arquivo Header Override (opcional) | Só se o modelo tiver um cabeçalho de mídia e você quiser substituir o arquivo padrão dele |
Clique em Agendar Broadcast. Status da transmissão: Aguardando agenda, Em execução, Concluído ou Interrompido. Uma transmissão só pode ser editada enquanto ainda está pendente. A página de detalhes mostra uma barra de progresso (pendentes / enviadas / com falha) e o botão Atualizar Progresso.
Para transmissões pelo WhatsApp por QR, veja Transmissão no WhatsApp.
Chatbots WABA
Respostas automáticas por palavra-chave só para os números desta conta WABA.
Clique em Adicionar Chatbot:
| Campo | Observações |
|---|---|
| Palavra-chave * | A palavra que dispara a resposta. É comparada exatamente com a mensagem recebida, sem diferenciar maiúsculas e minúsculas |
| Modo de Resposta * | Texto livre — envia um texto simples; Template WhatsApp — envia um modelo Aprovado |
| Mensagem de Resposta * | No modo texto, até 4.096 caracteres |
| Template WABA | No modo modelo |
| Devices WABA * | Pelo menos 1 número. O chatbot só dispara nos números selecionados |
| Metadata JSON / Arquivo Header | Opcionais, para preencher as variáveis do modelo e substituir o arquivo de um cabeçalho de mídia |
Para o chatbot ser usado, defina o Método de Auto-Reply daquele número como Respostas por palavra-chave ou Palavras-chave primeiro, depois IA na aba Resposta Automática.
Substituir as credenciais
O token expirou ou o App Secret foi trocado? Abra Editar Credenciais na página de detalhes.
Os campos ficam vazios de propósito — as credenciais antigas nunca são exibidas. Informe o novo Segredo do App Meta e o novo Token de Acesso do Usuário do Sistema e clique em Salvar Novas Credenciais. O cshub verifica o token com a Meta e reconecta o webhook.
Excluir uma conta WABA
Escolha Excluir na página de detalhes ou no menu do cartão.
- Sem histórico de chats: a conta é excluída e o webhook da Meta é desconectado automaticamente.
- Com histórico: escolha Transferir histórico para outra conta WABA (o histórico e os devices são transferidos e depois a conta é excluída) ou Excluir à força + histórico (permanente, não pode ser recuperado).
Dicas
- Mantenha a Classificação de Qualidade verde. Envie transmissões só para contatos que querem receber notícias suas e dê a eles uma forma de sair da lista.
- Escolha uma categoria de modelo honesta. Modelos promocionais cadastrados como Utility costumam ser rejeitados ou recategorizados pela Meta.
- Sincronize depois de mudar algo na Meta. Adicionou um número ou modelo no Business Manager? Clique em Sincronizar Meta para o cshub ficar atualizado.
Outros problemas são tratados em Solução de problemas.