=== WVDevel Community Assistant for Telegram ===
Contributors: wvdevel
Tags: telegram, chatbot, ollama, community, moderation
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.1.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A configurable Telegram bot for any community or group: validates members, replies only when mentioned, and optionally integrates with Ollama.

== Description ==

This plugin connects a Telegram bot to your WordPress site to support
the community or group you manage:

* Validates every Telegram user against the plugin's own database
  table (username, Telegram ID and an access code). The code is stored
  encrypted with AES-256-GCM (authenticated encryption) using the
  security keys from your own `wp-config.php`, and is managed from a
  screen in the WordPress admin, with no loose JSON files.
* If a user is not validated, the bot does not reply at all -except
  for a single private notice the first time they write- so no
  information is exposed and no spam is generated.
* In a group, the bot only replies if it is mentioned (@bot username,
  replying to one of its messages, or with a command directed at it).
  In private chats it always replies, to already validated users.
* Includes configurable general commands: `/reglas`, `/horario`,
  `/anuncios`, `/recursos`, `/ayuda`, `/misdatos` -all editable from
  the WordPress admin, without touching code.
* Includes moderation commands for administrators, private chat only:
  `/validar`, `/invalidar`, `/listar`, `/anunciar`, `/stats`.
* "Mis recursos": each validated user can have a *carnet* (student/member
  code). Files uploaded per carnet from the "Recursos por usuario" admin
  screen are offered to that user -and only that user- when they send
  `/recursos` in a private chat: one button per file plus a "download
  all" button that sends a ZIP. The files are stored in a private,
  web-inaccessible folder and are delivered straight to Telegram, never
  through a public URL.
* Integrates an Ollama (conversational AI) client that is already
  built but disabled by default: once your Ollama server is ready,
  just enable the checkbox and set the URL/model in Settings. Until
  then the bot replies with a notice instead of failing.

= Use cases =

Built for any Telegram community that needs to moderate access and
automate replies: study groups, communities of practice, work teams,
clubs or product support.

== External services ==

This plugin connects to the following external services to work:

* **Telegram Bot API** (`https://api.telegram.org`) - required for the
  bot to function. The plugin sends your bot token and the text
  messages exchanged with Telegram users (inbound and outbound) so it
  can receive and reply to messages via webhook. Subject to Telegram's
  [Terms of Service](https://telegram.org/tos) and
  [Privacy Policy](https://telegram.org/privacy).
* **Ollama** (URL you configure, typically your own server) - optional
  and disabled by default. If you enable it, the text of messages from
  validated users is sent to the URL you configure to generate an AI
  reply. No information is sent to any third-party server other than
  the one you specify in Settings.

= Requirements =

* WordPress 5.8 or higher.
* PHP 7.4 or higher, with the `openssl` extension enabled.
* A site with valid HTTPS (Telegram does not accept webhooks over
  `http://`).
* A bot created with @BotFather on Telegram.

== Installation ==

1. Upload the full plugin folder to `wp-content/plugins/`, or zip its
   contents and use **Plugins -> Add New -> Upload Plugin** from the
   WordPress admin.
2. Activate "WVDevel Community Assistant for Telegram" in **Plugins**.
   On activation, the required database tables and a random webhook
   secret are created automatically.
3. Go to **Bot Telegram -> Ajustes** (Settings):
   1. Paste the bot token (obtained from @BotFather) and save the
      settings. It is encrypted before being saved.
   2. Click "Configurar Webhook" to register your site with Telegram.
   3. Add the group ID under "Grupos permitidos" and your own Telegram
      ID under "IDs de administradores".
   4. Edit the `/reglas`, `/horario`, `/anuncios` and `/recursos` texts
      with your community's actual content.
4. Go to **Bot Telegram -> Usuarios validados** and register each
   member (Telegram ID, username, name and access code). You can also
   do this from Telegram with `/validar [id] [codigo] [usuario]
   [nombre]` in a private chat with the bot, once your ID is in the
   administrators list.
5. (Optional) "Mis recursos" - personal files per member:
   1. In **Bot Telegram -> Ajustes**, section "4. Mis recursos",
      keep "Activar" checked (it is on by default), optionally edit
      the intro text and the per-file size limit.
   2. In **Bot Telegram -> Usuarios validados**, fill the **Carnet**
      field for each member (their student/member code). This is the
      key that links a person to their folder of files.
   3. In **Bot Telegram -> Recursos por usuario**, type a carnet and
      upload one or more files for it. They are stored in a private
      folder inside `wp-content/uploads` that is not reachable from
      the web.
   4. The member writes `/recursos` in a **private** chat with the
      bot: after the general text they get a button per file (tap to
      download) and, if there are two or more, a "download all"
      button that sends a ZIP.
6. (Optional, later) Enable Ollama in Settings once your server is
   running, providing its URL and the model to use.

== Frequently Asked Questions ==

= How does "Mis recursos" (personal files) work? =

Assign a *carnet* to a member under "Usuarios validados", upload
files for that carnet under "Recursos por usuario", and the member
receives them by writing `/recursos` in a private chat with the bot.
Each file is a button; a "download all" button sends a ZIP. It only
works in private chats, never in the group.

= Where are the personal files stored? Are they public? =

They are saved in `wp-content/uploads/wvdevel-mis-recursos-<random>/`,
protected with a "deny from all" `.htaccess`/`web.config` and an
unguessable random folder name. The plugin never exposes a public URL:
it uploads each file straight to Telegram, and only to the member
whose carnet matches. Deleting the plugin removes the whole folder.

= A member says /recursos does not show their files =

Check that: the feature is enabled in Settings; the member has a
**Carnet** set that exactly matches the one used when uploading; there
is at least one file for that carnet; and they are writing `/recursos`
in a **private** chat, not in the group.

= Do I need Ollama running to use the plugin? =

No. The Ollama client is disabled by default. While it is off, the
bot still validates users and replies to the configured commands
(`/reglas`, `/horario`, etc.); only free-form natural language
questions get a notice that AI is not configured yet.

= How do I get the numeric ID of the Telegram group? =

Forward any message from the group to a bot such as @userinfobot, or
check the first message the group sends to the bot after configuring
the webhook (it appears in the WordPress logs if something fails).

= Is it safe to store members' access codes in the database? =

The access code and the bot token are encrypted with AES-256-GCM
(authenticated encryption) using the `AUTH_KEY` / `SECURE_AUTH_KEY`
keys from your own `wp-config.php` before being saved. They are never
stored in plain text or in loose files.

= Does the bot reply to every message in the group? =

No. In a group it only replies if it is mentioned directly (@bot
username, replying to one of its messages, or with a command directed
at it). Any other message in the group is completely ignored.

= Can I have more than one administrator? =

Yes, add the Telegram IDs separated by commas under "IDs de
administradores" in Settings.

= What happens if I deactivate the plugin? =

Nothing is deleted: the webhook, the settings and the validated users
are kept. They are only removed completely if you use
**Plugins -> Delete**, which runs the definitive cleanup of tables and
settings.

== Screenshots ==

1. Settings screen: bot token, webhook configuration, allowed groups,
   administrators, Ollama integration and group texts.
2. Validated Users screen: adding members (with their carnet) and a
   list with search, status (validated/inactive) and masked access code.
3. "Recursos por usuario" screen: uploading files per carnet and the
   list of stored files.
4. Telegram: the /recursos reply in a private chat, with a button per
   file and a "download all" button.

== Changelog ==

= 1.1.0 =
* New "Mis recursos" feature: per-carnet personal files. Adds a "carnet"
  field to validated users, a "Recursos por usuario" admin screen to
  upload/delete files per carnet, and extends `/recursos` so that in a
  private chat the bot also lists the user's files with inline buttons
  (download one by one, or "download all" as a ZIP).
* Files are kept in an unguessable folder inside uploads, locked down
  with a Deny-from-all `.htaccess`/`web.config`, and are uploaded to
  Telegram via multipart -no public URL is ever exposed.
* The bot now handles Telegram `callback_query` updates (inline button
  presses), restricted to private chats and validated users.
* Uninstalling now also drops the `wvdevel_resources` table and removes
  the private resources folder.

= 1.0.0 =
* Initial release: encrypted user validation (AES-256-GCM), REST
  webhook protected with a secret_token, configurable general
  commands, private moderation commands, a message log screen with
  search and per-conversation deletion, an administrators screen, a
  broadcast screen for sending messages/attachments to validated
  users and/or allowed groups, and an Ollama client ready to be
  enabled.

== Upgrade Notice ==

= 1.1.0 =
Adds the "Mis recursos" feature (personal files per carnet delivered
through /recursos in private chat). The database is updated automatically
on activation.

= 1.0.0 =
Initial release.
