> ## Documentation Index > Fetch the complete documentation index at: https://docs.octasend.com.br/llms.txt > Use this file to discover all available pages before exploring further. # WhatsApp > Conecte um ou mais números pela Meta Cloud API (oficial), pelo app WhatsApp Business do celular (coexistência) ou pela Evolution API (QR Code) e entenda como cada mensagem sai 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](https://docs.octasend.com.br/api-reference/enviar-mensagens.md): a integração não precisa saber qual provedor está por trás. | | Meta Cloud API (oficial) | App WhatsApp Business (coexistência) | Evolution API (QR Code) | | - | - | - | - | | Aprovação prévia | Sim (conta WhatsApp Business na Meta) | Não precisa de token nem de app próprio; você entra com o Facebook e confirma pelo aplicativo | Não | | O que você informa | Phone Number ID e Access Token (WABA ID opcional) e, para receber eventos, App Secret e Verify Token | Nada além do login do Facebook e da confirmação no celular | Nada — basta ler o QR Code com o celular | | Como a mensagem sai | Na hora | Na hora (mesmo caminho da Meta Cloud API) | Por uma fila, com limite de mensagens por minuto e, se você configurar, intervalo mínimo entre envios e novas tentativas | | Status registrados no log | Enviada, Falhou ou Ignorada. Com o webhook configurado, a entrega e a leitura ficam registradas, e o status continua Enviada | Como na Meta: entrega e leitura chegam sozinhas | Enfileirada, depois Enviada, Falhou ou Ignorada. Depois de enviada, Entregue e Lida quando o WhatsApp confirma | | Conteúdo rico (botões, lista, carrossel) | Com adaptações — veja [Enviar Mensagens](https://docs.octasend.com.br/api-reference/enviar-mensagens.md#mensagens-ricas) | Como na Meta Cloud API | Sim | | Grupos de WhatsApp | Não | Não | Sim — veja [Conversas e grupos](https://docs.octasend.com.br/plataforma/whatsapp-conversas-e-grupos.md) | | Risco de bloqueio do número | Menor | Menor que o da Evolution. Fora da janela de 24 horas, só com template aprovado (aba **Templates**) ou pelo celular | Maior: é uma automação não oficial de um número comum | > [!NOTE] > > Os canais e provedores disponíveis são liberados por conta. Se o WhatsApp ou um dos provedores não aparecer para você, fale com a OctaSend. 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) **1. Criar a conexão** Na aba **Conexões**, clique em **Adicionar conexão**, dê um nome (ex.: *WhatsApp Vendas*) e escolha **Evolution API**. A conexão é criada na hora e o painel do QR Code aparece no próprio formulário. Sem nome, o painel avisa *"Dê um nome para esta conexão"*. **2. Gerar o QR Code** Clique em **Conectar WhatsApp**. O status passa para **Aguardando leitura do QR Code**. **3. Ler com o celular** No celular, abra o WhatsApp → **Dispositivos conectados** → **Conectar um dispositivo** e escaneie o código. **4. Aguardar a confirmação** O painel consulta o status sozinho a cada poucos segundos até mostrar **Conectado**, com o número pareado. O QR Code vale por cerca de 1 minuto: se ele expirar antes da leitura, clique em **Gerar novo código**. 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. > [!NOTE] > > O servidor da Evolution é mantido pela OctaSend: você não informa URL, chave nem webhook. O recebimento de mensagens e de avisos de desconexão já vem configurado. > [!WARNING] > > Enquanto alguma conexão Evolution que já foi pareada estiver fora do ar, o menu lateral mostra o aviso **WhatsApp (Evolution) desconectado — Clique para reconectar**, que leva à tela do canal. Uma conexão recém-criada que ainda não leu o QR Code não gera o aviso. Mensagens que chegam à vez de envio com a conexão desconectada **falham** — elas não esperam a reconexão. ## Conectar pela Meta Cloud API (oficial) Requer uma conta WhatsApp Business aprovada na Meta. **1. Criar a conexão** Na aba **Conexões**, clique em **Adicionar conexão**, dê um nome e escolha **Meta Cloud API**. **2. Preencher as credenciais** | Campo | Obrigatório | Descrição | | - | - | - | | Phone Number ID | Sim | ID numérico do número no WhatsApp Business | | WhatsApp Business Account ID (WABA ID) | Não | ID da conta WhatsApp Business | | Access Token permanente | Sim | Token gerado no Meta Business (`EAAxxx...`) | | App Secret | Não | Em **App Settings → Basic** no Meta App. Necessário para receber status de entrega e mensagens | | Webhook Verify Token | Não | Um valor secreto qualquer, definido por você, usado para validar o webhook | | Template Name | Não | Template aprovado para mensagens fora da janela de 24 horas | | Template Language | Não | Idioma do template (ex.: `pt_BR`) | **3. Testar e salvar** **Testar Conexão** consulta o número na Meta e responde *"Conectado: +55 11 ... (nome verificado)"*. Erros comuns: *"Access Token inválido ou expirado"*, *"Phone Number ID inválido"* e *"Preencha o Phone Number ID e o Access Token"*. Clique em **Salvar**. **4. Configurar o webhook na Meta** Copie a **URL de callback** exibida logo abaixo do campo Webhook Verify Token. No [Meta App Dashboard](https://developers.facebook.com/apps), abra **WhatsApp → Configuration → Webhook**, cole a URL, informe o mesmo Verify Token e assine o campo `messages`. A URL de callback é a mesma para todas as conexões Meta da conta. Na verificação do webhook, vale o Verify Token de qualquer conexão Meta ativa da conta. Com o webhook configurado: * Os [Logs de Mensagens](https://docs.octasend.com.br/plataforma/logs-de-mensagens.md) 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](https://docs.octasend.com.br/api-reference/consultar-logs.md), 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](https://docs.octasend.com.br/plataforma/chatbot.md). > [!WARNING] > > Sem o **App Secret**, a OctaSend não consegue validar a assinatura dos eventos da Meta e os descarta: os envios funcionam, mas o log não registra entrega, leitura nem falha de entrega, e as mensagens recebidas não chegam. ### 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. > [!NOTE] > > A seção só aparece se a integração com a Meta estiver ativa na plataforma e a sua conta puder usar a Meta Cloud API. Se você não vê **WhatsApp Business do celular** na aba **Conexões**, fale com a OctaSend. Para conectar, o seu usuário precisa da permissão de editar canais. ### Antes de começar | Requisito | Por quê | | - | - | | Número no aplicativo **WhatsApp Business** (não no WhatsApp comum), atualizado | A coexistência só existe para o app Business. Se o número está no WhatsApp comum, a janela da Meta pode pedir um código por SMS e tratar o número como cadastro novo. **Feche a janela sem digitar o código**: concluir tiraria o número do aplicativo. | | Celular com o aplicativo à mão | A Meta pede para confirmar a conexão pelo app (QR Code ou código mostrado na janela). | | Conta do Facebook com acesso ao portfólio de negócios do número | É com ela que você entra na janela da Meta. | | Número que não esteja conectado em outra conta OctaSend | Um mesmo número só pode estar em uma conta da plataforma. | ### Conectar **1. Abra o canal** Em **Configurações → Canais → WhatsApp**, na aba **Conexões**, procure a seção **WhatsApp Business do celular**. **2. Clique em Conectar número do WhatsApp Business** Abre a janela da Meta. Se aparecer **Não foi possível carregar a janela da Meta**, uma extensão ou a rede está bloqueando o Facebook: libere e clique em **Tentar de novo**. **3. Entre com o Facebook e escolha o número** Siga a janela da Meta, aceite as permissões e confirme a conexão no aplicativo WhatsApp Business do celular. **4. Escolha se compartilha o histórico** No próprio aplicativo, você decide se compartilha o histórico das conversas individuais (até os últimos 6 meses). Sem compartilhar, a conexão funciona do mesmo jeito, só sem o histórico. **5. Acompanhe a importação** O número aparece na lista de conexões. Enquanto importa, o item mostra **Importando contatos e histórico**, com a porcentagem. **Mantenha o WhatsApp Business aberto no celular até terminar.** No fim, o estado vira **Histórico importado**. 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](https://docs.octasend.com.br/plataforma/contatos.md). 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: | O que aparece | O que significa | O que fazer | | - | - | - | | **Importando contatos e histórico** | Importação em andamento. | Esperar, com o aplicativo aberto no celular. | | **A Meta ainda não recebeu o pedido para importar…** e **Tentar sincronizar de novo** | A Meta não aceitou o pedido na hora. | Clique em **Tentar sincronizar de novo**. Se a Meta aceitar só parte, tente de novo em alguns minutos. | | **Histórico importado** ou **Você optou por não compartilhar o histórico** | Tudo certo. | Nada. | | **O prazo para importar o histórico terminou** | Passaram 24 horas sem a Meta aceitar o pedido. O número continua funcionando. | Siga sem o histórico, ou desconecte no aplicativo e conecte de novo. | | **Reconectando ao WhatsApp desde…** | A Meta suspendeu o número por uma troca de aparelho ou reinstalação do aplicativo. Os envios ficam pausados. | Esperar, em geral alguns minutos. Depois de 1 hora, aparece **Reconectar**. | | **A conexão com a Meta expirou** e **Reconectar** | A Meta recusou o acesso (por exemplo, o aplicativo foi removido nas integrações do portfólio). | Clique em **Reconectar** e refaça a conexão. | 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](https://docs.octasend.com.br/plataforma/configuracoes.md). * **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](https://docs.octasend.com.br/plataforma/comunicacoes.md), 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](https://docs.octasend.com.br/api-reference/enviar-mensagens.md). * **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. > [!WARNING] > > A Meta pode restringir números que usam automação não oficial. Se isso acontecer, o aplicativo do celular e a API deixam de funcionar juntos. O cartão do número mostra o aviso **Este número está na API oficial e na Evolution ao mesmo tempo** até alguém clicar em **Entendi o risco** (fica registrado quem e quando). O aceite não bloqueia nada. * **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 > [accordion] A janela da Meta pede um código por SMS ou ligação > > Ela entrou no cadastro de um número novo, não na coexistência. Feche a janela **sem digitar o código**. Confira se o número está no aplicativo **WhatsApp Business** atualizado (não no WhatsApp comum) e conecte de novo. > [accordion] Este número não está no app WhatsApp Business > > A Meta não encontrou o número no aplicativo Business. Abra o número no aplicativo WhatsApp Business atualizado e conecte de novo. > [accordion] Este número já está conectado em outra conta > > O número tem conexão em outra conta da OctaSend. Fale com o suporte para confirmar o dono e liberar. > [accordion] A Meta não enviou todos os dados da conexão > > A janela não devolveu os dados a tempo. Conecte de novo; se repetir, fale com o suporte. > [accordion] A Meta limitou as solicitações por alguns instantes > > Espere alguns minutos e conecte de novo. > [accordion] Mensagens em dobro em Conversas > > O número está ligado pela Evolution e pela coexistência ao mesmo tempo, e a mesma mensagem não foi juntada. Fale com o suporte, que confere as duas conexões do número. > [accordion] A importação do histórico não termina > > Mantenha o WhatsApp Business aberto no celular. Se o item mostrar o pedido pendente, use **Tentar sincronizar de novo**. Se passou das 24 horas, veja o estado **O prazo para importar o histórico terminou**. ## 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](https://docs.octasend.com.br/plataforma/automacoes.md) ou por eventos de integrações como a [Nuvem Shop](https://docs.octasend.com.br/integracoes/nuvemshop.md) — que saem por uma conexão **Evolution** não são enviadas na hora: entram numa fila. [Campanhas](https://docs.octasend.com.br/plataforma/campanhas.md) 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. > [!WARNING] > > Numa falha de rede, uma nova tentativa pode repetir uma mensagem que já tinha chegado ao contato. 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 > [accordion] Telefone do destinatário > > Os envios de comunicações exigem `recipient.phone` com um **celular brasileiro**: DDD + 9 dígitos, com ou sem o `55` na frente (ex.: `+5511999990000` ou `11999990000`). Um número de 11 dígitos sem `+`, com o `9` logo depois do DDD, é tratado como celular brasileiro sem o código do país e recebe o `55` automaticamente, inclusive no DDD 55. Números fora desse formato falham com *"Invalid phone number: … Must be a valid Brazilian mobile number"*. > [accordion] Número sem WhatsApp > > Quando a OctaSend confirma que um número não tem WhatsApp, a mensagem fica **Ignorada** com o motivo *"Número não está registrado no WhatsApp"*, e os envios seguintes para esse número também são ignorados, em qualquer conexão da conta: > > * **Evolution** — o número é verificado antes do envio. Uma confirmação de que o número existe vale por 7 dias; a de que não existe não expira. > * **Meta** — o número é marcado quando a entrega falha com o erro de número inexistente da Meta (código 131026). A marca expira em 60 dias, ou antes, assim que esse número mandar uma mensagem para uma conexão Meta com webhook configurado. > [accordion] Tamanho do texto > > Cada mensagem de texto tem até **3.800 caracteres**, já com as variáveis substituídas. Acima disso, o texto é cortado e termina com `[…continua]`. > [accordion] Intervalo entre mensagens de uma sequência > > No editor, cada mensagem da sequência tem o campo **segundos antes da próxima mensagem**. A pausa vale entre envios imediatos (Meta), com no máximo 30 segundos por pausa e 60 segundos somados na sequência — passado esse total, as mensagens restantes saem sem pausa. Mensagens que vão para a fila da Evolution não aguardam esse intervalo: cada uma entra na fila separadamente e segue o ritmo dela, incluindo o **Intervalo mínimo entre envios** da conta, se houver. > [accordion] Contato descadastrado > > O descadastro vale para as mensagens de marketing: [campanhas](https://docs.octasend.com.br/plataforma/campanhas.md), [automações](https://docs.octasend.com.br/plataforma/automacoes.md) com gatilho **Segmento de contatos**, **Data de um campo do contato** ou **Chamada de API**, e o carrinho abandonado da integração da loja. Nelas, um contato descadastrado do WhatsApp não recebe a mensagem: o log fica **Ignorada** com o motivo *"Contato descadastrado"*. > > Mensagens transacionais continuam chegando: automações com gatilho **Chegou um pedido** ou **Evento de uma loja** e os demais eventos mapeados na integração da loja. Envios pela API também não são bloqueados, a menos que a chamada envie `respect_opt_out: true`. Veja [Contatos](https://docs.octasend.com.br/plataforma/contatos.md). > [accordion] Canal sem conexão > > Se o WhatsApp não estiver configurado na conta (nenhuma conexão ativa), o envio nem começa: o resultado vem como `skipped` com o erro `Canal não configurado`, e nada é registrado em **Logs**. ## 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](https://docs.octasend.com.br/plataforma/comunicacoes.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.