Tema
Conectar WhatsApp via API Oficial (Meta)
A opção API Oficial (Meta) conecta o Columba ao seu número de WhatsApp usando a Cloud API da própria Meta. É uma alternativa ao QR Code para quem já opera (ou quer operar) na infraestrutura oficial da Meta.
O caminho principal é o botão Conectar com a Meta: você entra com sua conta Meta, escolhe ou cria o número num popup e pronto — sem copiar nem colar nenhuma credencial. Quem já tem um App Meta próprio e prefere gerenciar suas próprias credenciais pode usar o Modo avançado.
INFO
Se o botão Conectar com a Meta não aparecer no seu painel, a integração direta ainda não está habilitada no seu ambiente — use o Modo avançado com um App Meta próprio.
Pré-requisitos
Antes de começar, você precisa ter:
- Uma conta pessoal do Facebook ou Meta Business com acesso de administrador (ou permissão para criar) ao portfólio de negócios da empresa.
- Um número de telefone para o WhatsApp: um número novo, capaz de receber SMS ou ligação para verificação, ou um número que já está em uso no aplicativo WhatsApp Business — veja Coexistência: manter o número no app WhatsApp Business.
Conectar com a Meta
- Acesse Configurações → Conectores.
- Na seção WhatsApp, clique em Nova instância.
- Preencha o Nome da instância.
- Em Tipo de conexão, selecione API Oficial (Meta).
- Clique no botão Conectar com a Meta.
Um popup da Meta é aberto. Dentro dele:
- Entre com a conta Meta (Facebook ou Meta Business) que administra a empresa.
- Aceite os termos apresentados pela Meta.
- Escolha ou crie o portfólio de negócios e a conta do WhatsApp Business (WABA) que vai receber o número.
- Escolha o número: um número novo, verificado por SMS ou ligação na hora, ou um número que você já usa no aplicativo WhatsApp Business — a chamada coexistência, em que o app e o Columba dividem o mesmo número.
- Defina o nome de exibição do número: é o nome que os contatos veem na conversa.
Ao final, o popup fecha sozinho e o Columba conclui a conexão automaticamente: assina os webhooks da sua conta do WhatsApp Business e registra o número na Cloud API. Não há nenhuma credencial para copiar ou colar.
O que você ainda precisa fazer fora do Columba
Para enviar modelos de mensagem para números reais, a Meta exige um método de pagamento cadastrado na sua conta do WhatsApp Business (WABA) — sem isso, o envio de modelos não sai, mesmo com o número já conectado. Esse cadastro é feito fora do Columba, diretamente no WhatsApp Manager (business.facebook.com/wa/manage), na seção de faturamento (Billing) do seu portfólio de negócios.
Você não precisa ir atrás disso sozinho: a checklist Saúde do número, descrita a seguir, avisa quando o pagamento está faltando e traz um atalho direto para a tela certa da Meta.
Coexistência: manter o número no app WhatsApp Business
A coexistência é o caminho para quem hoje atende pelo celular — usando o QR Code ou o próprio aplicativo WhatsApp Business — e quer passar a usar a API Oficial sem abrir mão do app. Nesse modo, o mesmo número fica ativo nos dois lugares ao mesmo tempo: no aplicativo do celular e na Cloud API, dentro do Columba.
Quando usar
Se você já usa o número no aplicativo WhatsApp Business do celular (não confundir com o WhatsApp comum) e não quer perder o app — por exemplo, porque alguém da equipe continua respondendo por ele, ou porque você usa recursos do app que a API não tem —, a coexistência é o caminho certo. Se o número é novo ou você não precisa mais do app, use o fluxo normal ("Número novo").
Requisitos
- O aplicativo WhatsApp Business do celular precisa estar atualizado para uma versão recente.
- O número não pode estar cadastrado em outra API (Cloud API de outro provedor, ou já registrado em outra instância).
- Você precisa de uma conta Meta com acesso ao portfólio de negócios da empresa (o mesmo requisito do fluxo normal).
O que muda
- Dispositivos vinculados ao número — como sessões do WhatsApp Web — são desconectados quando a coexistência é ativada.
- Grupos, chamadas de voz/vídeo, catálogo e status continuam funcionando só pelo aplicativo: a API Oficial (e por isso o Columba) não têm acesso a eles.
- A Meta limita o envio neste modo a um teto de 20 mensagens por segundo.
- É preciso abrir o aplicativo no celular de tempos em tempos. Se o WhatsApp Business ficar muito tempo sem ser aberto, a ligação com a API pode expirar.
Como conectar
- No passo Conectar com a Meta, quando o popup pedir para escolher o número, selecione a opção "Já uso este número no app WhatsApp Business" em vez de "Número novo".
- A Meta mostra um QR Code dentro do próprio popup. Abra o WhatsApp Business no celular do número que você quer conectar e escaneie esse QR Code (o mesmo caminho usado para vincular um aparelho).
- O app pergunta se você autoriza compartilhar o histórico de contatos e conversas com a API. Aceitar é o que permite ao Columba importar o que já existe — recusar não impede a conexão, só limita o que é trazido (veja a seguir).
O que é importado
Depois da conexão, o Columba pede à Meta a sincronização de contatos e de até 180 dias de conversas. A importação acontece em fases (mais recente primeiro) e pode levar algum tempo — o progresso aparece tanto no card da instância quanto na checklist Saúde do número.
Se você recusar o compartilhamento de histórico no aplicativo, o Columba não importa nada do que já existia: só as conversas novas, a partir da conexão, passam a aparecer no Chat.
Como aparecem as mensagens enviadas pelo celular
Mensagens que alguém enviar pelo aplicativo (e não pelo Columba) depois da coexistência ativada também aparecem no Chat, mas com um sinal claro: o remetente mostrado é "App WhatsApp Business", em vez do nome de um atendente.
Essas mensagens não abrem nem renovam a janela de atendimento de 24 horas da API, e não disparam automações (fluxos ou IA) — elas só ficam registradas no histórico da conversa.
INFO
A janela de 24 horas e a exigência de modelos aprovados continuam valendo normalmente para tudo que sai pelo Columba. A coexistência muda apenas o que acontece quando alguém usa o aplicativo diretamente — veja Janela de 24 horas e modelos de mensagem.
Saúde do número
Assim que a conexão termina, o Columba abre automaticamente a checklist Saúde do número — e você pode reabri-la a qualquer momento pelo botão Saúde do número no card da instância, em Configurações → Conectores.
A checklist consulta a Meta em tempo real e mostra, no topo, se o número pode enviar mensagens: Sim, Limitado ou Bloqueado, além de quando foi a última verificação ("Verificado há X"). Abaixo, cada item mostra um status:
| Item | O que verifica | O que significa um alerta |
|---|---|---|
| Pagamento | Se há um método de pagamento cadastrado na WABA | Sem cartão cadastrado, a Meta bloqueia o envio de modelos para números reais |
| Nome de exibição | Se o nome do número foi aprovado pela Meta | Nome pendente de revisão ou recusado pela Meta — pode ser preciso escolher outro nome |
| Verificação da empresa | Se o portfólio de negócios foi verificado pela Meta | Sem verificação, a Meta limita o envio a 250 contatos novos por dia |
| Registro | Se o número está registrado corretamente na Cloud API | Número ainda não registrado — geralmente se resolve sozinho ou com Verificar de novo |
| Qualidade | A avaliação de qualidade do número pela Meta (verde, amarela, vermelha) | Qualidade amarela ou vermelha reduz ou bloqueia o envio de mensagens |
| Limite de mensagens | O teto atual de conversas iniciadas por dia (informativo) | Não bloqueia nada — apenas mostra a faixa atual liberada pela Meta |
| Webhook | Se a Meta está assinada para enviar eventos deste número ao Columba | Sem a assinatura, mensagens recebidas não chegam ao Chat |
| Coexistência (só em números conectados assim) | O andamento da importação de contatos e histórico vindos do app, e se o número continua vinculado ao aplicativo | Importação de histórico recusada no app, ou o número não está mais ligado ao WhatsApp Business |
Quando um item precisa de ação, ele traz um botão que leva direto à tela certa da Meta (por exemplo, cadastrar pagamento ou verificar a empresa) ou, no caso do webhook, o botão Reassinar, que resolve a assinatura sem sair do Columba.
Clique em Verificar de novo a qualquer momento para atualizar os status. No card da instância, em Configurações → Conectores, um selo colorido (verde, amarelo ou vermelho) resume a saúde do número sem precisar abrir a checklist.
Configurações da instância
Pelo botão Configurações no card da instância você altera o nome e liga a opção Assinar com o nome do atendente (desligada por padrão): toda mensagem enviada pelo chat por este número sai com o nome de quem atendeu em negrito na primeira linha. Detalhes em Enviar mensagens.
Modo avançado: usar seu próprio App Meta
Esta seção é para quem já tem um App Meta próprio no painel de desenvolvedores da Meta e prefere gerenciar suas próprias credenciais, em vez de usar o botão Conectar com a Meta. É o mesmo resultado final — um número conectado à Cloud API —, só que com mais passos manuais do seu lado.
INFO
Nesse modo, o Columba não cria nem gerencia o app Meta por você — a configuração inicial na plataforma da Meta é de sua responsabilidade.
Pré-requisitos do modo avançado
Antes de começar, você precisa ter, na plataforma da Meta:
- Uma conta Meta Business.
- Um app criado no painel de desenvolvedores da Meta, com o produto WhatsApp configurado.
- Um número de telefone cadastrado na Cloud API desse app.
Criar a instância no Columba
- Acesse Configurações → Conectores.
- Na seção WhatsApp, clique em Nova instância.
- Preencha o Nome da instância.
- Em Tipo de conexão, selecione API Oficial (Meta).
- Clique no link discreto Já tenho App Meta próprio (avançado).
- Preencha os cinco campos de credenciais (veja abaixo onde encontrar cada um).
- Clique em Criar instância.
Onde encontrar cada credencial no painel da Meta
| Campo no Columba | Onde encontrar na Meta |
|---|---|
| Phone Number ID | No app Meta, em WhatsApp → API Setup (ou Configuration), na seção do número de telefone cadastrado. |
| WhatsApp Business Account ID (WABA) | Na mesma tela de configuração do WhatsApp, junto aos dados da sua conta comercial (WhatsApp Business Account). |
| Access Token (permanente / System User) | Gerado no Meta Business Suite, através de um usuário do sistema (System User) com as permissões whatsapp_business_messaging (enviar e receber mensagens) e whatsapp_business_management (gerenciar e sincronizar modelos de mensagem). Use um token permanente — tokens temporários de teste expiram e interrompem a conexão. |
| App Secret | Nas configurações do app, em Configurações básicas do app (App Settings → Basic). |
| Verify Token | Um texto que você mesmo define. Não vem da Meta — você escolhe uma palavra ou frase e usa o mesmo valor ao configurar o webhook (próximo passo). |
Cuidado
O Access Token e o App Secret dão acesso ao envio de mensagens em nome do seu número. Trate-os como senhas: não compartilhe fora do painel do Columba.
Configurar o webhook na Meta
Depois de criar a instância com sucesso, o Columba mostra a janela Configure o webhook na Meta, com a Callback URL desta instância pronta para copiar.
- Copie a Callback URL exibida na janela (ou, depois, pelo botão Configurações no card da instância).
- No painel do seu app Meta, acesse WhatsApp → Configuration → Webhooks.
- Cole a Callback URL no campo de URL de retorno de chamada (callback).
- Informe o mesmo Verify Token que você definiu na criação da instância.
- Assine (subscribe) o campo
messages.
Sem esse passo, o número fica cadastrado no Columba, mas as mensagens recebidas não chegam ao seu Chat.
INFO
As instâncias criadas no modo avançado também mostram a checklist Saúde do número, incluindo o item de webhook (que, nesse modo, é a assinatura que você configurou manualmente acima).
Janela de 24 horas e modelos de mensagem
Na API Oficial, a Meta só libera o envio de texto livre (e de mídia) para um contato que escreveu para a sua empresa nas últimas 24 horas — a chamada janela de atendimento. Fora dessa janela, a única mensagem que pode ser enviada é um modelo aprovado pela Meta (também chamado de template).
Essa regra é exclusiva da API Oficial. No QR Code, que usa a mesma conexão do WhatsApp do celular, não existe janela de 24 horas — o texto livre funciona sempre, para qualquer contato.
INFO
No Chat, quando a janela está fechada, uma faixa "Fora da janela de 24 h" substitui o campo de texto, com o botão Enviar modelo. Veja como funciona em Enviar um modelo (API Oficial).
Onde criar modelos de mensagem
Modelos são criados e aprovados pela própria Meta, fora do Columba, no WhatsApp Manager: business.facebook.com/wa/manage/message-templates. O Columba não cria modelos — ele lista os que já foram aprovados na sua conta e permite enviá-los pelo Chat.
Categorias e cobrança
Todo modelo pertence a uma categoria, definida pela Meta no momento da criação:
| Categoria | Uso típico | Cobrança |
|---|---|---|
| Utilitário | Atualizações sobre uma interação já iniciada (confirmação de pedido, lembrete de agendamento) | Sem custo dentro da janela de 24 h; cobrado pela Meta fora dela |
| Marketing | Promoções, novidades e ofertas | Sempre cobrado pela Meta, mesmo dentro da janela, e exige consentimento prévio do contato |
| Autenticação | Códigos de verificação | Sempre cobrado pela Meta |
Os valores cobrados pela Meta variam por país e mudam com frequência — consulte a tabela oficial da Meta para preços atualizados. O Columba mostra o aviso de cobrança por categoria na hora de enviar, mas não exibe preços.
Acompanhar o que a Meta cobra
No card da instância, em Configurações → Conectores, uma linha mostra o consumo do mês atual: "Este mês: N cobradas (~US$ X) · N grátis". O link Ver detalhes abre um painel com os últimos 3 meses, mês a mês.
Estimativa, não fatura
O valor em dólares é uma estimativa, calculada com as tarifas públicas da Meta para o Brasil (Marketing, Utilitário fora da janela e Autenticação). A fatura da Meta na sua conta comercial é sempre a referência oficial — o Columba não a substitui, e as tarifas reais podem variar por faixa de volume.
Contam como grátis:
- texto livre e modelos de Utilitário enviados dentro da janela de 24 horas;
- mensagens enviadas dentro do ponto de entrada de anúncio (as 72 horas seguintes a um clique em anúncio que abre o WhatsApp, quando aplicável).
O Columba soma uma mensagem ao consumo do mês a partir da confirmação de entrega pela Meta — não no momento do envio —, e cada mensagem entra na contagem uma única vez.
Sincronizar modelos com o Columba
O card da instância, em Configurações → Conectores, mostra quantos modelos aprovados estão disponíveis e há quanto tempo foi a última sincronização.
- Clique em Sincronizar para buscar a lista mais recente de modelos direto da Meta.
- Clique em Gerenciar no WhatsApp Manager para abrir a tela da Meta onde os modelos são criados e editados.
O Columba também sincroniza sozinho ao criar a instância e sempre que a Meta avisa que um modelo mudou de status.
Pré-requisitos para enviar modelos
Além dos pré-requisitos de conexão descritos acima, para enviar modelos de mensagem para números reais você também precisa de:
- Método de pagamento cadastrado na WABA — sem um cartão ou outra forma de pagamento cadastrada na sua WhatsApp Business Account, a Meta não libera o envio de modelos.
- Token com a permissão
whatsapp_business_management— além da permissão de envio de mensagens, o Access Token do System User precisa também dessa permissão para o Columba conseguir listar e sincronizar os modelos. Se você cadastrou o token antes de saber disso, gere um token novo no Meta Business Suite já com as duas permissões e atualize a credencial em Configurações.
Token sem a permissão certa
Sem a permissão whatsapp_business_management, o card da instância mostra um aviso e a lista de modelos aparece vazia, mesmo que existam modelos aprovados na sua conta.