Modalità Callback WeCom — App Personalizzate

Immagina di allestire una casella postale dedicata per il tuo assistente AI: invece di farlo aggirare nelle chat di gruppo, gli dai una scrivania tutta sua dove le persone possono avvicinarsi e lasciare messaggi direttamente.

Qual è la Grande Differenza?

Hermes Agent ti offre due modi per connetterti a WeCom (WeChat Enterprise). La modalità Bot è come un assistente amichevole che si unisce alle chat di gruppo: veloce da configurare, ma limitata. La modalità callback è diversa: crei un’app personalizzata che appare nella barra laterale WeCom dei tuoi dipendenti, proprio come qualsiasi app ufficiale. Sembra nativa, supporta più aziende e gestisce i messaggi crittografati in modo sicuro.

Il compromesso? Hai bisogno di un server pubblico per ricevere i messaggi. Ma non preoccuparti: un semplice tunnel come ngrok funziona benissimo per i test.

Come Funziona Realmente

Ecco il flusso in parole povere:

Qualcuno invia un messaggio alla tua app personalizzata in WeCom.
WeCom crittografa il messaggio e lo invia all’endpoint HTTP del tuo server.
Hermes lo decrittografa, lo mette in coda per l’agente AI e dice subito a WeCom “ricevuto” (in silenzio: l’utente non vede ancora nulla).
L’agente pensa per 3-30 minuti (a seconda del tuo compito).
Hermes invia la risposta in modo proattivo utilizzando l’API dei messaggi di WeCom.

Niente polling. Niente ritardi. Solo una conversazione asincrona e pulita.

Configurazione Passo Dopo Passo

1. Crea l’App nella Console Admin di WeCom

Accedi alla Console Admin di WeCom, vai su Applicazioni → Crea App.
Annota il tuo Corp ID (in cima alla console) e crea un Corp Secret.
Nella pagina di panoramica dell’app, prendi l’Agent ID.

Nella sezione Ricevi Messaggi, configura:

URL: http://IL_TUO_IP_PUBBLICO:8645/wecom/callback
Token: generane uno casuale
EncodingAESKey: genera una chiave di 43 caratteri

2. Imposta le Variabili d’Ambiente

Aggiungi queste al tuo file .env:

WECOM_CALLBACK_CORP_ID = il-tuo-corp-id
WECOM_CALLBACK_CORP_SECRET = il-tuo-corp-secret
WECOM_CALLBACK_AGENT_ID = 1000002
WECOM_CALLBACK_TOKEN = il-tuo-callback-token
WECOM_CALLBACK_ENCODING_AES_KEY = la-tua-chiave-aes-43-caratteri

# Opzionale
WECOM_CALLBACK_PORT = 8645
WECOM_CALLBACK_ALLOWED_USERS = user1,user2

3. Avvia il Gateway

hermes gateway

Nota: usa hermes gateway start solo dopo aver eseguito hermes gateway install per registrare il servizio.

L’adattatore callback avvia un server HTTP sulla porta 8645. WeCom verificherà l’URL tramite una richiesta GET, poi inizierà a inviare messaggi tramite POST.

Riferimento alla Configurazione

Puoi anche impostare questi parametri in config.yaml sotto platforms.wecom_callback.extra:

Impostazione	Default	Descrizione
`corp_id`	—	Obbligatorio. Il tuo Corp ID WeCom
`corp_secret`	—	Obbligatorio. Il segreto dell’app
`agent_id`	—	Obbligatorio. L’Agent ID della tua app
`token`	—	Obbligatorio. Token di verifica callback
`encoding_aes_key`	—	Obbligatorio. Chiave AES di 43 caratteri
`host`	non impostato (dual-stack)	Indirizzo di bind per il server HTTP
`port`	8645	Porta per il server callback

Per Concludere

La modalità Callback di WeCom è il modo “ufficiale” per integrare Hermes nel tuo flusso di lavoro aziendale. Richiede più configurazione rispetto al bot, ma il risultato è un’esperienza app di prim’ordine e rifinita per i tuoi utenti.

Consiglio pratico: Inizia con ngrok prima di esporre un server reale. Esegui ngrok http 8645, usa quell’URL nella console WeCom e testa con un singolo utente. Una volta che funziona, passa a un server di produzione e limita WECOM_CALLBACK_ALLOWED_USERS al tuo team. Buon lavoro!