Collegare Feishu a Elisi Agent

Collegare un bot Feishu a Elisi Agent

Dopo la configurazione puoi scrivere in privato al bot aziendale in Feishu e chiedere a Elisi Agent di registrare o cercare attività, liste e altri elementi.

Prima di iniziare

Ti servono:

Un account Elisi.
Il permesso di creare e pubblicare un'app personalizzata Feishu.
L'approvazione dell'amministratore aziendale per i permessi dell'app, se richiesta.

1. Crea un'app Feishu

Apri la piattaforma Feishu Open e vai alla console sviluppatori.
Crea un'app personalizzata aziendale.
In Aggiungi funzionalità app, attiva Bot.
In Autorizzazioni, aggiungi:
- Leggere i messaggi privati inviati dagli utenti al bot.
- Inviare messaggi come app.
- Per usare il bot nei gruppi, aggiungi anche il permesso di ricevere i messaggi in cui viene menzionato.

Salva l'App ID e l'App Secret.

2. Collega il bot in Elisi

Apri Impostazioni in Elisi.
In Elisi AI, seleziona Bot Feishu / Lark.
Scegli Feishu come piattaforma. Se usi il servizio internazionale Lark, scegli Lark.
Inserisci un nome facoltativo per il bot, App ID, App Secret e Verification Token mostrato nella console Feishu.
Seleziona Collega bot.

Dopo la verifica, Elisi mostra:

Un URL di callback degli eventi.
Un comando monouso per collegare l'account.

L'App Secret viene mostrato una sola volta. Elisi lo conserva in forma crittografata e non lo invia all'Agent.

3. Configura i callback degli eventi

Torna alla piattaforma Feishu Open:

Apri Eventi e callback oppure Sottoscrizioni eventi.
Seleziona Invia gli eventi a un server per sviluppatori.
Copia l'URL di callback degli eventi da Elisi e incollalo come URL della richiesta.
Lascia vuoto Encrypt Key.
Salva l'URL e attendi che Feishu confermi la verifica.

Seleziona Aggiungi evento e aggiungi:

Ricevi messaggi (im.message.receive_v1)

La sola verifica dell'URL non basta: devi aggiungere anche im.message.receive_v1.

4. Pubblica e installa l'app

Crea una nuova versione nella piattaforma Feishu Open.
Verifica che includa i permessi e l'evento appena aggiunti.
Invia la versione per la revisione e pubblicala. Se richiesto, completa prima l'approvazione dell'amministratore.
Installa l'app nell'azienda e verifica che il tuo account Feishu sia incluso nell'ambito di disponibilità.

Dopo ogni modifica ai permessi o agli eventi, pubblica una nuova versione perché le modifiche diventino effettive.

5. Collega l'account Elisi

Configurare e pubblicare l'app può richiedere più di 15 minuti. Una volta pubblicata, torna in Elisi:

Nella scheda del bot seleziona Genera nuovo codice di collegamento.
Copia il comando monouso completo, ad esempio:
```
/elisi-bind AbCdEf123
```
Entro 15 minuti, apri una chat privata con il bot e invia il comando.
Dopo il messaggio di conferma, torna in Elisi e aggiorna lo stato.

La configurazione è completa quando lo stato passa da In attesa di collegamento a Connesso. Il primo collegamento deve avvenire in una chat privata, non in un gruppo.

6. Usa il bot

Chat privata: Invia testo direttamente al bot.
Chat di gruppo: Un utente collegato deve menzionare il bot nel messaggio.
Disconnetti: Seleziona Disconnetti nella scheda del bot in Elisi.

La versione attuale supporta messaggi di testo. Non supporta callback crittografati con Encrypt Key, allegati, schede interattive o la condivisione di un account Elisi tra più persone.

Risoluzione dei problemi

Problema	Cosa controllare
La verifica dell'URL fallisce o non restituisce la challenge	Controlla che l'URL sia completo e che il `Verification Token` corrisponda. Svuota `Encrypt Key` e salva di nuovo.
L'URL viene verificato, ma il bot non risponde in privato	Verifica che `im.message.receive_v1` sia stato aggiunto. Dopo aver aggiunto eventi e permessi, ripubblica, fai approvare e installa la versione più recente.
Elisi mostra ancora «In attesa di collegamento»	Genera un nuovo codice e invia il comando completo in una chat privata entro 15 minuti. I codici vecchi scadono.
L'account è collegato ma il bot non risponde	Controlla che il permesso di inviare messaggi come app sia approvato e incluso nell'ultima versione pubblicata.
Il bot non risponde in un gruppo	Collega prima l'account in privato. Poi un utente collegato deve menzionare il bot nel gruppo.
Non trovi il bot o non puoi scrivergli	Verifica che l'app sia installata e che il tuo account rientri nell'ambito di disponibilità.

Se il problema persiste, controlla nei Registri di invio eventi della piattaforma Feishu Open se appare im.message.receive_v1. Se manca, l'evento, i permessi, la versione pubblicata o l'ambito dell'app potrebbero non essere ancora attivi.