Canal WhatsApp

O canal WhatsApp permite que usuários enviem mensagens para o ThairaAI pelo WhatsApp e recebam respostas da IA — usando os mesmos backends de IA disponíveis no app desktop.

Arquitetura

O ThairaAI se conecta ao WhatsApp através de um servidor whatsapp-api separado (baseado no CodeChat / Baileys). O ThairaAI nunca se conecta diretamente ao WhatsApp.

WhatsApp ↔ whatsapp-api (:8084) ↔ ThairaAI (:25809)

• Entrada: o whatsapp-api encaminha mensagens recebidas ao ThairaAI via webhook
• Saída: o ThairaAI chama a API REST do whatsapp-api para enviar respostas

Pré-requisitos

1. Uma instância do whatsapp-api em execução (porta padrão 8084)
2. Uma conta WhatsApp conectada a essa instância
3. O app desktop ThairaAI

Configuração

Vá em Configurações → Canais → WhatsApp e preencha:

Campo	Descrição	Padrão
URL do Servidor	URL base do seu servidor whatsapp-api	http://localhost:8084
Nome da Instância	Nome da instância WhatsApp no whatsapp-api	thairaai
Chave API Global	AUTHENTICATION_GLOBAL_AUTH_TOKEN do .env do whatsapp-api	descoberta automática

Dica

Se o whatsapp-api estiver em um diretório irmão ao ThairaAI, a chave API é descoberta automaticamente no arquivo .env — sem necessidade de configuração manual.

Clique em Salvar e Ativar. O ThairaAI irá:

1. Iniciar automaticamente seu servidor HTTP interno (se ainda não estiver rodando para o WebUI)
2. Criar ou retomar a instância no whatsapp-api
3. Registrar a URL do webhook no whatsapp-api automaticamente

Pareamento de usuários

Usuários do WhatsApp precisam ser aprovados antes que a IA responda.

1. Envie qualquer mensagem para o número do WhatsApp
2. O ThairaAI responde com um código de pareamento de 6 dígitos
3. Abra Configurações → Canais → WhatsApp → Solicitações Pendentes no app desktop
4. Clique em Aprovar

Após aprovação, todas as mensagens desse número recebem respostas da IA.

Tipos de mensagem suportados

Tipo	Como é tratado
Texto	Encaminhado à IA diretamente
Imagem	Baixada para um arquivo temporário; a IA recebe o caminho local e a legenda como texto
Mensagem de voz	Convertida de OGG/Opus para WAV, transcrita via Fala para Texto, e encaminhada como texto
Arquivo de áudio	Mesmo pipeline das mensagens de voz

Dica

A transcrição de voz e áudio requer que o recurso de Fala para Texto esteja ativo. Acesse Configurações → Ferramentas → Fala para Texto e escolha um provedor. A opção Whisper Local roda inteiramente na sua máquina, sem necessidade de chave de API.

Comportamento das conversas

• Respostas: o ThairaAI envia respostas como novas mensagens no WhatsApp (o WhatsApp não suporta edição de mensagens)
• Indicador de processamento: uma mensagem ⏳ Thinking... é enviada enquanto a IA processa; a resposta final chega como uma mensagem separada
• Histórico: o contexto da conversa é preservado durante a sessão. Se o ThairaAI reiniciar ou a sessão ficar inativa por mais de 5 minutos, as mensagens anteriores são injetadas automaticamente como contexto na próxima requisição
• Somente texto: o WhatsApp exibe apenas texto simples — formatação HTML é removida automaticamente

Selecionando o backend de IA

Em Configurações → Canais → WhatsApp, escolha o agente de IA e o modelo usado nas conversas do WhatsApp. Essa configuração é independente do chat no app desktop.

Desativando

Desative o canal nas Configurações. O ThairaAI irá cancelar o registro do webhook no whatsapp-api automaticamente.

---

Aba WhatsApp Web

Ao abrir uma conversa do WhatsApp no app desktop, a área de conversa exibe duas abas:

Aba	Conteúdo
Chat	O chat com o assistente de IA — mensagens enviadas e recebidas pelo canal WhatsApp
WhatsApp Web	Um navegador WhatsApp Web embutido (web.whatsapp.com)

O WhatsApp Web roda como um singleton global: o navegador embutido nunca é destruído ao trocar de conversa ou navegar para outra parte do app. Leia o QR code uma vez — a sessão persiste enquanto a janela do app estiver aberta (e entre reinicializações, já que o armazenamento do navegador é isolado em persist:whatsapp-web).

Dica

Trocar entre conversas do WhatsApp mantém a aba do WhatsApp Web aberta e já conectada. Não é necessário ler o QR code novamente.

---

Modo Profissional Enterprise

O Modo Profissional inverte o paradigma: em vez de você conversar com seu próprio assistente, seus clientes enviam mensagens para o seu número WhatsApp e a IA responde automaticamente em seu nome — sem necessidade de pareamento manual.

Isso é ideal para profissionais que precisam atender clientes por WhatsApp: terapeutas, consultórios, advogados, clínicas e qualquer negócio que receba contatos pelo app.

Cuidado

O Modo Profissional é uma funcionalidade Enterprise. Qualquer pessoa que enviar uma mensagem para o número configurado receberá respostas automáticas da IA sem aprovação prévia. Configure com atenção.

Como ativar

Opção 1 — Tela inicial: clique no pill de toggle na barra de ações rápidas. O ícone do WhatsApp fica verde quando ativo. Ao ativar, você recebe uma confirmação no próprio WhatsApp.

Opção 2 — Configurações: acesse Configurações → Canais → WhatsApp → Modo Profissional e ative o toggle.

Campos de configuração

Campo	Descrição	Exemplo
Nome do consultório/empresa	Identificação do negócio injetada no contexto da IA	Clínica Silva Psicologia
Nome do profissional	Nome usado pela IA ao se referir ao responsável	Dra. Ana Silva
Horário de atendimento	Informado à IA para comunicar disponibilidade	Seg–Sex, 9h–18h
Mensagem de boas-vindas	Primeira mensagem enviada a novos contatos	(padrão automático se vazio)

O que muda com o Modo Profissional ativo

Comportamento	Modo padrão	Modo Profissional
Novo contato	Recebe código de pareamento	Recebe mensagem de boas-vindas e já conversa com a IA
Aprovação	Manual pelo proprietário	Automática
Contexto da IA	Assistente pessoal	Recepcionista do consultório com nome, horário e identidade configurados

Preset de recepcionista

Para aproveitar ao máximo o Modo Profissional, selecione o agente Therapy Receptionist em Configurações → Canais → WhatsApp → Agente. Esse preset é especializado em:

• Verificar a autenticação do Google Calendar antes de qualquer ação
• Consultar disponibilidade e oferecer horários ao cliente
• Criar agendamentos somente após confirmação explícita
• Nunca oferecer orientação clínica ou psicológica
• Responder no idioma do cliente

A IA também recebe a data e a hora atuais em toda mensagem, então referências relativas como “amanhã às 10h”, “próxima segunda” ou “daqui a 2 dias” são resolvidas sem precisar perguntar ao cliente o ano, dia da semana ou mês.

Dica

O preset de recepcionista usa as ferramentas do Google Calendar (google_list_events, google_create_event). Configure a integração com o Google em Configurações → Integrações → Google antes de usar o agendamento automático.

Agenda de Atendimentos

Para impedir que a IA recepcionista leia (ou grave por engano) na sua agenda pessoal do Google, o ThairaAI usa uma agenda dedicada para todos os agendamentos de clientes.

Acesse Configurações → Integrações → Google (o painel aparece assim que sua conta Google estiver conectada) e use a seção Agenda de Atendimentos:

Ação	Quando usar
Criar agenda dedicada	Primeira configuração — cria uma agenda nova chamada ThairaAI — Agendamentos (<seu nome>)
ou escolher existente…	Se você já tem uma agenda usada para atendimentos (ou uma criada num computador anterior), selecione no dropdown
Limpar	Desvincula a agenda — a IA volta a responder “agendamento temporariamente indisponível”

O dropdown só lista agendas onde você tem permissão de escrita. Agendas com nome ThairaAI ou Agendamento aparecem no topo.

O que a IA pode e não pode ver

Configuração	IA lista eventos?	IA cria eventos?	IA vê sua agenda pessoal?
Sem agenda configurada	Não	Sim, em primary (legado)	Limitado — somente escrita
Agenda dedicada configurada	Sim, só a dedicada	Sim, só a dedicada	Não

Quando uma agenda dedicada está definida, o system prompt explicitamente proíbe a IA de tocar na agenda primária, no Gmail ou nos contatos. Em perguntas sobre disponibilidade, a IA descreve horários ocupados em termos genéricos (“esse horário não está disponível”) e nunca revela títulos, nomes ou convidados de outros agendamentos.

Suas próprias consultas também funcionam. Quando você manda mensagem para seu próprio assistente ThairaAI (“quais consultas tenho hoje?”, “lista os agendamentos da próxima semana”), a IA usa a agenda dedicada por padrão — então você vê exatamente o que a recepcionista agendou, sem o LLM precisar ler sua agenda pessoal do Google. Se quiser olhar a agenda pessoal, basta pedir explicitamente (“olha na minha agenda pessoal”) — as ferramentas aceitam um override explícito.

Cuidado

Se você apagar a agenda dedicada direto pelo Google Calendar, o ThairaAI ainda tem o ID guardado. Clique em Limpar no painel antes de criar uma nova, ou use o dropdown ou escolher existente… para revincular.

---

Para detalhes de implementação interna, consulte Arquitetura do Canal WhatsApp.