WeCom Callback (aplicativo próprio)

Conecte o Hermes ao WeCom (WeChat corporativo) como um aplicativo corporativo próprio, usando o modelo de callback/webhook.

WeCom Bot ou WeCom Callback

O Hermes suporta dois modos de integração com o WeCom:

• WeCom Bot — no estilo bot, conecta por WebSocket. Configuração mais simples, funciona em conversas de grupo.
• WeCom Callback (esta página) — aplicativo próprio, recebe callbacks XML criptografados. Aparece como aplicativo de primeira classe na barra lateral do WeCom dos usuários. Suporta roteamento entre várias corporações.

Veja também: WeCom Bot, para a integração no estilo bot.

Rode hermes gateway setup e escolha WeCom Callback para um passo a passo guiado.

Como funciona

1. Você registra um aplicativo próprio no console de administração do WeCom
2. O WeCom envia XML criptografado ao seu endpoint HTTP de callback
3. O Hermes descriptografa a mensagem e a coloca na fila do agente
4. Confirma na hora (em silêncio — nada é exibido ao usuário)
5. O agente processa o pedido (tipicamente de 3 a 30 minutos)
6. A resposta é entregue de forma proativa pela API message/send do WeCom

Pré-requisitos

• Uma conta corporativa do WeCom com acesso de administrador
• Os pacotes Python aiohttp e httpx (já vêm na instalação padrão)
• Um servidor alcançável publicamente para a URL de callback (ou um túnel, como o ngrok)

Configuração

1. Crie um aplicativo próprio no WeCom

1. Vá ao console de administração do WeCom → Applications → Create App
2. Anote o seu Corp ID (mostrado no topo do console)
3. Nas configurações do aplicativo, crie um Corp Secret
4. Anote o Agent ID na página de visão geral do aplicativo
5. Em Receive Messages, configure a URL de callback:
   • URL: http://YOUR_PUBLIC_IP:8645/wecom/callback
   • Token: gere um token aleatório (o WeCom fornece um)
   • EncodingAESKey: gere uma chave (o WeCom fornece uma)

2. Configure as variáveis de ambiente

Acrescente 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-token-de-callback
WECOM_CALLBACK_ENCODING_AES_KEY=sua-chave-aes-de-43-caracteres

# Opcional
# WECOM_CALLBACK_HOST=  # fixação opcional; em branco = pilha dupla (todas as interfaces, IPv4+IPv6)
WECOM_CALLBACK_PORT=8645
WECOM_CALLBACK_ALLOWED_USERS=user1,user2

3. Suba o gateway

hermes gateway

(Use hermes gateway start só depois que o hermes gateway install tiver registrado o serviço systemd/launchd.)

O adaptador de callback sobe um servidor HTTP na porta configurada. O WeCom verifica a URL de callback com uma requisição GET e, depois disso, começa a mandar mensagens por POST.

Referência de configuração

Defina isto no config.yaml, em platforms.wecom_callback.extra, ou use variáveis de ambiente:

Ajuste	Padrão	Descrição
corp_id	—	Corp ID da empresa no WeCom (obrigatório)
corp_secret	—	Corp secret do aplicativo próprio (obrigatório)
agent_id	—	Agent ID do aplicativo próprio (obrigatório)
token	—	Token de verificação do callback (obrigatório)
encoding_aes_key	—	Chave AES de 43 caracteres para a criptografia do callback (obrigatória)
host	em branco (pilha dupla: todas as interfaces, IPv4+IPv6)	Endereço em que o servidor HTTP de callback escuta
port	8645	Porta do servidor HTTP de callback
path	/wecom/callback	Caminho de URL do endpoint de callback

Roteamento com vários aplicativos

Para empresas que rodam vários aplicativos próprios (por exemplo, em departamentos ou subsidiárias diferentes), configure a lista apps no config.yaml:

platforms:
  wecom_callback:
    enabled: true
    extra:
      host: "0.0.0.0"
      port: 8645
      apps:
        - name: "dept-a"
          corp_id: "ww_corp_a"
          corp_secret: "secret-a"
          agent_id: "1000002"
          token: "token-a"
          encoding_aes_key: "key-a-43-chars..."
        - name: "dept-b"
          corp_id: "ww_corp_b"
          corp_secret: "secret-b"
          agent_id: "1000003"
          token: "token-b"
          encoding_aes_key: "key-b-43-chars..."

Os usuários têm escopo corp_id:user_id para evitar colisões entre corporações. Quando um usuário manda uma mensagem, o adaptador registra a qual aplicativo (corporação) ele pertence e roteia as respostas pelo token de acesso do aplicativo correto.

Controle de acesso

Restrinja quem pode interagir com o aplicativo:

# Libera usuários específicos
WECOM_CALLBACK_ALLOWED_USERS=zhangsan,lisi,wangwu

# Ou libera todos os usuários
WECOM_CALLBACK_ALLOW_ALL_USERS=true

Endpoints

O adaptador expõe:

Método	Caminho	Finalidade
GET	/wecom/callback	Handshake de verificação da URL (o WeCom manda isso durante a configuração)
POST	/wecom/callback	Callback de mensagem criptografada (o WeCom manda as mensagens dos usuários aqui)
GET	/health	Verificação de saúde — devolve {"status": "ok"}

Criptografia

Todos os payloads de callback são criptografados com AES-CBC usando a EncodingAESKey. O adaptador cuida de:

• Entrada: descriptografar o payload XML e verificar a assinatura SHA1
• Saída: respostas enviadas pela API proativa (não como resposta criptografada ao callback)

A implementação de criptografia é compatível com o SDK oficial WXBizMsgCrypt da Tencent.

Limitações

• Sem streaming — as respostas chegam como mensagens completas depois que o agente termina
• Sem indicadores de digitação — o modelo de callback não suporta status de digitação
• Só texto — hoje suporta mensagens de texto na entrada; entrada de imagem/arquivo/voz ainda não foi implementada. O agente sabe das capacidades de mídia de saída pela dica de plataforma do WeCom (imagens, documentos, vídeo, voz).
• Latência de resposta — as sessões do agente levam de 3 a 30 minutos; os usuários veem a resposta quando o processamento acaba

Solução de problemas

A verificação de assinatura falha. O WeCom assina toda requisição com o Token que você registrou no console de administração. Uma divergência entre o token configurado no Hermes e o token que o console espera é a causa mais comum. Copie de novo tanto o Token quanto a EncodingAESKey do console — é fácil truncar. Espaços em branco em volta do = nos valores do ~/.hermes/.env também quebram a checagem de assinatura. Depois de corrigir, reinicie o hermes gateway run.

A URL de callback não é alcançável / a verificação falha. O WeCom bate na URL pública que você registrou. Confirme que:

1. Seu proxy reverso / túnel encaminha /wecom/callback para a porta do gateway.
2. A URL no console de administração é HTTPS (o WeCom rejeita HTTP puro).
3. De fora da sua rede, curl -i https://<seu-dominio>/wecom/callback devolve qualquer coisa que não seja um timeout (um 4xx sem parâmetros de query está de bom tamanho — só quer dizer que o ouvinte está alcançável).

A porta não é alcançável / o ouvinte não subiu. Procure nos logs do hermes gateway run o host/porta em que ele se prendeu. Se o adaptador se prendeu a 127.0.0.1, você precisa colocar um proxy reverso ou túnel na frente — os servidores do WeCom não alcançam o loopback. Deixe extra.host em branco para valer o padrão de pilha dupla (todas as interfaces, IPv4+IPv6), ou fixe uma interface no config.yaml (mais allowed_source_cidrs, se for expor diretamente), ou mantenha o loopback e use um túnel como o Cloudflare Tunnel / nginx.

---