Discourse AI: Guida all'integrazione del Bot Discord

[DevTeVe (DevTek Ve)]

Funzionamento (Architettura)

Prima di configurare, è importante capire che non è necessario ospitare un’applicazione bot separata o eseguire uno script “bot” (come un bot Node.js o Python) sul proprio server.

Questa integrazione utilizza le Interazioni di Discord (Webhook) combinate con le Modifiche Progressive per simulare un'esperienza di streaming AI:

1. Azione Utente: Un utente digita /ask nel tuo server Discord.
2. Webhook: Discord invia una richiesta HTTP POST direttamente al tuo server Discourse.
3. Ack Immediata: Discourse risponde istantaneamente con lo stato “Ricerca…”. Questo previene il timeout “Interazione Fallita” di Discord.
4. Risposta in Streaming: Un processo in background inizia a generare la risposta AI. Man mano che l’AI produce testo, Discourse invia frequenti richieste HTTP PATCH per modificare il messaggio Discord in tempo reale.

Risultato: Gli utenti vedono la risposta digitata dal vivo, proprio come ChatGPT, invece di attendere un unico blocco di testo statico.

Vantaggio Chiave: Poiché Discourse gestisce la logica internamente, non c’è infrastruttura aggiuntiva da mantenere. Se il tuo forum è online, il tuo bot è online.

Questa guida illustra il processo completo per integrare il bot AI di Discourse con un server Discord. Include istruzioni specifiche per la registrazione manuale dei comandi slash tramite API, attualmente necessaria per aggirare i problemi di sincronizzazione automatica nel plugin.

Prerequisiti

• Accesso Amministratore a Discourse: Devi essere un amministratore della tua istanza Discourse self-hosted.
• Accesso Amministratore a Discord: Devi avere i permessi “Gestisci Server” sul server Discord di destinazione.
• Accesso al Terminale: Avrai bisogno di un terminale per eseguire i comandi curl.

1. Creare l’Applicazione Discord

1. Naviga al Discord Developer Portal.
2. Clicca su New Application nell’angolo in alto a destra.
3. Dai un nome alla tua applicazione (es. “Discourse Helper”) e clicca su Create.
4. Copia le Credenziali: Nella pagina General Information, individua e salva quanto segue per dopo:

2. Configurare l’Utente Bot

1. Nel menu della barra laterale sinistra, clicca su Bot.

2. Clicca su Reset Token.

3. Abilita gli Intent Privilegiati:

   • Scorri fino alla sezione “Privileged Gateway Intents”.
   • Attiva Message Content Intent su ON. (Questo permette al bot di leggere i messaggi a cui deve rispondere).

4. Clicca su Save Changes.

3. Configurare le Impostazioni di Discourse

1. Accedi al Pannello Amministrativo di Discourse.

2. Naviga su Admin → Plugins → AI → Features.

3. Cerca “discord” e clicca su modifica:
   

   

4. Compila i dettagli

   • AI Discord app ID: Incolla =ApplicationId=
   • AI Discord app public key: Incolla =PublicKey=
     
     

5. Consenti il tuo Server Discord:

   • Apri la tua app Discord e abilita la Modalità Sviluppatore (Impostazioni Utente → Avanzate → Modalità Sviluppatore).
   • Fai clic con il tasto destro sull’icona del tuo server nella barra laterale e seleziona Copia ID Server.
   • Nelle Impostazioni di Discourse, incolla questo ID nel campo AI Discord allowed guilds.

4. Impostare l’Endpoint delle Interazioni

1. Costruisci l’URL del tuo endpoint: https://=ForumUrl=/discourse-ai/discord/interactions
2. Torna al Discord Developer Portal.
3. Nella pagina General Information, scorri fino a Interactions Endpoint URL.
4. Incolla il tuo URL e clicca su Save Changes.
   • Successo: Discord invierà un segnale di prova. Se viene salvato senza errori, la tua istanza Discourse ha verificato con successo la firma.
   • Fallimento: Se ricevi un errore, assicurati che AI Discord app ID e AI Discord app public key siano salvati correttamente nelle Impostazioni di Discourse.

5. Invitare il Bot

1. Nel Developer Portal, clicca su Installation nella barra laterale.
2. Scopes: Seleziona le caselle per bot e applications.commands.
3. Permessi del Bot: Seleziona i seguenti:
   • Invia Messaggi
   • Incorpora Link
   • Allega File
   • Leggi Cronologia Messaggi
4. Copia l’Installation Link nella parte superiore della pagina.
5. Apri questo URL in una scheda del browser e autorizza il bot a unirsi al tuo server.

6. Registrare il Comando Slash (Chiamata API Manuale)

Importante: Il nome del parametro del comando DEVE essere query.

Per Mac / Linux (Bash)

curl -X POST "https://discord.com/api/v10/applications/=ApplicationId=/commands" \
  -H "Authorization: Bot =BotToken=" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ask",
    "description": "Ask the AI a question",
    "options": [
        {
            "name": "query",
            "description": "What is your question?",
            "type": 3,
            "required": true
        }
    ]
}'

• Risposta di Successo: Dovresti ricevere una risposta JSON contenente l’ID del nuovo comando.
• Errore 401? Assicurati di aver mantenuto la parola Bot (con uno spazio) prima del tuo token nell’header Authorization.

7. Verifica

1. Apri il tuo Server Discord.
2. Digita /ask in un canale di testo.
3. Dovrebbe apparire il menu dei comandi. Seleziona /ask e digita una domanda nel campo query.
4. Comportamento Atteso:
   • Immediato: Il bot risponde “Ricerca…”
   • Dopo alcuni secondi: Il messaggio si aggiorna con la risposta dell’AI.

Risoluzione dei Problemi

Errore	Causa	Soluzione
401 Unauthorized (in Curl)	Formato Token errato	Assicurati che l’header sia Authorization: Bot =BotToken=. Usa il token dalla scheda Bot, non dalla scheda Generale.
Job Exception: context must be an instance of BotContext	Payload Errato	Assicurati di essere aggiornato, questo è stato risolto su FIX: Discord Bot crash due to missing BotContext in PersonaReplier by devtekve · Pull Request #36429 · discourse/discourse · GitHub