Tema
WhatsApp Oficial (Cloud API)
Visao Geral
O Paralela suporta a integracao com a API oficial do WhatsApp (Cloud API da Meta), oferecendo uma conexao mais estavel e recursos avancados em comparacao ao metodo por QR Code.
Principais vantagens:
- Conexao permanente sem quedas de sessao
- Suporte a templates de mensagem para envios fora da janela de 24 horas
- Coexistencia (Coex): use o WhatsApp Business App no celular ao mesmo tempo
- Registro de chamadas perdidas no historico do ticket
- Suporte completo a todos os tipos de mensagem: texto, imagens, video, audio, documentos, contatos, localizacao, reacoes e stickers
Diferenca entre QR Code e API Oficial
| Caracteristica | QR Code | API Oficial |
|---|---|---|
| Conexao | Escanear QR Code | Cadastro via Meta Business |
| Estabilidade | Pode desconectar | Conexao permanente |
| Templates | Nao suporta | Suporta (obrigatorio fora da janela de 24h) |
| Coexistencia | Nao | Sim (usar WhatsApp Business App no celular ao mesmo tempo) |
| Chamadas | Nao registra | Registra chamadas perdidas |
| Reacoes | Limitado | Suporta reacoes com emojis |
| Localizacao | Limitado | Envia e recebe localizacao |
Requisitos
Para conectar via API Oficial, voce precisa de:
- Uma conta Meta Business (business.facebook.com)
- Um numero 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 proprio, separado do App usado para Facebook e Instagram. O administrador define as credenciais do WhatsApp em Configuracoes → Integracoes → WhatsApp Cloud API. Se esses campos ficarem vazios, o WhatsApp reaproveita automaticamente as credenciais do App do Facebook, de modo que operacoes com um unico App continuam funcionando sem alteracoes.
Conectando via Cadastro Integrado (Coex)
O cadastro integrado (Embedded Signup) e o unico caminho para conectar um numero a API oficial. O fluxo e guiado pela propria Meta, tanto para numeros novos quanto para quem ja possui uma conta WhatsApp Business (WABA) configurada.
- Acesse Conexoes no menu lateral
- Clique em Adicionar Conexao
- 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 permissoes
- Cadastre um numero novo ou selecione uma conta WhatsApp Business (WABA) e numero existentes
- Aguarde a verificacao e ativacao
- A conexao aparece como Conectado
A opcao WhatsApp COEX so aparece quando o Configuration ID do cadastro integrado esta configurado nas integracoes. Sem ele, o cadastro pela API oficial fica indisponivel.
Templates de Mensagem
O que sao
Templates sao formatos de mensagem pre-aprovados pela Meta, obrigatorios para enviar mensagens fora da janela de conversa de 24 horas. Quando um cliente envia uma mensagem, voce tem 24 horas para responder livremente. Apos esse periodo, so e possivel iniciar contato usando um template aprovado.
Categorias
| Categoria | Uso |
|---|---|
| Marketing | Promocoes, ofertas, novidades |
| Utilidade | Confirmacoes, atualizacoes, lembretes |
| Autenticacao | Codigos de verificacao, senhas temporarias |
Sincronizando Templates
- Acesse Conexoes no menu lateral
- Selecione a conexao WhatsApp Oficial desejada
- Clique em Sincronizar Templates
- Os templates aprovados na Meta Business serao importados automaticamente
Status dos Templates
| Status | Significado |
|---|---|
| Aprovado | Pronto para uso |
| Pendente | Em analise pela Meta |
| Rejeitado | Nao 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 selecao de um template
- Preencha as variaveis dinamicas (nome, data, valor, etc.)
- O template e enviado conforme o formato aprovado pela Meta
Templates com Midia no Cabecalho (imagem, video, documento)
Um template pode ter um cabecalho de midia: uma imagem, um video ou um documento exibido no topo da mensagem.
No cadastro do template:
- Em Templates WhatsApp, ao criar o template, escolha o Formato do cabecalho como Imagem, Video ou Documento
- Envie o arquivo da midia. Ele e exigido pela Meta como amostra para aprovacao e tambem fica guardado como midia padrao do template
- Conclua o cadastro normalmente
No envio (fluxos, campanhas, agendamentos e atendimento):
- Ao usar um template de midia, o sistema mostra o campo URL da midia do cabecalho, ja preenchido com a midia padrao cadastrada
- Voce pode deixar como esta (usa o padrao) ou informar outra URL/variavel para enviar uma midia diferente naquele disparo
- Nos fluxos, o campo aceita uma variavel (ex:
) para enviar uma midia dinamica
A URL precisa ser publica
Quando uma URL e informada no envio, a Meta baixa o arquivo no momento do disparo. Use sempre um link HTTPS publico e direto (sem encurtadores ou redirecionamentos). Arquivos enviados pelo proprio sistema ja atendem a esse requisito.
| Formato | Tipos aceitos | Limite |
|---|---|---|
| Imagem | JPG, PNG | 5 MB |
| Video | MP4 | 16 MB |
| Documento | PDF e outros | 100 MB |
Registro do Numero e Reconexao Automatica
Para enviar e receber mensagens pela API Oficial, o numero precisa estar registrado na Cloud API da Meta. O Paralela cuida disso automaticamente:
- Ao adicionar uma conexao: o numero e registrado automaticamente, independentemente de ele ter sido adicionado pelo cadastro embutido (Embedded Signup) ou selecionado a partir de uma conta WhatsApp Business existente.
- Recuperacao automatica: se a Meta desvincular o numero (desregistro), o Paralela detecta e tenta registrar novamente de forma automatica. Isso acontece em tres situacoes:
- quando uma mensagem falha por numero nao registrado (qualquer tipo: texto, template, midia, contato);
- quando a Meta envia um evento de remocao de parceiro (
account_updatecomevent: PARTNER_REMOVED) pelo webhook; - na inicializacao do sistema, para numeros que ainda nunca foram registrados.
- Limite da Meta: a Meta limita o registro a cerca de 10 tentativas por numero a cada 72 horas. Por isso o registro so e disparado quando realmente necessario, com controle de repeticao para nunca exceder esse limite.
Registrar manualmente
Na pagina de Conexoes, o cartao de um numero da API Oficial exibe a acao Registrar novamente. Use-a caso o numero apareca como desconectado e voce queira forcar um novo registro imediatamente. Se o registro falhar (por exemplo, PIN de verificacao em duas etapas incorreto), a mensagem de erro da Meta sera exibida.
Requisito de webhook: para que a recuperacao automatica via evento
PARTNER_REMOVEDfuncione, o aplicativo Meta deve estar inscrito no campo de webhookaccount_update. Mesmo sem essa inscricao, a recuperacao por falha de envio e na inicializacao continua funcionando.
Recursos Exclusivos
Coexistencia (Coex)
O modo de coexistencia permite usar o WhatsApp Business App no celular ao mesmo tempo que o numero esta conectado ao Paralela.
- Mensagens enviadas pelo app aparecem no Paralela
- Mensagens enviadas pelo Paralela aparecem no app
- Ideal para equipes que precisam do celular em campo
Chamadas Perdidas
Chamadas de voz recebidas sao registradas automaticamente como um log no ticket do contato.
- Permite acompanhar tentativas de contato por ligacao
- O registro aparece no historico da conversa
Reacoes
- Clientes podem reagir a mensagens com emojis
- As reacoes aparecem no historico da conversa em tempo real
Localizacao
- Envie e receba mensagens de localizacao diretamente pelo chat
- Localizacoes recebidas incluem um link para o Google Maps
Origem de Anuncios (Click-to-WhatsApp)
Quando um cliente inicia a conversa clicando em um anuncio do Facebook/Instagram (Click-to-WhatsApp) ou em um post com botao "Enviar mensagem", a Meta envia os dados de origem junto da primeira mensagem da conversa. O Paralela captura esses dados e os guarda no ticket daquele atendimento.
Ficam disponiveis as seguintes variaveis:
| Variavel | Conteudo |
|---|---|
| Identificador do clique no anuncio (usado para atribuicao na API de Conversoes da Meta) |
| ID do anuncio ou post que originou a conversa |
| URL do anuncio ou post que o cliente clicou |
| Tipo da origem: ad (anuncio) ou post |
Como usar: essas variaveis funcionam em qualquer texto renderizado do atendimento — mensagens de fluxo, notificacoes, saudacoes e webhooks. Por exemplo, voce pode encaminhar a origem para um CRM externo via webhook usando e , ou exibir a campanha de origem em uma mensagem automatica.
Escopo por conversa
Os dados de origem ficam vinculados ao ticket que iniciou o contato pelo anuncio. Se o mesmo cliente voltar por outro anuncio em um novo atendimento, o novo ticket recebe a origem correspondente. A Meta so envia esses dados na primeira mensagem de conversas iniciadas por anuncio/post.
Filas e Distribuicao
A distribuicao de conversas funciona da mesma forma que no WhatsApp QR Code. Voce pode vincular filas a conexao, configurar distribuicao automatica entre atendentes e definir saudacoes com I.A. Consulte a documentacao de WhatsApp para mais detalhes sobre filas e distribuicao.
Integracao com I.A.
Os mesmos assistentes de I.A. disponiveis no WhatsApp QR Code funcionam com a API Oficial. Mensagens de audio podem ser transcritas automaticamente. Consulte a documentacao de Assistentes I.A. para mais detalhes.