Índice da documentação
Conectar o WhatsApp
Aqui está tudo para ligar um número ao agente: qual provedor escolher, o passo a passo de cada um, o que cada status significa, as opções do canal e o que fazer quando o agente para de responder.
Antes de começar
Três coisas evitam a maior parte dos problemas de conexão:
- Use um número dedicado ao agente. Se o mesmo número estiver em outro sistema de automação ou sendo usado por outra ferramenta ao mesmo tempo, uma das sessões cai — e a que cai costuma ser a do Hub, sem aviso de erro.
- Deixe o celular com WhatsApp instalado e com internet. O WhatsApp desvincula os aparelhos conectados depois de um longo período sem atividade do celular principal. Quando isso acontece, é preciso ler um novo QR Code.
- Crie o canal dentro da conta do agente. Cada canal pertence a um agente. Um número conectado a um agente não responde por outro.
Evolution API ou Z-API
O Hub conversa com o WhatsApp por um destes dois provedores. A diferença está em onde o número é pareado.
| Evolution API | Z-API | |
|---|---|---|
| Como pareia | QR Code lido direto no painel do Genius Hub. | Pareamento feito no painel da própria Z-API. |
| Conta externa | Não é preciso ter conta em outro serviço. | Exige conta e instância próprias na Z-API. |
| Webhook | Configurado automaticamente pelo Hub. | Você copia o webhook exibido no Hub e cola no painel da Z-API. |
| Quando escolher | Quer conectar em poucos minutos, sem outra conta. | Já usa a Z-API para outras operações. |
Não sabe qual escolher?
Use a Evolution API. É o caminho mais curto: o QR Code aparece no próprio painel e não há webhook para configurar à mão.
Conectar pela Evolution API
- No painel, abra WhatsApp e clique em Criar canal.
- Escolha Evolution API, selecione o agente e clique em Criar e gerar QR Code.
- No celular que vai atender, abra o WhatsApp e vá em Aparelhos conectados → Conectar aparelho.
- Aponte a câmera para o QR Code da tela. O status muda para Conectado em alguns segundos.
- Mande uma mensagem de outro número e confira a resposta em Conversas.
O QR Code expira
Ele se renova sozinho a cada cerca de 30 segundos. Se a tela mostrar que está vencido, clique em Gerar novo QR e leia o novo código.
Conectar pela Z-API
Na Z-API, o número é pareado no painel deles. No Hub você só informa a instância e acompanha o status.
- No painel da Z-API, crie a instância e pareie o número lendo o QR Code por lá.
- No Hub, em WhatsApp → Criar canal, escolha Z-API, selecione o agente e informe as credenciais da instância. O Hub valida as credenciais antes de salvar.
- Abra o canal e clique em Ver status e webhook. Copie o endereço de webhook exibido.
- Cole esse endereço no painel da Z-API, no campo de webhook de mensagens recebidas da sua instância. Sem isso o agente recebe nada, mesmo com o número conectado.
- Mande uma mensagem de outro número e confira a resposta em Conversas.
Número conectado não é o mesmo que webhook configurado
Um canal Z-API pode aparecer como conectado e mesmo assim não entregar mensagens: se o webhook não foi colado na Z-API, as mensagens chegam ao serviço deles e nunca chegam ao agente. Confira o webhook antes de procurar outro problema.
Status da conexão
O status aparece no cartão de cada canal, na tela WhatsApp.
| Status | O que significa | O que fazer |
|---|---|---|
| Aguardando leitura do QR | O canal foi criado, mas o número ainda não está pareado. | Leia o QR Code no celular. Se ele venceu, gere um novo. |
| Conectado | O número está pareado e o agente recebe e responde mensagens. | Nada. Para testar, mande uma mensagem de outro número. |
| Desconectado | A sessão caiu ou foi encerrada. O agente não recebe mensagens enquanto estiver assim. | Reconecte lendo um novo QR Code. Se o número já estava pareado em outro lugar, desconecte-o de lá primeiro. |
Desconectar e trocar de número
Para trocar o número de um canal, use Desconectar no próprio canal e depois crie o pareamento com o novo aparelho.
Comportamento do canal
Estas opções ficam na configuração do canal de WhatsApp de cada agente. Os valores padrão são os recomendados para a maioria dos atendimentos.
| Opção | O que faz | Padrão |
|---|---|---|
| Ignorar grupos | O agente não responde mensagens de grupos. | Ligado |
| Manter online | O número aparece como online enquanto o agente está ativo. | Ligado |
| Marcar mensagens como lidas | O Hub marca como lida a mensagem recebida, no WhatsApp do cliente. | Desligado |
| Recusar chamadas | Rejeita as chamadas recebidas pelo número. | Desligado |
| Mensagem para chamadas | Texto enviado ao cliente quando uma chamada é recusada. Ex.: “Não atendemos ligações; pode escrever por aqui.” | Vazio |
Recusar chamadas
Ligue essa opção se o número for usado só para mensagens. Preencha a mensagem para chamadas, para que o cliente saiba por onde falar.
Passar para um atendente
Há três situações em que a conversa sai do agente e vai para uma pessoa. Em todas elas a conversa aparece em Conversas marcada como aguardando, e o agente fica em silêncio nela até alguém responder.
- O cliente pede uma pessoa. Com o recurso Chamar Pessoa / Equipe ligado, o agente transfere quando o cliente pede atendente ou quando o assunto está fora do escopo dele.
- O limite de interações foi atingido. Se o agente tiver um limite de interações configurado, ao chegar nele a conversa é encaminhada a uma pessoa.
- Uma pessoa respondeu pelo celular. Quando alguém da equipe responde direto pelo aparelho conectado, o agente para de responder naquele contato.
Voltar a conversa para a IA
Na conversa, use Devolver para IA quando o atendimento humano terminar. Use Assumir conversa para tomar o controle quando quiser responder você mesmo. Há também um tempo de silêncio configurável: se a equipe não responder dentro desse prazo, a conversa volta sozinha para o agente.
Enquanto a conversa estiver assumida ou aguardando atendimento, o agente não envia nada para aquele cliente. Se parecer que ele “sumiu”, confira se a conversa está nessa situação antes de procurar outro problema.
O agente não responde
Procure pelo sintoma. Cada linha indica onde olhar primeiro, na ordem em que vale verificar.
| Sintoma | Causa mais provável | O que fazer |
|---|---|---|
| Nenhuma mensagem chega ao agente | O status não está Conectado, ou a sessão caiu. | Confira o status no canal. Se estiver desconectado, reconecte lendo um novo QR Code. |
| Conectado, mas a mensagem não chega (Z-API) | O webhook não foi colado na Z-API, ou foi colado no campo errado. | Copie de novo o webhook em Ver status e webhook e cole no campo de mensagens recebidas. |
| A conexão cai sozinha | O número está pareado em outro sistema, ou o celular ficou muito tempo sem uso. | Remova o número do outro sistema e reconecte. Mantenha o celular ativo com internet. |
| O QR Code não aparece ou vence antes de ler | O QR Code se renova a cada cerca de 30 segundos. | Clique em Gerar novo QR e leia o código logo em seguida. |
| O agente responde, mas em uma conversa específica não | A conversa está assumida por uma pessoa ou aguardando atendimento. | Abra a conversa em Conversas. Use Devolver para IA se o atendimento humano terminou. |
| Ele não responde em grupos | A opção Ignorar grupos está ligada, que é o padrão. | Só desligue se quiser que o agente participe de grupos, e avalie o risco de ele responder fora de hora. |
Se nada disso resolver
Verifique o status na tela WhatsApp e a última mensagem na conversa. Essas duas informações, junto com o nome do agente, são o que a equipe de suporte precisa para investigar. Fale pela página de contato.
Dúvidas frequentes
Posso responder pelo celular e deixar o agente cuidar do resto?
Sim. Quando alguém responde pelo aparelho conectado, o agente para de responder naquela conversa, para não atrapalhar. Ele volta a atender quando você usar
Devolver para IA, ou quando o tempo de silêncio configurado passar.O agente consegue enviar fotos, catálogos e documentos?
Sim, desde que o arquivo esteja na base de conhecimento do agente. Documentos enviados como arquivo ficam disponíveis para ele mandar ao cliente. Texto colado na base não tem o que ser enviado. Veja a base de conhecimento.
Posso usar o mesmo número em dois agentes?
Não. Cada número conectado pertence a um canal, e cada canal a um agente. Para atender duas operações, use dois números, cada um com o seu agente.
O agente responde mensagens de áudio e imagem?
Ele entende o conteúdo dessas mensagens e responde de acordo. Teste com um áudio e uma imagem reais antes de publicar, como indicado em testar antes de publicar.
Preciso deixar o computador ligado para o agente funcionar?
Não. Depois de conectado, o agente responde sem nada aberto no seu computador. O que precisa ficar ativo é o celular com WhatsApp instalado e com internet, como descrito em antes de começar.
Quanto custa cada mensagem respondida?
O custo é medido em créditos, e não em mensagens. A tela de Consumo mostra quanto cada agente gastou por período. O que mais pesa é o material marcado como “por completo” na base, porque ele é enviado de novo em cada resposta.
Próximos passos
Com o número conectado, o próximo passo é deixar o agente pronto para o atendimento: criar e configurar o agente.