WhatsApp

O canal WhatsApp fica em Configurações → Canais → WhatsApp. Você pode cadastrar várias conexões — cada conexão é um número, ligado por um de três jeitos: Meta Cloud API, app WhatsApp Business (coexistência) ou Evolution API. Todos usam o mesmo payload da API Enviar Mensagens: a integração não precisa saber qual provedor está por trás. A tela do canal tem as abas Conexões, Templates (só aparece quando há uma conexão do app WhatsApp Business), Configurações Gerais e Boas Práticas.

​

Conexões

A aba Conexões lista os números cadastrados. Cada item mostra o nome, o provedor e os marcadores (padrão) ou (desativada), além dos nomes das credenciais já preenchidas — os valores nunca aparecem na lista. Ações disponíveis em cada conexão:

• Tornar padrão — passa a ser a conexão usada por tudo que não escolher outra.
• QR Code — só em conexões Evolution: abre o painel de pareamento, teste e histórico.
• Editar — abre as credenciais. O provedor não pode ser trocado depois que a conexão é criada; para usar outro provedor, crie uma nova conexão.
• Remover — apaga a conexão.

​

Regras das conexões

• Toda conexão precisa de um nome, único entre as suas conexões de WhatsApp. É esse nome que aparece quando você escolhe por onde uma mensagem sai.
• A primeira conexão cadastrada vira a padrão automaticamente.
• Só existe uma conexão padrão por vez, e só uma conexão ativa pode ser padrão.
• A conexão padrão não pode ser removida enquanto houver outra conexão ativa: o painel mostra ”… é a conexão padrão. Escolha outra conexão como padrão antes de removê-la.” Se ela for a única, a remoção é permitida.
• O mesmo Phone Number ID da Meta não pode estar em duas conexões.
• A conexão do app WhatsApp Business (coexistência) não pode ser criada nem editada pelo formulário de conexões: nome e método vêm da conexão feita com o Facebook. Dá para remover, tornar padrão e acompanhar o estado na lista.
• O mesmo número não pode estar em duas contas da OctaSend.
• Qualquer usuário da conta com acesso ao painel pode cadastrar, editar e remover conexões.

​

Conectar pela Evolution API (QR Code)

Depois de conectado, o botão QR Code da conexão reabre o painel, que mostra:

• Status — Desconectado, Iniciando sessão…, Aguardando leitura do QR Code, Conectado ou Erro ao iniciar sessão. Se o servidor da Evolution não responder, aparece o aviso Servidor Evolution API indisponível com o detalhe.
• Enviar mensagem de teste — só com a conexão conectada. Informe o número no formato internacional, sem + (ex.: 5511999999999), e o texto.
• Histórico de conexões — as últimas 10 sessões, com número, início, duração e motivo da desconexão.
• Desconectar — pede confirmação e encerra a sessão. O envio por essa conexão para até você ler um novo QR Code.

​

Conectar pela Meta Cloud API (oficial)

Requer uma conta WhatsApp Business aprovada na Meta. Com o webhook configurado:

• Os Logs de Mensagens são atualizados sozinhos. Uma falha de entrega muda o status para Falhou, com o código e o motivo informados pela Meta. A entrega e a leitura ficam registradas com data e hora, nos campos delivered_at e read_at de Consultar logs, e o status continua Enviada. Uma confirmação que chegue atrasada não apaga uma já registrada.
• As mensagens que seus clientes mandam para o número (texto e mídia) chegam à OctaSend e podem ser respondidas pelo chatbot.

​

Janela de 24 horas e template aprovado

A Meta só aceita mensagem livre para quem falou com o seu número nas últimas 24 horas. Por isso:

• Se a conexão tem Template Name preenchido e o template da comunicação é uma única mensagem de texto simples, o envio usa o template aprovado — que funciona fora da janela. Nesse caso, quem chega ao destinatário é o texto aprovado na Meta, não o texto escrito na comunicação. O idioma é o do campo Template Language (pt_BR se vazio).
• Nesse caso, os valores de variables da chamada viram os parâmetros do corpo do template, na ordem numérica das chaves ("1", "2", "3"…). Chaves não numéricas entram depois, em ordem alfabética. Envie exatamente os parâmetros que o template aprovado espera.
• Sequências com mais de uma mensagem e conteúdo rico (mídia, botões, lista, carrossel) sempre saem como mensagem livre: fora da janela, a Meta recusa e o log registra a falha.

​

Conectar o número do app WhatsApp Business (coexistência)

Se a sua empresa já atende pelo aplicativo WhatsApp Business no celular, você pode conectar esse mesmo número à OctaSend sem tirá-lo do aplicativo. O número continua funcionando no celular e passa a funcionar também na plataforma: caixa Conversas, chatbot, comunicações, automações, campanhas e API. Você não cola token nem cria app na Meta. Entra com o Facebook numa janela da Meta, confirma a conexão pelo aplicativo do celular e escolhe se compartilha o histórico.

​

Antes de começar

​

Conectar

Ao conectar, a plataforma pede à Meta os contatos do aplicativo e o histórico das conversas individuais. A conexão nova leva o nome WhatsApp mais o número e, se for a primeira conexão de WhatsApp da conta, já nasce como padrão. Se o mesmo número já estava conectado aqui pela Meta Cloud API (configuração manual), a configuração manual é substituída pela coexistente, mantendo nome, padrão e bot da conexão.

​

Histórico e contatos

• Conversas: só as conversas individuais; grupos não são importados (limite da Meta). As mensagens antigas entram como histórico: não reabrem a conversa, não tiram o responsável, ficam como lidas e não acionam o chatbot. Conversas em que só há mensagens antigas ficam como Resolvidas.
• Mídia do histórico: só chega a mídia dos últimos 14 dias. A mais antiga aparece como anexo indisponível.
• Contatos: entram em Contatos. O nome vindo do aplicativo só preenche contato que ainda está sem nome.
• Um pedido de importação por conexão: a Meta aceita um pedido de contatos e um de histórico a cada conexão do número, e o prazo é de 24 horas. Depois de concluída (inclusive quando você recusou o histórico), reconectar não pede de novo. Para tentar outra vez, desconecte o número da plataforma no aplicativo do celular (veja Sair da plataforma, abaixo) e conecte de novo.

Estados que a lista de conexões pode mostrar: Enquanto a conexão está suspensa ou precisa reconectar, ela não pode ser a padrão, e a caixa Conversas bloqueia a resposta com Os envios por este número estão pausados. Quem administra os canais pode conferir a conexão em Canais.

​

O que muda no envio

• Mesmo caminho da Meta Cloud API. Comunicações, automações, campanhas, API e a caixa Conversas enviam pelo mesmo caminho da Meta Cloud API, e valem as regras da janela de 24 horas: a mensagem livre só é aceita até 24 horas depois da última mensagem do cliente. Fora da janela, use um template aprovado (veja Templates da Meta, abaixo) ou responda pelo próprio aplicativo do celular, que não depende da janela. Mensagem livre fora da janela é recusada pela Meta e o log registra a falha.
• Sem fila e sem intervalo mínimo. Como na Meta Cloud API, a mensagem sai na hora. A fila e o limite por minuto da Evolution não se aplicam.
• Velocidade. A Meta limita o número a cerca de 20 mensagens por segundo. A plataforma não impõe um limite próprio nessa conexão: valem os limites gerais da conta, como o limite diário de mensagens.
• Status no log. Entrega e leitura chegam pelo webhook da própria plataforma, sem você configurar nada na Meta. Falhas de entrega mudam o log para Falhou, com o motivo da Meta.
• Mensagens enviadas pelo celular. O que você escreve pelo aplicativo aparece na conversa como Celular, e o chatbot fica pausado nessa conversa por 30 minutos. As mensagens que a própria plataforma envia e que “voltam” como eco não pausam o bot.
• Chatbot. Responde a texto e mídia recebidos em até 10 minutos da chegada; mensagens atrasadas da Meta são gravadas sem acionar o bot.

​

Templates da Meta

A aba Templates do canal lista os templates da conta WhatsApp Business de cada conexão do app WhatsApp Business: escolha a conexão no seletor Conexão para criar, editar, excluir e sincronizar. O status de aprovação vem da Meta e é sincronizado todo dia. A conexão Meta Cloud API configurada à mão não aparece aqui: ela usa o campo Template Name.

• Onde usar: em Comunicações, escolhendo o template e as variáveis (campo do contato ou valor fixo); na caixa Conversas, pelo botão Enviar template, que funciona fora das 24 horas; e pela API Enviar Mensagens.
• Regras da Meta: template de marketing exige opt-in do contato; um template aprovado só pode ser editado 1 vez a cada 24 horas e 10 vezes em 30 dias; excluir um template apaga todos os idiomas dele.
• Templates com parâmetros nomeados ainda não são suportados.

​

Mesmo número na Meta e na Evolution

Ao conectar um número que já tem uma conexão Evolution (QR Code) ativa, os dois caminhos podem ficar ligados ao mesmo tempo. Isso só muda algo quando as duas conexões estão ativas no mesmo número.

• Uma conversa por cliente e número. Ao ligar a segunda conexão, as conversas antigas da coexistente são juntadas às da Evolution. A mesma mensagem que chega pelos dois caminhos aparece uma vez na conversa.
• O chatbot atende por uma conexão só. No cartão do número, o campo Bot atende por define qual. Se essa conexão cair, o bot fica parado, o cartão avisa, e ele não troca de caminho sozinho.
• Resposta pela inbox. No campo de mensagem aparece Enviar por: Meta / Evolution, com o padrão definido em Conversas respondem por. Pela Meta, só dentro das 24 horas.
• Grupos continuam só pela Evolution.
• Limites: contatos @lid da Evolution não são juntados, e mais de duas conexões no mesmo número não são suportadas.
• Reativar uma conexão pode soltar o vínculo do chatbot dela, se outra conexão do número já tem bot. Reassocie o bot no cartão depois.

​

Sair da plataforma

• Remover a conexão na plataforma desliga o chatbot dessa conexão (se não restar nenhuma outra), apaga a conexão e para de receber as mensagens por aqui. O número continua no aplicativo do celular. As conversas já salvas permanecem.
• Para o número deixar a plataforma também do lado da Meta, desconecte pelo aplicativo: Configurações → Conta → Plataforma comercial → Desconectar conta. É também o caminho para pedir a importação do histórico de novo.
• A Meta também pode desconectar o número sozinha, por exemplo se o aplicativo principal ficar cerca de 14 dias sem ser aberto. Se os envios falharem com a conexão aparentemente normal, abra Configurações → Conta → Plataforma comercial no aplicativo e, se o número estiver desconectado, use Conectar número do WhatsApp Business com o mesmo número: a conexão existente é atualizada.

​

Problemas comuns

​

Qual conexão envia cada mensagem

Quando você tem mais de um número, a conexão é escolhida nesta ordem — vale a primeira definida:

1. Conexão desta mensagem — o ícone de conexão em cada mensagem de uma sequência, no editor do template.
2. Enviar esta mensagem por — no template de cada idioma da comunicação.
3. Conexão padrão desta comunicação — na aba Configurações do canal WhatsApp da comunicação. Vale para todos os idiomas, exceto os que definirem uma conexão própria.
4. Conexão padrão do canal — definida em Configurações Gerais ou pelo botão Tornar padrão.

Enquanto um campo estiver herdando, o painel mostra embaixo dele “Será enviado por: …” com a conexão que vai de fato disparar. Uma mesma sequência pode misturar conexões Meta e Evolution. Se a conexão escolhida estiver desativada, o envio falha com o aviso “A conexão … está desativada. Ative-a ou escolha outra conexão.” — ele não cai para a padrão em silêncio.

​

Configurações Gerais

A aba Configurações Gerais tem dois ajustes:

• Conexão padrão do canal — seletor com as conexões ativas. Toda mensagem que não escolher uma conexão específica sai pela padrão.
• Intervalo mínimo entre envios — tempo mínimo, de 1 a 60 segundos, entre duas mensagens da fila da Evolution, com o botão Salvar intervalo. Deixe em branco para não usar intervalo. Vale para as mensagens que passam pela fila (API, automações e eventos de integrações); conversas, grupos e envios pela Meta saem na hora. Recomendamos pelo menos 3 segundos para reduzir o risco de bloqueio do número. É o mesmo valor da tela Fila de WhatsApp, descrita abaixo.

Se a fila estiver desligada para a sua conta, a aba avisa: nesse caso os envios pela Evolution saem na hora e o intervalo não é aplicado.

​

Ritmo de envio e fila (Evolution)

Mensagens de comunicações — disparadas pela API, por automações ou por eventos de integrações como a Nuvem Shop — que saem por uma conexão Evolution não são enviadas na hora: entram numa fila. Campanhas têm ritmo de disparo próprio e não passam por esta fila.

• A resposta da API traz "status": "queued" e a nota Message queued (will be sent in intervals). O log fica Enfileirada até a mensagem ser processada.
• A fila é processada a cada minuto e respeita um limite de mensagens por minuto por conta: 20 por minuto, a menos que a OctaSend tenha combinado outro valor com você. O que passar do limite espera a próxima janela.
• O limite vale para a conta inteira, somando todas as conexões Evolution. Cada mensagem de uma sequência conta como uma mensagem.
• Com o Intervalo mínimo entre envios configurado, a fila também espera pelo menos esse tempo entre duas mensagens da conta, sempre dentro do limite por minuto. Com muitas mensagens acumuladas, as que não cabem no minuto ficam para os minutos seguintes.
• Mudar o intervalo (aumentar, diminuir ou deixar em branco) vale também para as mensagens que já esperavam a vez: elas passam para o ritmo novo, na mesma ordem, a partir de cerca de 90 segundos depois da mudança. A mensagem que já está sendo enviada não é tocada, então nada sai em dobro.
• Depois do processamento, o log muda para Enviada, Falhou (com o motivo) ou Ignorada. Depois de enviada, a mensagem passa para Entregue e Lida quando o WhatsApp confirma a entrega e a leitura. O status só avança: uma confirmação atrasada não volta uma mensagem lida para entregue.
• Uma mensagem que falha no envio é tentada de novo, cerca de 1 minuto depois, até o Máximo de tentativas da conta. O padrão é uma tentativa só: sem configurar, a falha é final. Número sem WhatsApp e mensagem que já saiu em parte não são tentados de novo. Quando um item de uma sequência volta para nova tentativa, os itens seguintes para o mesmo contato voltam para a fila atrás dele.

Pela Meta, não há fila: a mensagem sai na hora e a resposta da API já traz o resultado do envio.

​

Tela Fila de WhatsApp

Quando pelo menos uma conexão Evolution está conectada, aparece o item Configurações → Fila de WhatsApp. A tela mostra só a fila da sua conta:

• Configurações da fila — campos Intervalo mínimo entre envios (de 1 a 60 segundos; em branco, sem intervalo) e Máximo de tentativas (de 1 a 10; em branco, uma tentativa só), com o botão Salvar configurações. O intervalo é o mesmo da aba Configurações Gerais do canal. Um valor fora da faixa mostra o erro no próprio campo.
• Estatísticas — contadores de Pendente e Processando, com as mensagens que estão na fila agora, e de Enviado e Falhou, com as já processadas. Os contadores se atualizam sozinhos a cada 10 segundos. Se uma leitura falhar, a tela mantém os últimos números e mostra o aviso “Não foi possível atualizar a fila agora.”, que some quando a leitura volta. Mensagens ignoradas por número sem WhatsApp não entram nessa contagem; elas aparecem no log de processamento como Pulada.
• Fila Pendente — as mensagens que aguardam a vez, com telefone, status (Enfileirada ou Enviando), desde quando estão na fila e o número de tentativas. A tabela se atualiza sozinha a cada 10 segundos e mostra até 20 mensagens.
• Log de processamento — os últimos 100 processamentos, atualizados em tempo real, com telefone, status (Enviada, Falhou, Tentando ou Pulada), tentativa, data e o erro, quando houver.

​

Regras de envio

​

Boas Práticas

A aba Boas Práticas reúne recomendações para reduzir o risco de o número ser suspenso ou banido — importantes principalmente na Evolution:

• Volume e aquecimento — comece com no máximo 100 mensagens por dia em números novos e aumente de 10% a 20% por semana; aguarde pelo menos 3 segundos entre envios; não mande mais de 3 mensagens seguidas para o mesmo contato sem resposta.
• Horários — envie entre 8h e 20h no fuso do destinatário; evite campanhas de marketing em fins de semana e feriados.
• Consentimento — tenha opt-in explícito, nunca use listas compradas e diga em cada mensagem como cancelar.
• Conteúdo — evite links encurtados, caixa alta excessiva e termos como “GRÁTIS” ou “URGENTE”; personalize as mensagens.
• Saúde do número — mantenha uso orgânico, pause os envios se a taxa de bloqueio passar de 2% e não use o mesmo número em vários dispositivos ao mesmo tempo.

​

Testar o canal

• Evolution — use Enviar mensagem de teste no painel do QR Code, com a conexão conectada.
• Meta — Testar Conexão valida as credenciais sem enviar mensagem.
• Template de uma comunicação — o botão Enviar teste do editor manda o template para o Destinatário de Teste cadastrado em Configurações → Geral. O teste usa o rascunho salvo da versão, se houver; os envios reais usam só a versão publicada. Esse destinatário fica salvo no seu navegador, separado por pessoa e por empresa. Veja Comunicações.