Modo de Callback do WeCom — Aplicativos Personalizados

Pense nisso como configurar uma caixa de correio dedicada para seu assistente de IA — em vez de ele ficar escondido em conversas de grupo, você dá a ele uma mesa própria onde as pessoas podem chegar e deixar mensagens diretamente.

Qual é a Grande Diferença?

O Hermes Agent oferece duas maneiras de conectar o WeCom (WeChat Empresarial). O modo Bot é como um assistente simpático que entra em conversas de grupo — rápido de configurar, mas limitado. O modo Callback é diferente: você cria um aplicativo personalizado que aparece na barra lateral do WeCom dos seus funcionários, como qualquer aplicativo oficial. Parece nativo, suporta várias empresas e lida com mensagens criptografadas com segurança.

O trade-off? Você precisa de um servidor público para receber mensagens. Mas não se preocupe — um túnel simples como ngrok funciona bem para testes.

Como Funciona na Prática

Aqui está o fluxo em termos simples:

Alguém envia uma mensagem para seu aplicativo personalizado no WeCom.
O WeCom criptografa essa mensagem e a envia para o endpoint HTTP do seu servidor.
O Hermes descriptografa, coloca na fila para o agente de IA e imediatamente avisa ao WeCom “recebido” (silenciosamente — o usuário não vê nada ainda).
O agente pensa por 3 a 30 minutos (dependendo da sua tarefa).
O Hermes envia a resposta de volta proativamente usando a API de mensagens do WeCom.

Sem polling. Sem atrasos. Apenas uma conversa assíncrona e limpa.

Configuração Passo a Passo

1. Crie o Aplicativo no Admin do WeCom

Entre no Console de Admin do WeCom, vá em Aplicações → Criar Aplicação.
Anote seu Corp ID (no topo do console) e crie um Corp Secret.
Na página de visão geral do aplicativo, pegue o Agent ID.

Em Receber Mensagens, configure:

URL: http://SEU_IP_PUBLICO:8645/wecom/callback
Token: gere um aleatório
EncodingAESKey: gere uma chave de 43 caracteres

2. Defina as Variáveis de Ambiente

Adicione estas ao seu arquivo .env:

WECOM_CALLBACK_CORP_ID = seu-corp-id
WECOM_CALLBACK_CORP_SECRET = seu-corp-secret
WECOM_CALLBACK_AGENT_ID = 1000002
WECOM_CALLBACK_TOKEN = seu-callback-token
WECOM_CALLBACK_ENCODING_AES_KEY = sua-chave-aes-de-43-caracteres

# Opcional
WECOM_CALLBACK_PORT = 8645
WECOM_CALLBACK_ALLOWED_USERS = usuario1,usuario2

3. Inicie o Gateway

hermes gateway

Nota: Use hermes gateway start somente depois de executar hermes gateway install para registrar o serviço.

O adaptador de callback inicia um servidor HTTP na porta 8645. O WeCom verificará a URL via uma requisição GET e, em seguida, começará a enviar mensagens via POST.

Referência de Configuração

Você também pode definir estas opções em config.yaml sob platforms.wecom_callback.extra:

Configuração	Padrão	Descrição
`corp_id`	—	Obrigatório. Seu Corp ID do WeCom
`corp_secret`	—	Obrigatório. Segredo do aplicativo
`agent_id`	—	Obrigatório. O Agent ID do seu aplicativo
`token`	—	Obrigatório. Token de verificação do callback
`encoding_aes_key`	—	Obrigatório. Chave AES de 43 caracteres
`host`	não definido (dual-stack)	Endereço de bind para o servidor HTTP
`port`	8645	Porta para o servidor de callback

Concluindo

O modo Callback do WeCom é a maneira “oficial” de integrar o Hermes ao seu fluxo de trabalho empresarial. É mais configuração do que o bot, mas o retorno é uma experiência de aplicativo polida e de primeira classe para seus usuários.

Dica prática: Comece com ngrok antes de expor um servidor real. Execute ngrok http 8645, use essa URL no console do WeCom e teste com um único usuário. Quando funcionar, mude para um servidor de produção e restrinja WECOM_CALLBACK_ALLOWED_USERS à sua equipe. Bom desenvolvimento!