Tema
WhatsApp Oficial (Cloud API)
Visão Geral
A integração da Paralela com o WhatsApp Oficial conecta seu número à API oficial do WhatsApp (Cloud API da Meta), oferecendo uma conexão mais estável e recursos avançados em comparação ao método por QR Code.
Principais vantagens:
- Conexão permanente sem quedas de sessão
- Suporte a templates de mensagem para envios fora da janela de 24 horas
- Coexistência (Coex): use o WhatsApp Business App no celular ao mesmo tempo
- Registro de chamadas perdidas no histórico do ticket
- Suporte completo a todos os tipos de mensagem: texto, imagens, vídeo, áudio, documentos, contatos, localização, reações e stickers
Diferença entre QR Code e API Oficial
| Característica | QR Code | API Oficial |
|---|---|---|
| Conexão | Escanear QR Code | Cadastro via Meta Business |
| Estabilidade | Pode desconectar | Conexão permanente |
| Templates | Não suporta | Suporta (obrigatório fora da janela de 24h) |
| Coexistência | Não | Sim (usar WhatsApp Business App no celular ao mesmo tempo) |
| Chamadas | Não registra | Registra chamadas perdidas |
| Reações | Limitado | Suporta reações com emojis |
| Localização | Limitado | Envia e recebe localização |
Requisitos
Para conectar via API Oficial, você precisa de:
- Uma conta Meta Business (business.facebook.com)
- Um número de telefone dedicado (ou compartilhado via Coex)
- Um App da Meta com credenciais (App ID e App Secret) configuradas pelo administrador do sistema
Apps separados por canal: o WhatsApp Cloud API pode usar um App da Meta próprio, separado do App usado para Facebook e Instagram. O administrador define as credenciais do WhatsApp em Configurações → Integrações → WhatsApp Cloud API. Se esses campos ficarem vazios, o WhatsApp reaproveita automaticamente as credenciais do App do Facebook, de modo que operações com um único App continuam funcionando sem alterações.
Conectando via Cadastro Integrado (Coex)
O cadastro integrado (Embedded Signup) é o único caminho para conectar um número à API oficial. O fluxo é guiado pela própria Meta, tanto para números novos quanto para quem já possui uma conta WhatsApp Business (WABA) configurada.
- Abra Conexões no menu lateral. Se o item não aparece, abra Configurações Avançadas e, em Itens Ocultos do Menu, clique em Conexões para mostrá-lo no menu (ou procure "Conexões" na lupa do topo).
- Clique em Nova Conexão
- Selecione WhatsApp COEX
- Siga o fluxo de cadastro da Meta que abre automaticamente
- Autentique com a conta que gerencia o Meta Business e autorize as permissões
- Cadastre um número novo ou selecione uma conta WhatsApp Business (WABA) e número existentes
- Aguarde a verificação e ativação
- A conexão aparece como Conectado
A opção WhatsApp COEX só aparece quando o Configuration ID do cadastro integrado está configurado nas integrações. Sem ele, o cadastro pela API oficial fica indisponível.
Templates de Mensagem
O que são
Templates são formatos de mensagem pré-aprovados pela Meta, obrigatórios para enviar mensagens fora da janela de conversa de 24 horas. Quando um cliente envia uma mensagem, você tem 24 horas para responder livremente. Após esse período, só é possível iniciar contato usando um template aprovado.
Categorias
| Categoria | Uso |
|---|---|
| Marketing | Promoções, ofertas, novidades |
| Utilidade | Confirmações, atualizações, lembretes |
| Autenticação | Códigos de verificação, senhas temporárias |
Sincronizando Templates
- Abra Conexões no menu lateral. Se o item não aparece, abra Configurações Avançadas e, em Itens Ocultos do Menu, clique em Conexões para mostrá-lo no menu (ou procure "Conexões" na lupa do topo).
- Selecione a conexão WhatsApp Oficial desejada
- Clique em Sincronizar Templates
- Os templates aprovados na Meta Business serão importados automaticamente
Status dos Templates
| Status | Significado |
|---|---|
| Aprovado | Pronto para uso |
| Pendente | Em análise pela Meta |
| Rejeitado | Não aprovado, precisa de ajustes e reenvio |
| Desativado | Desativado pela Meta |
Usando Templates
- Ao enviar mensagem fora da janela de 24 horas, o sistema solicita a seleção de um template
- Preencha as variáveis dinâmicas (nome, data, valor, etc.)
- O template é enviado conforme o formato aprovado pela Meta
Templates com Mídia no Cabeçalho (imagem, vídeo, documento)
Um template pode ter um cabeçalho de mídia: uma imagem, um vídeo ou um documento exibido no topo da mensagem.
No cadastro do template:
- Em Templates WhatsApp, ao criar o template, escolha o Formato do cabeçalho como Imagem, Vídeo ou Documento
- Envie o arquivo da mídia. Ele é exigido pela Meta como amostra para aprovação e também fica guardado como mídia padrão do template
- Conclua o cadastro normalmente
No envio (fluxos, campanhas, agendamentos e atendimento):
- Ao usar um template de mídia, o sistema mostra o campo URL da mídia do cabeçalho, já preenchido com a mídia padrão cadastrada
- Você pode deixar como está (usa o padrão) ou informar outra URL/variável para enviar uma mídia diferente naquele disparo
- Nos fluxos, o campo aceita uma variável (ex:
{{minha_imagem}}) para enviar uma mídia dinâmica
A URL precisa ser pública
Quando uma URL é informada no envio, a Meta baixa o arquivo no momento do disparo. Use sempre um link HTTPS público e direto (sem encurtadores ou redirecionamentos). Arquivos enviados pelo próprio sistema já atendem a esse requisito.
| Formato | Tipos aceitos | Limite |
|---|---|---|
| Imagem | JPG, PNG | 5 MB |
| Vídeo | MP4 | 16 MB |
| Documento | PDF e outros | 100 MB |
Registro do Número e Reconexão Automática
Para enviar e receber mensagens pela API Oficial, o número precisa estar registrado na Cloud API da Meta. A Paralela cuida disso automaticamente:
- Ao adicionar uma conexão: o número é registrado automaticamente, independentemente de ele ter sido adicionado pelo cadastro embutido (Embedded Signup) ou selecionado a partir de uma conta WhatsApp Business existente.
- Recuperação automática: se a Meta desvincular o número (desregistro), a Paralela detecta e tenta registrar novamente de forma automática. Isso acontece em três situações:
- quando uma mensagem falha por número não registrado (qualquer tipo: texto, template, mídia, contato);
- quando a Meta envia um evento de remoção de parceiro (
account_updatecomevent: PARTNER_REMOVED) pelo webhook; - na inicialização do sistema, para números que ainda nunca foram registrados.
- Limite da Meta: a Meta limita o registro a cerca de 10 tentativas por número a cada 72 horas. Por isso o registro só é disparado quando realmente necessário, com controle de repetição para nunca exceder esse limite.
Registrar manualmente
Na página de Conexões, o cartão de um número da API Oficial exibe a ação Registrar novamente. Use-a caso o número apareça como desconectado e você queira forçar um novo registro imediatamente. Se o registro falhar (por exemplo, PIN de verificação em duas etapas incorreto), a mensagem de erro da Meta será exibida.
Requisito de webhook: para que a recuperação automática via evento
PARTNER_REMOVEDfuncione, o aplicativo Meta deve estar inscrito no campo de webhookaccount_update. Mesmo sem essa inscrição, a recuperação por falha de envio e na inicialização continua funcionando.
Recursos Exclusivos
Coexistência (Coex)
O modo de coexistência permite usar o WhatsApp Business App no celular ao mesmo tempo que o número está conectado à Paralela.
- Mensagens enviadas pelo app aparecem na Paralela
- Mensagens enviadas pela Paralela aparecem no app
- Ideal para equipes que precisam do celular em campo
Chamadas Perdidas
Chamadas de voz recebidas são registradas automaticamente como um log no ticket do contato.
- Permite acompanhar tentativas de contato por ligação
- O registro aparece no histórico da conversa
Reações
- Clientes podem reagir a mensagens com emojis
- As reações aparecem no histórico da conversa em tempo real
Localização
- Envie e receba mensagens de localização diretamente pelo chat
- Localizações recebidas incluem um link para o Google Maps
Origem de Anúncios (Click-to-WhatsApp)
Quando um cliente inicia a conversa clicando em um anúncio do Facebook/Instagram (Click-to-WhatsApp) ou em um post com botão "Enviar mensagem", a Meta envia os dados de origem junto da primeira mensagem da conversa. A Paralela captura esses dados e os guarda no ticket daquele atendimento.
Ficam disponíveis as seguintes variáveis:
| Variável | Conteúdo |
|---|---|
{{ctwa_clid}} | Identificador do clique no anúncio (usado para atribuição na API de Conversões da Meta) |
{{source_id}} | ID do anúncio ou post que originou a conversa |
{{source_url}} | URL do anúncio ou post que o cliente clicou |
{{source_type}} | Tipo da origem: ad (anúncio) ou post |
Como usar: essas variáveis funcionam em qualquer texto renderizado do atendimento — mensagens de fluxo, notificações, saudações e webhooks. Por exemplo, você pode encaminhar a origem para um CRM externo via webhook usando {{ctwa_clid}} e {{source_id}}, ou exibir a campanha de origem em uma mensagem automática.
Escopo por conversa
Os dados de origem ficam vinculados ao ticket que iniciou o contato pelo anúncio. Se o mesmo cliente voltar por outro anúncio em um novo atendimento, o novo ticket recebe a origem correspondente. A Meta só envia esses dados na primeira mensagem de conversas iniciadas por anúncio/post.
Além das variáveis, a Paralela registra o anúncio de origem (título, texto, tipo de mídia e ID) no ticket — o anúncio mais recente que trouxe aquela conversa — e no contato — o primeiro anúncio pelo qual ele chegou.
Também em conexões QR Code
As mesmas variáveis ({{ctwa_clid}}, {{source_id}}, {{source_url}}, {{source_type}}) também funcionam em conexões WhatsApp por QR Code. Veja WhatsApp (QR Code).
Filas e Distribuição
A distribuição de conversas funciona da mesma forma que no WhatsApp QR Code. Você pode vincular filas à conexão, configurar distribuição automática entre atendentes e definir saudações com I.A. Consulte a documentação de WhatsApp para mais detalhes sobre filas e distribuição.
Integração com I.A.
Os mesmos assistentes de I.A. disponíveis no WhatsApp QR Code funcionam com a API Oficial. Mensagens de áudio podem ser transcritas automaticamente. Consulte a documentação de Assistentes I.A. para mais detalhes.