GitHubHelp

madAle/school_bot

★ 0Forks 0RubyGitHub ↗Compare

README

School Bot - WhatsApp Translation Bot

Bot per gruppo WhatsApp scolastico che traduce automaticamente i messaggi dei contatti autorizzati in Italiano, Arabo Standard Moderno e Urdu.

Requisiti

  • Ruby 3.x
  • Docker e Docker Compose (solo per WAHA)
  • API key per il provider LLM scelto (Claude o Gemini)

Provider WhatsApp

Il bot supporta due provider, configurabili in config.yml:

Provider Pro Contro
WAHA (waha) Gratuito, nessun account business Non ufficiale, rischio ban
Meta Cloud API (meta_cloud) Ufficiale, zero rischio ban, gratis fino a 1000 conv/mese Richiede account Meta Business

Provider LLM (traduzione)

Provider Pro Contro
Gemini (gemini) Gratuito (15 req/min, 1M token/giorno), multimodale Richiede account Google
Claude (claude) Qualità eccellente, multimodale A pagamento ($5 credito iniziale)

Setup comune

1. Installa le dipendenze Ruby

bundle install

2. Configura la API key per il provider LLM scelto

Gemini (gratuito)

  1. Vai su https://aistudio.google.com/apikey
  2. Fai login con il tuo account Google
  3. Clicca Create API Key
  4. Copia la chiave e configurala:
export GEMINI_API_KEY="..."

Claude (a pagamento, $5 credito iniziale)

  1. Vai su https://console.anthropic.com e crea un account
  2. Vai su API Keys nella sidebar
  3. Clicca Create Key, dagli un nome (es. "school-bot")
  4. Copia la chiave (mostrata solo una volta) e configurala:
export ANTHROPIC_API_KEY="sk-ant-..."

Per continuare a usare Claude dopo il credito iniziale, aggiungi una carta in Settings > Billing.

3. Modifica config.yml

  • Scegli il provider WhatsApp: provider: "waha" o provider: "meta_cloud"
  • Scegli il provider LLM: llm_provider: "gemini" o llm_provider: "claude"
  • Inserisci l'ID del gruppo WhatsApp in group_id
  • Aggiungi i numeri autorizzati in authorized_contacts (formato: 39XXXXXXXXXX, senza @c.us)

Per trovare l'ID del gruppo, avvia il bot con LOG_LEVEL=DEBUG e invia un messaggio nel gruppo: l'ID apparirà nei log.

Setup WAHA (provider: waha)

4. Avvia WAHA

docker-compose up -d

5. Collega WhatsApp

Apri http://localhost:3000/dashboard e scansiona il QR code con WhatsApp sul telefono.

6. Avvia il bot

ruby app.rb

Setup Meta Cloud API (provider: meta_cloud)

4. Crea un'app Meta

  1. Vai su https://developers.facebook.com/apps/ e crea una nuova app
  2. Aggiungi il prodotto "WhatsApp"
  3. Nella sezione WhatsApp > API Setup, trovi il Phone Number ID e puoi generare un Access Token

5. Configura le variabili d'ambiente

export WHATSAPP_ACCESS_TOKEN="your-permanent-token"

6. Aggiorna config.yml

provider: "meta_cloud"

meta_cloud:
  phone_number_id: "IL_TUO_PHONE_NUMBER_ID"
  verify_token: "una-stringa-segreta-a-tua-scelta"
  api_version: "v21.0"

7. Registra il webhook

  1. Esponi il bot su internet (es. con ngrok: ngrok http 4567)
  2. In Meta Developer Dashboard > WhatsApp > Configuration > Webhook
  3. URL: https://tuo-url.ngrok.io/webhook
  4. Verify token: lo stesso valore di verify_token in config.yml
  5. Sottoscrivi il campo "messages"

8. Avvia il bot

ruby app.rb

Come funziona

  1. Un contatto autorizzato (es. una maestra) invia un messaggio nel gruppo
  2. Il provider (WAHA o Meta) inoltra il messaggio al bot via webhook
  3. Il bot verifica che il mittente sia nella lista autorizzati
  4. Il messaggio viene inviato all'LLM (Gemini o Claude) per la traduzione
  5. Le traduzioni vengono inviate nel gruppo

Esempio di output

📚 *Traduzione / Translation*

🇮🇹 *Italiano:*
Domani non c'è scuola per lo sciopero dei trasporti.

🇸🇦 *العربية:*
غداً لا توجد مدرسة بسبب إضراب وسائل النقل.

🇵🇰 *اردو:*
کل ٹرانسپورٹ کی ہڑتال کی وجہ سے سکول نہیں ہوگا۔

Note

  • Il bot traduce solo i messaggi dei contatti nella lista authorized_contacts
  • Supporta testo, immagini e PDF
  • Per documenti e immagini, il bot fa prima un riassunto e poi lo traduce
  • WAHA usa WhatsApp Web: il telefono deve rimanere connesso a internet
  • Meta Cloud API: il telefono non deve restare connesso

Contributors

madAle

Issues