Conexões de WhatsApp

Visão geral

Uma conexão é um número de WhatsApp ligado ao ChatISP. Tudo o que chega a esse número vira conversa no painel de atendimento, e tudo o que a equipe, a IA ou os fluxos respondem sai por ele. A tela fica no menu Conexões, com o subtítulo Números de WhatsApp conectados ao sistema, por QR ou pela API oficial.

Existem dois transportes, que podem ser usados separados ou juntos no mesmo número:

Quando o mesmo número está conectado pelos dois transportes, o ChatISP trata o par como um canal só: uma conversa por cliente, mensagens sem duplicidade e a saída escolhida pela política que o administrador definir. Detalhes em QR e API oficial no mesmo número.

Quem pode usar

A tela exige a permissão Conexões de WhatsApp (descrição na tela de perfis: Conecta e gerencia os números de WhatsApp do sistema.). Quem não tem a permissão não vê o menu. Para definir em quais números cada atendente trabalha, veja Conexões por atendente.

Limite de números por plano Limite por plano

O plano contratado define quantos números de WhatsApp a instalação pode ter. A conta é feita por número: um número conectado por QR e pela API oficial ao mesmo tempo ocupa uma vaga só. No cabeçalho da tela aparece o medidor no formato 2 de 4 números de WhatsApp do seu plano; quando o teto é atingido, ele vira Teto do plano atingido e o botão Nova conexão deixa de aparecer.

Como a tela é organizada

Cada número aparece em um bloco. Um número com um transporte só aparece no bloco Conexão individual (Um canal de atendimento para este número.). Um número com QR e API oficial aparece no bloco Conexões vinculadas (QR Code e API oficial, um número e a mesma conversa.), com o telefone em destaque e os dois cartões lado a lado, o do QR primeiro.

Cada cartão mostra o nome que você deu à conexão, a etiqueta de estado, o tipo (Aplicativo (QR code) ou API oficial), o telefone, o nome da conta do WhatsApp (ou Sem nome) e os botões de ação. A tela se atualiza sozinha a cada 10 segundos, então uma desconexão feita pelo celular aparece sem precisar recarregar.

Escolher o tipo de conexão

Clique em Nova conexão. A janela pergunta Escolha como você quer conectar o WhatsApp: e oferece quatro caminhos:

QR code ou API oficial?

Conectar pelo QR code

O ChatISP vira um aparelho conectado do WhatsApp do número, como o WhatsApp Web. Vale tanto para o WhatsApp comum quanto para o WhatsApp Business.

1. Em Conexões, clique em Nova conexão e escolha Aplicativo (QR code). A conexão nasce com o nome WhatsApp (você renomeia depois em Editar) e a janela Conectar WhatsApp abre sozinha.
2. Aguarde o código aparecer. A janela mostra Aguardando a leitura do código...
3. No celular do número, abra o WhatsApp, toque em Dispositivos conectados (em Configurações ou no menu de três pontos, conforme o aparelho), depois em conectar um aparelho, e aponte a câmera para o código na tela.
4. Quando a leitura é aceita, aparece WhatsApp conectado com sucesso., a janela fecha e o cartão passa para Conectada, já com o telefone e o nome da conta.

O código do WhatsApp expira em pouco tempo. Se ninguém ler a tempo, a janela mostra O código expirou. Gere um novo para continuar. e o botão Gerar novo código. Não é preciso fechar a janela: clique no botão e leia o novo código.

Uma conexão QR já existente que está desconectada tem o botão Conectar no cartão, que abre a mesma janela de leitura.

O que acontece ao conectar

• As mensagens que chegarem ao número passam a entrar no ChatISP e seguem as regras de atendimento (fluxos, IA, fila e departamentos).
• O sistema confere se já existe uma conexão da API oficial com o mesmo telefone. Se existir, as duas viram Conexões vinculadas automaticamente.
• Se o número já atendeu antes por outra conexão que foi excluída, as conversas antigas desse número voltam a ficar ligadas a ele, abertas e encerradas. Veja Desconectar, excluir e reconectar.
• Se o nome da conta ainda não veio do WhatsApp na primeira leitura, o painel consulta de novo sozinho e preenche o cartão.

Servidor sem acesso ao WhatsApp

Se, ao pedir o código, aparecer O servidor não conseguiu falar com o WhatsApp. Verifique a saída do servidor para a internet e tente de novo., o problema é de rede, não do painel: o servidor não está conseguindo sair para a internet até os servidores do WhatsApp (firewall, rota ou DNS do provedor). Libere a saída do servidor e use Gerar novo código.

API oficial da Meta

A opção API oficial do WhatsApp conecta um número dedicado à plataforma oficial da Meta por um assistente com login do Facebook. Não é preciso copiar identificadores nem tokens: o assistente busca as contas, você escolhe o número e o ChatISP configura o resto, inclusive o recebimento das mensagens.

Requisitos do número

Antes de abrir o assistente, a tela mostra Requisitos da API oficial com o aviso Você precisa de um número dedicado, que não esteja em uso no WhatsApp do celular.

O botão Continuar com Facebook só é liberado depois que você marca Tenho um número dedicado que não está em uso no WhatsApp do celular. Se o número já está no aplicativo WhatsApp Business e você quer mantê-lo lá, use a coexistência.

Passo a passo do assistente

O assistente Conectar WhatsApp Business tem quatro etapas, indicadas no topo: Entrar, Autorizar, Escolher número e Pronto.

1. Clique em Continuar com Facebook. Uma nova aba abre com a página segura de conexão da Ravi Systems. O painel avisa: Abrimos uma aba segura da Ravi Systems para você entrar com o Facebook. Conclua a autorização por lá: assim que terminar, este assistente continua sozinho. Se o navegador bloquear a aba, use o botão Abrir a página de conexão.
2. Na aba nova, entre com o Facebook de quem administra a empresa no Gerenciador de Negócios da Meta e siga as telas da Meta: escolher ou criar o portfólio da empresa, a conta do WhatsApp Business e o número, e confirmar o número.
3. Ao terminar na aba, volte ao ChatISP. O assistente detecta a autorização sozinho, mostra Buscando suas contas do WhatsApp Business... e lista as contas e os números encontrados, cada número com o selo de qualidade da Meta.
4. Clique no número desejado e em Conectar número selecionado. O painel mostra Configurando a conexão..., cria a conexão, ativa o recebimento de mensagens na conta comercial e termina com WhatsApp conectado!.

A autorização precisa ser concluída em até 5 minutos depois de aberta a aba. Passado esse prazo, o assistente mostra A autorização não foi concluída a tempo. Tente novamente. e o botão Tentar novamente.

Mensagens de erro do assistente

Recebimento das mensagens (webhook)

Na API oficial, as mensagens dos clientes chegam porque a Meta chama um endereço do seu ChatISP (o Endereço do webhook, visível na janela Configurar API). O assistente inscreve esse endereço na conta comercial automaticamente. Para funcionar, a Meta precisa alcançar esse endereço pela internet, com HTTPS e certificado válido.

• Instalação própria Configure um domínio com certificado para o servidor (veja a página Servidor) antes de conectar a API oficial. Um servidor acessível só pela rede interna envia mensagens, mas não recebe.
• No ChatISP Cloud o endereço público já é fornecido pela Ravi Systems; não há nada a configurar.

Se a inscrição do recebimento falhar no fim do assistente, o assistente mostra o motivo devolvido pela Meta e o cartão da conexão fica em Configuração pendente. Corrija a causa (normalmente o endereço público do servidor) e use Configurar API e Salvar para tentar a inscrição de novo.

Número Business existente (coexistência)

A coexistência é o recurso da Meta que coloca na API oficial um número que já está no aplicativo WhatsApp Business, sem tirar o número do celular. O aplicativo continua funcionando e o ChatISP passa a falar pelo canal oficial do mesmo número.

1. Em Nova conexão, escolha Número Business existente.
2. Marque Tenho o número no aplicativo WhatsApp Business e o celular em mãos e clique em Continuar com Facebook.
3. Na aba da Ravi Systems, entre com o Facebook e siga as telas da Meta. Em um dos passos a Meta mostra um QR code: leia esse código no próprio aplicativo WhatsApp Business do celular, como a tela da Meta orientar.
4. Concluída a autorização, o ChatISP normalmente já recebe o número escolhido e finaliza sozinho. Se não receber, ele mostra a lista de contas para você escolher o número, como no fluxo comum.

Em número com coexistência, as chamadas de voz do canal oficial não ficam disponíveis: a Meta só libera chamadas pelo canal oficial em número dedicado, sem o aplicativo. O cartão mostra Chamadas indisponíveis com a explicação. Para chamadas nesse número, use a perna QR (veja Chamadas de voz e vídeo).

Configuração manual da API oficial

Para quem já tem um aplicativo e as credenciais da Meta (por exemplo, um número já operado por outro sistema), a opção Configuração manual cria uma conexão da API oficial chamada WhatsApp Business e abre a janela Configurar API. A mesma janela abre pelo botão Configurar API no cartão de qualquer conexão da API oficial.

Ao clicar em Salvar, o ChatISP testa as credenciais na hora e, se o token funcionar, inscreve o recebimento na conta comercial. Os avisos possíveis:

Testar conexão

O botão Testar conexão (cartões da API oficial com número configurado) repete a verificação a qualquer momento: confere as credenciais, atualiza telefone e nome da conta, mede na Meta o estado das chamadas e se o número está em coexistência, refaz a vinculação com a conexão QR do mesmo número, se houver, mede a saúde da conta na Meta (bloqueio, limite por verificação) e confere a inscrição do recebimento, refazendo-a quando preciso (ver Saúde da conta na Meta).

QR e API oficial no mesmo número

Quando uma conexão QR e uma conexão da API oficial têm o mesmo telefone, o ChatISP as vincula sozinho (com ou sem o nono dígito) e passa a tratá-las como um único canal de atendimento. É o cenário de coexistência: o número está no aplicativo WhatsApp Business, conectado ao ChatISP pelo QR e também pela API oficial.

Como o par se comporta

• Uma conversa por cliente. A mensagem do cliente chega pelos dois canais, mas entra uma vez só no painel. Recibos de entrega e leitura, citações e reações casam com a mensagem certa, venham pelo canal que vierem.
• Um canal em todas as telas. Em filtros, seletores, ficha do atendente e demais listas, o número aparece uma vez. Só a tela de Conexões mostra os dois cartões, dentro do bloco Conexões vinculadas, porque é nela que se gerencia cada transporte.
• O par sobrevive à queda do QR. Se o celular desconectar, a API oficial continua atendendo as conversas do número. Só um número diferente lendo o QR desfaz o vínculo.
• Vaga única no plano. O par conta como um número no limite do plano.
• Recursos do aplicativo preservados. As conversas novas ficam ligadas à perna QR, que traz foto e nome do contato e os recursos de editar, apagar para todos e reagir.

Por onde sai cada mensagem

A escolha do canal segue a política da aba Canais e franquia em Configurações. Na configuração de fábrica (Usar as duas conexões com Priorizar o QR e menus Enquanto houver franquia grátis):

Os modos Só a API oficial e Só o QR são estritos: o sistema usa apenas o canal escolhido, sem recorrer ao outro. Todas as opções estão explicadas em Configurações, aba Canais e franquia.

Janela de 24 horas e modelos aprovados

Na API oficial vale a regra da Meta: a empresa pode mandar mensagem livre (texto, mídia, menu) apenas dentro de 24 horas contadas da última mensagem do cliente. Cada nova mensagem do cliente reabre a janela por mais 24 horas. Fora dela, só chegam ao cliente os modelos de mensagem aprovados pela Meta.

O que o atendente vê

Em uma conversa de número que tem só a API oficial, com a janela fechada, a caixa de mensagem fica bloqueada com o texto Fora da janela de 24 h: envie um modelo e a barra A janela de 24 horas da API oficial fechou: até o cliente responder, só um modelo aprovado chega a ele. O botão Enviar modelo abre a lista de modelos aprovados, com os campos das variáveis. As notas internas continuam livres. Se a Meta recusar uma mensagem por janela fechada, o painel avisa Fora da janela de 24 horas da API oficial. Envie um modelo aprovado.

Em número com QR (sozinho ou vinculado à API), nada disso trava: o texto livre sai pelo QR.

Modelos da conta

Os modelos são criados e aprovados no Gerenciador do WhatsApp da Meta; o ChatISP mantém uma cópia dos modelos da conta para usar no painel, na régua de cobrança e nas campanhas. No cartão da API oficial (com a identificação da conta comercial preenchida), o botão Modelos abre a lista:

• Cada modelo mostra nome, idioma, situação na Meta (por exemplo APPROVED para aprovado), categoria e o texto com as variáveis {{1}}, {{2}}...
• Sincronizar com a Meta busca a lista atualizada (a mensagem confirma quantos modelos foram sincronizados). Modelos apagados na Meta somem da lista.
• Gerenciar na Meta abre o gerenciador de modelos da sua conta comercial, onde se cria e se submete um modelo à aprovação.

Modelos de início de conversa

Nem todo modelo tem o mesmo uso: alguns são feitos para envio em massa, outros para puxar o cliente para uma conversa. Na página Templates Meta, cada cartão tem o interruptor Início de conversa, que grava ao clicar. Ligado, o modelo aparece ao iniciar uma conversa pelo painel e no botão Enviar modelo quando a janela de 24 horas fecha. Desligado, ele fica para as campanhas e a régua de cobrança e para as promoções. Enquanto nenhum modelo da conexão estiver ligado, todos aparecem em todo lugar. O filtro Início de conversa mostra só os marcados, e a marca acompanha a cópia ao duplicar um modelo.

Quando a lista local está vazia, o painel busca os modelos na Meta sozinho na primeira vez que alguém tenta enviar um. Para o envio pelo painel valem os modelos aprovados sem cabeçalho de mídia (imagem, vídeo ou documento no cabeçalho), porque o painel preenche apenas as variáveis do texto.

Franquia e custos da API oficial

A Meta cobra por mensagem enviada pela API oficial, inclusive dentro da janela de 24 horas, e libera 1.000 mensagens de serviço grátis por mês em cada número. Modelos são sempre pagos. Mensagens enviadas pelo QR não têm custo. O ChatISP acompanha esse consumo e deixa o administrador decidir como gastar a franquia.

Gestor de consumo no cartão

Cada cartão da API oficial com número configurado mostra o quadro Franquia da Meta:

• A barra e a legenda {usado} de {limite} mensagens grátis usadas no mês, com o total em números (por exemplo, 640 / 1.000). A partir de 80% do limite o quadro muda de cor como alerta.
• Quando a franquia estoura, a barra ganha um trecho pago e aparece N mensagens além da franquia · estimativa a pagar à Meta: R$ X. A estimativa usa o preço por mensagem configurado e a cotação do dólar mais recente conhecida pelo sistema (sem cotação, aparece em dólar).
• Modelos enviados (sempre pagos): N mostra quantos modelos saíram no mês.
• O link Configurar leva direto à aba Canais e franquia em Configurações.

Política de uso (resumo)

Na aba Canais e franquia de Configurações, o administrador escolhe em cartões clicáveis, que salvam no clique:

Uma faixa Na prática resume em uma frase o efeito da combinação escolhida. A explicação completa de cada opção está em Configurações.

As políticas de canal afetam números vinculados (QR e API no mesmo número). Num número que só tem a API oficial, todas as mensagens saem por ela e consomem a franquia.

Recursos do cartão da conexão

Além do estado e das ações principais, o cartão concentra ajustes que valem número a número.

Cliente digitando ao vivo (QR)

Disponível nos cartões QR, com a etiqueta Ativado ou Desativado e o botão para alternar. A mudança vale na hora, sem reconectar (Pronto, a mudança já vale para este número.). Vem ativado.

Com as chamadas de voz ativas no número, o celular continua sem tocar mensagens mesmo com o recurso desativado, porque a linha de chamadas precisa ficar disponível para receber ligações.

Chamadas de voz Recurso de plano

Quando o serviço de chamadas está disponível na instalação e no plano, cada cartão ganha o quadro Chamadas de voz, com o estado e o botão Ativar chamadas ou Desligar chamadas:

• Na perna QR, as chamadas usam um segundo aparelho conectado do mesmo número: ao ativar, lê-se outro QR code no mesmo celular. O código lido no celular de outro número é recusado e desfeito na hora. A conexão de mensagens precisa estar conectada antes.
• Na API oficial, não há aparelho: o recurso é ligado no próprio número, na Meta, e só existe em número dedicado (sem coexistência).

Desligar as chamadas não afeta as mensagens. O passo a passo completo está em Chamadas de voz e vídeo.

Base de conhecimento

Todo cartão tem o quadro Base de conhecimento com a etiqueta da base que a assistente usa neste número e o botão Trocar, que abre Base de conhecimento deste número: tocar numa base grava na hora e vale também para o canal gêmeo do mesmo número. Sem base, a etiqueta fica em alerta (Nenhuma) e o botão vira Escolher base; nesse estado a assistente atende sem planos, condições e respostas cadastradas. Com uma só base na instalação a conexão nova já nasce atendida por ela. Veja Várias bases: uma por empresa.

Botões do cartão

Saúde da conta na Meta

O cartão de cada conexão da API oficial mostra, além do estado, o que a própria Meta diz sobre a conta. O painel consulta a Meta de hora em hora (a cada 5 minutos quando há problema) e sempre que você clica em Testar conexão.

O botão Forma de pagamento fica sempre no rodapé do cartão da API oficial, mesmo sem aviso, para cadastrar ou trocar o cartão na Meta a qualquer momento.

Estados da conexão

A etiqueta no topo do cartão mostra o estado atual. Nas conexões QR, o estado é conferido com o serviço do WhatsApp a cada atualização da tela, então reflete o que está acontecendo de fato.

O quadro de chamadas tem estados próprios (Chamadas desligadas, Aguardando leitura, Chamadas ativas, Chamadas fora do ar, Chamadas indisponíveis), independentes do estado das mensagens.

Conexões por atendente

Em provedores com mais de um número (por exemplo, um para suporte e outro para comercial, ou um por cidade), o gestor pode definir em quais números cada atendente trabalha.

1. Abra a tela Atendentes e edite o atendente.
2. No campo Conexões, marque os números em que ele atua. A dica da tela resume a regra: O atendente vê e recebe apenas as conversas e chamadas das conexões marcadas. Nenhuma marcada: atua em todas.
3. Salve. A coluna Conexões da lista de atendentes mostra a escolha (Todas quando nenhuma está marcada).

O que a restrição alcança

• Lista de conversas, abertura de conversa e início de conversa nova pelo painel: só nos números marcados.
• Distribuição automática (roleta) e avisos de fila e de transferência: o atendente só é escolhido ou avisado para conversas dos seus números.
• Chamadas de voz: só as dos seus números.
• Automação de envios: régua de cobrança e campanhas só podem ser criadas nos números do atendente.
• Transferir ou compartilhar uma conversa com quem não atua naquele número é recusado com Este atendente não atua na conexão desta conversa.; a lista de destinos já mostra apenas quem pode receber.

A restrição vale para qualquer perfil de acesso, inclusive quem tem permissão de ver todas as conversas: quem marcou as caixas decidiu onde o atendente atua. Números vinculados (QR e API) aparecem como uma entrada só, e marcar o número cobre os dois transportes. Conversas antigas sem conexão (de um número excluído) não são restringidas. Contatos e relatórios seguem apenas as permissões do perfil.

Mais sobre a ficha do atendente em Usuários e perfis.

Desconectar, excluir e reconectar o mesmo número

O histórico de atendimento pertence ao número, não à conexão. Trocar o celular, trocar o QR pela API oficial ou recriar a conexão não apaga nada.

Desconectar (QR)

Desconectar remove o ChatISP dos aparelhos conectados do WhatsApp e apaga a sessão guardada, para que ela não volte sozinha. Se as chamadas de voz estavam ativas no número, o aparelho de chamadas sai junto. O cartão continua na tela com o telefone registrado, pronto para Conectar de novo. Num número vinculado, a API oficial segue atendendo enquanto o QR está fora.

Excluir

Excluir pede a confirmação Excluir esta conexão? As conversas registradas serão mantidas e vinculadas automaticamente quando o mesmo número estiver conectado novamente, por QR Code ou API oficial. A base de conhecimento e os fluxos deste número também voltam sozinhos nessa hora. Ao confirmar:

• Se for QR conectado, o aparelho é desvinculado do WhatsApp antes; se as chamadas estavam ativas, o aparelho de chamadas também.
• Protocolos, mensagens, eventos, notas internas, responsáveis, contatos e chamadas antigas são preservados.
• Campanhas que estavam enviando por essa conexão ficam pausadas.
• A base de conhecimento não é apagada: ela continua na tela Base de conhecimento, em espera. O ChatISP guarda, pelo número, qual base e quais fluxos atendiam essa conexão.
• Se a conexão gêmea (o outro transporte do mesmo número) continua conectada, ela assume as conversas imediatamente.
• Sem nenhum transporte do número, as conversas continuam disponíveis para consulta e notas internas, mas a caixa de mensagem fica bloqueada com Aguardando conexão do mesmo número.

Reconectar o mesmo número

Quando o mesmo número volta a ser conectado, por QR ou pela API oficial, a base de conhecimento e os fluxos que serviam o número voltam sozinhos (desde que a base continue ativa e a conexão nova ainda não tenha uma base escolhida), e o ChatISP religa automaticamente todas as conversas desse número, abertas e encerradas, e a caixa de mensagem se libera sozinha nas conversas abertas, sem recarregar a página. Isso acontece inclusive se a primeira mensagem chegar antes de alguém abrir a tela de Conexões.

Levar o número para outro sistema

A conta conectada pela API oficial pertence à sua empresa, não à Ravi Systems. O número, a conta do WhatsApp Business e os modelos de mensagem ficam no seu portfólio empresarial da Meta e podem ser usados em qualquer sistema homologado por ela. O ChatISP não cria nenhuma barreira para a saída: queremos clientes pela qualidade do serviço, nunca por prisão técnica.

Dados da API

No cartão de uma conexão pela API oficial, o botão discreto Dados da API abre a janela com tudo o que o novo fornecedor pode pedir, cada item com o botão Copiar:

• Número de WhatsApp e Nome verificado;
• Identificação do número;
• Conta do WhatsApp Business e Identificação da conta comercial;
• Portfólio empresarial e Identificação do portfólio.

A janela abre na hora com o que o painel já sabe e, em seguida, confere os dados na Meta (Conferindo na Meta...). O token de acesso não aparece de propósito: ele é ligado a esta instalação e não funciona em outro sistema. O novo fornecedor gera o dele ao conectar a mesma conta.

Passo a passo da migração

1. Se quiser guardar o histórico de conversas, faça o backup do ChatISP em Configurações. O histórico fica com você; nenhum sistema o importa pela Meta.
2. No novo sistema, conecte o número pelo cadastro da Meta (o mesmo login no Facebook usado aqui). Entre com a conta que administra o seu portfólio e escolha a mesma conta do WhatsApp Business e o mesmo número. Os modelos aprovados acompanham a conta.
3. Volte ao ChatISP, abra Dados da API e clique em Desvincular da Ravi Systems. O ChatISP cancela o recebimento das mensagens na Meta, apaga a credencial guardada e remove a conexão. O histórico de atendimento fica guardado, como em Excluir.
4. Se preferir fazer pela Meta, em Configurações do negócio, Integrações, Apps conectados, remova o app do ChatISP. Depois use Desvincular da Ravi Systems ou Excluir no painel.

Boas práticas

• Dê nomes claros. Use Editar para nomear cada conexão pelo papel (por exemplo, "Suporte" e "Comercial"). É esse nome que a equipe vê nos filtros, nas conversas e na automação de envios.
• Mantenha o celular do QR ligado e com internet. O WhatsApp pode desconectar aparelhos vinculados quando o celular principal fica muito tempo sem uso, então use o WhatsApp no celular de tempos em tempos.
• Mantenha o aplicativo do WhatsApp atualizado no celular do número, principalmente na coexistência, que exige o WhatsApp Business atualizado.
• Prefira a combinação QR e API oficial no mesmo número quando quiser menus com botões e o cartão de cobrança sem gastar a franquia com o atendimento comum.
• Acompanhe o gestor de consumo no cartão da API oficial e, se quiser margem, diminua a franquia mensal em Configurações para o sistema poupar a API antes do limite real.
• Crie os modelos com antecedência no Gerenciador do WhatsApp da Meta, porque a aprovação não é imediata, e sincronize em Modelos.
• Prepare o endereço público antes da API oficial na instalação própria: domínio e certificado configurados em Servidor.
• Exclua sem medo quando precisar trocar o transporte. O histórico fica guardado e volta sozinho quando o mesmo número for conectado.

Problemas comuns