=== AroksDS Submission Alerts for Contact Form 7 to Telegram ===
Contributors: aroksds2026
Tags: contact form 7, cf7, telegram, notifications, form submissions
Requires at least: 6.0
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.1
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Stop losing leads: send Contact Form 7 submissions to a shared Telegram channel as a reliable backup to email.

== Description ==

Email is not a reliable operational channel for lead intake. Even when Contact Form 7 reports “mail sent”, real-world delivery can fail: messages may land in spam, be blocked by SMTP/DMARC rules, get throttled, or simply never reach the inbox in time. The result is the worst-case scenario: **a lead is submitted, but nobody sees it**.

**AroksDS Submission Alerts for Contact Form 7 to Telegram** creates a second, independent delivery path: every successful form submission can generate an instant Telegram notification in a shared team space (group, private chat, or a forum topic). This gives you a practical “backup channel” so leads are not lost when email delivery is unreliable.

= Why this plugin is useful =
* **Backup channel to email**: reduce lost leads caused by spam filtering or mail delivery issues.
* **Shared visibility for managers**: send to a single Telegram group used by everyone who handles leads.
* **Faster response time (SLA)**: instant notifications help you respond while the user is still “hot”.
* **Less human error**: no need to manually check mailboxes or WordPress admin panels.
* **Simple triage**: route different forms to different chats/topics (sales vs support vs hiring).
* **Operational continuity**: even if your SMTP provider or mail settings break, Telegram alerts can still arrive.
* **Privacy control**: choose what fields are included (Allowed/Excluded fields) and keep templates minimal.
* **Troubleshooting**: built-in test tool + lightweight logs for quick diagnosis.

= Key features =
* **Success-only trigger**: sends only on Contact Form 7 `wpcf7_mail_sent` (this WordPress.org edition intentionally avoids any “before send” triggers).
* **Global defaults + per-form rules**: Form ID → Chat ID → optional Message Thread ID → Template → Allowed/Excluded fields.
* **Template placeholders**: `{field-name}`, `{form_id}`, `{form_title}`, `{page_url}`, `{date}`, `{time}`, `{all_fields}`.
* **Parse modes**: Plain, HTML, MarkdownV2 (placeholder values are escaped for safety).
* **Logs**: stores last 100 entries (errors always; successes only when Debug Logs are enabled).
* **Tools**: send a test message from wp-admin.
* **No tracking / telemetry**: no external calls except Telegram Bot API.

= What this plugin does NOT do (to avoid misunderstandings) =
* It sends **text messages only** via Telegram Bot API `sendMessage` (no attachments/files).
* It is not a CRM and does not store submissions as leads in WordPress.
* It does not replace email delivery — it **adds a duplicate channel** for operational safety.

= External services =

This plugin connects to the Telegram Bot API to send messages.

* Service: Telegram Bot API (sendMessage)
  https://core.telegram.org/bots/api
* Terms of use:
  https://telegram.org/tos
* Privacy policy:
  https://telegram.org/privacy

When: On successful Contact Form 7 submissions (`wpcf7_mail_sent`) and when you click "Send test message" in wp-admin.
Data sent: `chat_id`, message text (built from your template and filtered form fields), optional `parse_mode`, optional `message_thread_id`, `disable_web_page_preview`.
Privacy controls: limit what is sent by configuring Allowed/Excluded fields and by editing the message template.

Note: Telegram is a third-party service. Site owners are responsible for the data they send to Telegram. Avoid sending sensitive personal data unless necessary.

== Privacy ==

This plugin may send form submission content (which can include personal data) to Telegram.

Suggested text for your privacy policy:
* We use a plugin that forwards Contact Form 7 submissions to Telegram (a third-party service) via the Telegram Bot API.
* Data sent may include the message text built from form fields and metadata (e.g., page URL, date/time), depending on our configuration.
* We limit the data shared by selecting allowed/excluded fields and by editing the message template.
* Telegram processes data according to its own Terms and Privacy Policy:
  https://telegram.org/tos
  https://telegram.org/privacy

== Installation ==

1. Install and activate **Contact Form 7**.
2. Install this plugin (Plugins → Add New → Upload) or upload to `/wp-content/plugins/`.
3. Activate the plugin.
4. Go to **Settings → AroksDS Submission Alerts for Contact Form 7 to Telegram**.
5. Add your **Bot Token** and **Default Chat ID**.
6. (Optional) Set **Default Message Thread ID** for Telegram forum topics.
7. Configure template and Allowed/Excluded fields if needed.
8. Use the **Tools** tab to send a test message.
9. Submit a Contact Form 7 form to verify real submissions.

== Frequently Asked Questions ==

= Does it send only when email was sent successfully? =

Yes. This WordPress.org edition triggers only on Contact Form 7 `wpcf7_mail_sent` (success-only).

= Why use Telegram if CF7 already sends emails? =

Because email delivery can fail in practice (spam filters, SMTP misconfiguration, provider blocks, DMARC policies, throttling). Telegram provides a second, independent notification channel to reduce lost leads.

= How do I get a bot token? =

Create a bot with Telegram’s BotFather and copy the token it gives you. Then paste the token into the plugin settings.

= How do I send to a Telegram group? =

1) Add your bot to the group.
2) Ensure the bot has permission to post messages.
3) Use the group chat ID as the target Chat ID.

= How do I find my Chat ID? =

Telegram chat IDs depend on the chat type:
* Private chat: usually a positive numeric ID.
* Groups/supergroups: often negative IDs (starting with `-`).
Use a helper method you trust to read the chat ID after you send a message where the bot can see it.

= What is “Message Thread ID”? =

It is used for Telegram forum topics. If your group has topics enabled, you can send to a specific topic by setting the Message Thread ID.

= Can I route different forms to different Telegram chats? =

Yes. Use **Per-form Rules** and set the Contact Form 7 Form ID and target Chat ID (and optional Thread ID).

= How do Allowed/Excluded fields work? =

* If **Allowed fields** has any values, only those fields are included.
* Otherwise, if **Excluded fields** has values, all fields are included except excluded ones.
The same rules apply to `{all_fields}` and `{field-name}` placeholders.

= Does it send attachments/files? =

No. This plugin sends text messages via Telegram Bot API `sendMessage`.

= Where are logs stored? Do they include the bot token? =

Logs are stored in your WordPress database as an option and keep only the last 100 entries.
The bot token is never stored in logs.

= Typical Telegram errors and what they mean =

* `chat not found` → wrong Chat ID or the bot cannot access that chat.
* `bot was blocked by the user` → the user blocked the bot.
* `not enough rights to send text messages` → bot permissions in the group are insufficient.
* `Bad Request: message is too long` → reduce `{all_fields}` or exclude large fields.

= Can I use a constant or environment variable for the token? =

Yes:
* `define('CF7_TG_BOT_TOKEN', '...')` in `wp-config.php`, or
* environment variable `CF7_TG_BOT_TOKEN`

When provided this way, the token field in Settings is locked.

== Screenshots ==

1. Settings page (bot token, defaults, and per-form rules).
2. Tools tab (send a test message).
3. Logs tab (last 100 entries and clear logs).

== Changelog ==

= 1.0.1 =
* Fix: Prevent placeholder injection in Plain/HTML by single-pass placeholder replacement.
* Fix: Preserve newlines in multi-line fields (textarea).
* Fix: Prevent admin rule index collisions when adding/removing rules.
* Security: Harden admin settings saving (sanitize/validate rule inputs; avoid processing entire $_POST).
* Fix: Improve MarkdownV2 escaping for backslashes.

= 1.0.0 =
* Initial WordPress.org-ready release (EN base language).
* Strict success-only trigger (`wpcf7_mail_sent`).
* Per-form rules, templates, tools, and logs.
* Privacy policy helper text and external service disclosure.

== Upgrade Notice ==

= 1.0.1 =
Security and reliability fixes (placeholder handling, admin rules UI, multiline fields).

= 1.0.0 =
First public release.
