WhatsApp (Official)

Essa conexão usa a WhatsApp Business API oficial da Meta, oferecendo uma integração segura, estável e rica em recursos para seus AI agentes.

📹 Vídeo-guias

Problemas com a conexão do WhatsApp?

Assistir vídeo

Entendendo a WhatsApp Official API

Antes de conectar, assista a este guia completo para entender como a API oficial funciona, os modelos de preço e as duas abordagens de conexão disponíveis:

Assistir vídeo

Tópicos abordados:

Como funciona a estrutura de portfólio da Meta
Modo App + API vs. somente API
Modelo de preço (janelas de conversa de 24 horas)
Dois caminhos de conexão: seu portfólio vs. portfólio do cliente
Requisitos de verificação
Respostas às perguntas mais comuns

Tutorial passo a passo de conexão

Assista a este passo a passo prático mostrando exatamente como conectar o WhatsApp pela interface da Zaia:

Assistir vídeo

🔌 Guia rápido de conexão

Na Zaia

Vá até Workspace Settings → Connections → New Connection
Selecione WhatsApp (Official) e dê um nome a ela
Clique em “Connect”

⚠️ Permita pop-ups quando solicitado — a autenticação da Meta abre em uma nova janela.

No fluxo da Meta

1. Criar ou selecionar portfólio

Novo portfólio? Preencha: nome, e-mail, país, site (ou Instagram)
Portfólio existente? Selecione no menu suspenso

2. Escolha o tipo de conexão

Criar conta do WhatsApp	Conectar app existente
Número totalmente novo	Número já usando o app WhatsApp Business
Número nunca usou o WhatsApp	Continuar usando o app + adicionar automação (coexistência)

3. Adicionar número de telefone

Digite o número com o código do país
As informações precisam corresponder ao seu app WhatsApp Business (se estiver conectando um número existente)

4. Verificar número (para números existentes)

Método via QR Code:

Você receberá uma mensagem do Facebook Business no WhatsApp
Clique no botão “Connect” na mensagem
Escolha “Don’t share conversations”
Escaneie o QR Code

Método via código de acesso:

Clique em “Use access code instead”
Digite o código enviado ao WhatsApp

💡 Contas novas: se a verificação falhar, aguarde de 15 a 30 minutos e tente novamente.

5. Confirmar configurações

Selecione o fuso horário
Revise as permissões
Clique em “Confirm” → “Finish”

De volta na Zaia

Crie um Channel e vincule-o à sua nova conexão do WhatsApp
Atribua um Agente ou Squad
Teste enviando uma mensagem para o seu número

✅ Pronto!

🔎 Ver detalhes da conexão

Depois que a conexão for criada, abra Workspace Settings → Connections e confira a área de detalhes da conexão.

Para conexões WhatsApp (Official), a Zaia exibe:

Token
Phone Number ID
WABA ID

Cada campo é somente leitura.

Cada campo também tem sua própria ação de copiar.

Para tokens com mais de 30 caracteres, a Zaia exibe os primeiros 30 caracteres seguidos de ....

A ação de copiar sempre copia o token completo.

Se um valor estiver vazio, a Zaia exibe Not available e desativa a cópia desse campo.

A Zaia só exibe valores já retornados pela conexão existente.

Ela não cria, edita nem recalcula esses identificadores.

⚠️ Importante: verificação de novo portfólio

Criou um novo portfólio durante a configuração? Você precisará verificá-lo em algumas horas:

Documentos exigidos: registro da empresa, comprovante de endereço
Processamento: 2 a 5 dias úteis
Sem verificação, a conexão pode ser restringida após o período inicial

🎯 Duas abordagens de conexão

Seu portfólio (até 40 números)

Adicione números de clientes ao seu próprio portfólio da Meta Business.

Ideal para: começar, configuração rápida, controle total
Limite: 40 números no total (2 portfólios × 20 cada)
Verificação: verifique SUA conta uma vez e adicione todos os 40 números sem verificar novamente

Portfólio do cliente (ilimitado)

O cliente cria o portfólio e adiciona você como admin.

Ideal para: escalar além de 40, empresas formais, propriedade do cliente
Limite: ilimitado
Verificação: cada cliente pode precisar verificar o próprio portfólio (se for empresa formal)

💡 Você pode criar 2 portfólios, mas ser admin em um número ilimitado de portfólios de clientes.

📱 App + API vs. somente API

App + API (coexistência)

O cliente continua usando o app WhatsApp Business + seu AI agente responde via API.

Quando usar: o cliente quer manter o acesso ao app, a equipe precisa responder, IA + humano juntos

Somente API (exclusivo)

O número se torna 100% API. O cliente não pode mais usar o app.

Quando usar: automação total, o cliente não precisa do app, número novo dedicado

⚠️ Aviso: a migração para somente API é irreversível — o número nunca pode voltar ao modo app.

💰 Preços

Cliente envia mensagem: GRATUITO
Você responde (dentro de 24h): GRATUITO — respostas ilimitadas
Você inicia a conversa: ~$0,15-0,35 por mensagem (requer template)

✅ Perfeito para AI agentes! Cada mensagem do cliente abre uma janela de 24h para respostas gratuitas ilimitadas.

🧩 Templates e envio de mensagens de saída

O WhatsApp Official oferece suporte a templates aprovados para entrega de saída.

Na Zaia, isso está disponível em:

Modos de envio suportados

Quando o tipo de conexão é WhatsApp (Official), a Zaia pode enviar:

Text
Template
Text with template fallback

Com o fallback ativado, a Zaia tenta primeiro o texto. Se a Meta rejeitar o envio porque a janela de 24 horas expirou, a Zaia envia o template configurado no lugar.

⚠️ O fallback só é acionado para o erro específico de janela do WhatsApp expirada. Outros erros de entrega não acionam o uso automático de template.

Requisitos do template

Os templates só funcionam quando:

A conexão está ativa
A conexão está configurada corretamente
O template existe para essa conta do WhatsApp
O template está aprovado na Meta

A Zaia só lista templates aprovados da conexão selecionada. Ela também monta dinamicamente os campos exigidos a partir do schema do template da Meta.

Isso inclui:

Variáveis do corpo (Body)
Variáveis do cabeçalho (Header)
Variáveis do botão (Button)
Entrada de imagem de cabeçalho, quando aplicável

Enviar um template pelo Conversations após a janela de 24 horas

Quando uma conversa do WhatsApp oficial fica bloqueada porque a janela de atendimento de 24 horas expirou, o Conversations exibe uma ação para enviar um template aprovado a partir da mesma área de composição bloqueada.

Essa ação não é exibida enquanto o envio de mensagens livres está disponível. Ela se aplica apenas a conversas WhatsApp (Official).

Quando o atendente abre a ação:

A Zaia lista os templates aprovados disponíveis para a conexão vinculada a essa conversa.
O atendente seleciona um template.
A Zaia exibe todos os campos obrigatórios do template.
A ação de envio permanece indisponível até que todos os valores obrigatórios sejam válidos.
O template preenchido é enviado pela mesma conexão oficial do WhatsApp.

Após um envio bem-sucedido, a mensagem do template aparece no histórico da conversa com suas informações de entrega.

Enviar um template não reabre a janela livre de 24 horas. O envio de mensagens livres volta a ficar disponível somente depois que o cliente enviar uma nova mensagem.

Se não houver templates aprovados disponíveis, a interface mostra um estado vazio e não permite o envio. Se a entrega falhar, a interface reporta o erro e a conversa permanece bloqueada.

Comportamento no Workflow vs. na tool

No node de Workflow, todos os campos obrigatórios do template devem ser preenchidos durante a configuração.

Na tool do Agente, os campos do template podem ser preenchidos parcialmente. Os valores ausentes podem ser completados no momento da execução a partir do contexto, dos dados de execução ou da saída do LLM.

Quando ambas as fontes fornecem valores, a Zaia mantém os valores configurados e preenche apenas os que estão faltando.

Validações e restrições

A Zaia valida os campos renderizados do template antes do envio. Isso inclui limites para corpo, cabeçalho, OTP e sufixos de URL de botão.

Templates com cabeçalhos de imagem aceitam uma URL pública, um arquivo armazenado ou uma data URL. A Zaia converte a imagem para o formato aceito pela API do WhatsApp antes de enviar.

Os metadados do template são armazenados no registro de entrega para rastreabilidade.

No envio direto de mensagens de chat, templates não podem ser enviados junto com anexos.

✅ Verificação

Quando é necessária

Novos portfólios (dentro de algumas horas após a criação)
Alto volume (1.000+ mensagens/dia)
Alguns recursos avançados

O que você precisa

Documentos da empresa (CNPJ, registro)
Comprovante de endereço
Processamento: 2 a 5 dias úteis

Pontos-chave

Seu portfólio: verifique uma vez → adicione todos os 40 números
Portfólio do cliente: cada cliente verifica o próprio (se for empresa formal)
Clientes pequenos (MEI/PF): geralmente não precisam de verificação imediata

⚠️ Novos portfólios funcionam inicialmente, mas exigem verificação em algumas horas para a continuidade do serviço.

❓ Perguntas frequentes

Preciso de uma página do Facebook?
Não! Conecte diretamente pelo Business Manager.

Posso usar um número de WhatsApp existente?
Sim! Escolha “Connect existing app” para o modo de coexistência (App + API).

Vou ver conversas anteriores?
Não. Apenas novas conversas a partir do momento da conexão (limitação da API da Meta).

Posso voltar de somente API para App+API?
Não. A migração para somente API é irreversível.

Quanto custa?
Receber + responder (24h): GRATUITO | Iniciar: ~$0,15-0,35/mensagem | Cobrado pela Meta, não pela Zaia.

Quando preciso de verificação?
Novos portfólios precisam de verificação em algumas horas. Clientes pequenos (MEI/PF) geralmente não precisam de verificação imediata.

🔧 Solução de problemas

QR Code / código de verificação falha
Aguarde de 15 a 30 minutos (especialmente para contas novas) e tente o método alternativo (QR ↔ Código).

Pop-up bloqueado
Permita pop-ups para o domínio da Zaia. Tente o Chrome se os problemas persistirem.

Conexão funciona e depois para
Verificação necessária. Confira o e-mail da Meta e verifique a empresa no Business Manager.

Mensagens não aparecem
Garanta que: conexão → vinculada ao Channel → o Channel tem Agente/Squad ativo → conta verificada (se necessário).

Não consigo ver o histórico de mensagens
Limitação da API da Meta. Apenas novas conversas a partir do momento da conexão ficam visíveis.

📚 Recursos

Precisa de ajuda? Entre em contato com o suporte da Zaia pelo chat dentro da plataforma.