📨 Telegram Addon Guide
Easy Form Builder by WhiteStudio – Telegram Integration
Version 1.0.0
1. Overview
The Telegram addon for Easy Form Builder connects your WordPress forms to a Telegram bot.
When enabled, each form submission triggers a notification sent to the admin’s Chat ID (or multiple recipients) via the Telegram Bot API.
Key Features
- Connect to Telegram via Bot Token
- Automatic notifications on form submission
- Separate Chat ID configuration per form
- Send test messages from the admin panel
- Onboarding system for automatic Chat ID retrieval
- Sent message activity log
- HTML support in message content
- Send to multiple Chat IDs simultaneously
How It Works
User submits a form
→
Form hook fires
→
Message is built
→
Telegram API called
→
Message delivered
2. File Structure
vendor/telegram/
├── class-Emsfb-telegram.php // Main class: menu, settings, admin AJAX
├── telegram-new-efb.php // Advanced class: sending, onboarding, webhook
├── onboarding.html // User onboarding page
├── guide.html // This guide
└── assets/
├── css/
│ └── telegram-efb.css // Settings page styles
└── js/
└── telegram-efb.js // Dynamic UI (jQuery)
├── class-Emsfb-telegram.php // Main class: menu, settings, admin AJAX
├── telegram-new-efb.php // Advanced class: sending, onboarding, webhook
├── onboarding.html // User onboarding page
├── guide.html // This guide
└── assets/
├── css/
│ └── telegram-efb.css // Settings page styles
└── js/
└── telegram-efb.js // Dynamic UI (jQuery)
| File | Class | Responsibility |
|---|---|---|
class-Emsfb-telegram.php |
telegramlistefb |
Admin menu, settings page, AJAX handlers (test, save, log) |
telegram-new-efb.php |
telegramsendefb |
Message sending, user management, onboarding, webhook, form hooks |
3. Prerequisites
- WordPress 5.0 or higher
- Easy Form Builder plugin installed and activated
- Pro version activated (the Telegram addon is only available in the Pro edition)
- A Telegram bot created via @BotFather
- Server must allow outbound connections to
api.telegram.org(port 443)
4. Installation & Setup
🤖 Step 1: Create a Telegram Bot
- Search for @BotFather on Telegram
- Send the
/newbotcommand - Choose a name for your bot (e.g.,
My Form Notifier) - Choose a username ending with
bot(e.g.,myform_notify_bot) -
Copy the Bot Token. Format:
123456789:ABCdefGhIJKlmNoPQRsTUVwxyz_0123456789
💬 Step 2: Get Your Chat ID
- Send
/startto your bot on Telegram -
Open this URL in your browser (replace with your token):
https://api.telegram.org/bot{YOUR_BOT_TOKEN}/getUpdates
-
In the JSON response, find
"chat": {"id": ...}. That number is your Chat ID.
💡 Tip: To send notifications to a group, add the bot to the group and use the group’s Chat ID (a negative number).
⚙️ Step 3: Activate in WordPress
- Log in to your WordPress admin dashboard
- Navigate to Easy Form Builder > Telegram in the sidebar menu
- Enter your Bot Token
- Enter your Chat ID (separate multiple IDs with commas)
- Click Test Connection and wait for a success message
- Save your settings
5. Admin Panel Settings
The Telegram settings page is accessible from Easy Form Builder > Telegram.
The UI is dynamically built using JavaScript.
Main Settings Fields
| Field | Description | Example |
|---|---|---|
| Bot Token | Bot token obtained from BotFather | 123456:ABCdef... |
| Chat ID | Recipient chat identifier (numeric) | 987654321 |
| Enabled | Toggle automatic sending on/off | 1 or 0 |
Action Buttons
| Button | AJAX Action | Function |
|---|---|---|
| Test Connection | test_telegram_connection_efb |
Validates Bot Token by calling getMe |
| Send Test | send_telegram_test_efb |
Sends a test message to the Chat ID |
| Save Settings | save_telegram_settings_efb |
Saves settings to wp_options |
| View Activity | load_telegram_activity_efb |
Displays the sent message log |
| Clear Activity | clear_telegram_activity_efb |
Clears all logs |
6. Form Configuration
Each form can have its own Telegram settings. These settings are stored in the emsfb_telegram_contact table.
Configurable Parameters Per Form
| Parameter | Description |
|---|---|
admin_chat_ids |
List of admin Chat IDs (comma-separated) |
bot_token |
Bot Token specific to this form |
received_message_noti_user |
Confirmation message sent to the user upon form receipt |
new_message_noti_user |
New message notification sent to the user |
new_message_noti_admin |
New message notification sent to the admin |
new_response_noti |
New response notification |
💡 Note: If a form-specific Bot Token is not set, the global Bot Token (from the main settings) will be used.
7. Onboarding System
The onboarding system allows admins to retrieve their Chat ID automatically
using a simple link, without manual input.
Onboarding Flow
Admin generates onboarding link
→
User opens the link
→
Bot receives /start
→
Chat ID is saved
How It Works
-
The function
generate_onboarding_link_efb()creates a unique link with a temporary token -
The user clicks the link
https://t.me/BOT?start=...and the/startcommand is sent -
The function
handle_webhook_efb()receives the message, validates the token, and stores the Chat ID inemsfb_telegram_contact -
User information (name, username) is saved to the
emsfb_telegram_userstable - The user receives a confirmation message
8. Notification System
When a form is submitted on the website, the Telegram notification system is triggered automatically.
Notification Process
- A user submits the form
-
The action
efb_send_telegram_notificationis fired -
The function
telegram_ready_for_send_efb()checks the form settings and Bot Token - The message text is built based on the defined template (with HTML support)
- The message is sent to all Chat IDs registered for that form
-
The send result is logged in the
emsfb_telegram_sent_listtable
Message Format
Messages support Telegram’s HTML parse_mode. Allowed tags:
<b>Bold text</b>
<i>Italic text</i>
<code>Code</code>
<a href=”URL”>Link</a>
<i>Italic text</i>
<code>Code</code>
<a href=”URL”>Link</a>
⚠️ Note: Newline characters
\n and @n# are automatically converted to line breaks.
9. Hooks & Filters (For Developers)
Action: Send Telegram Notification
// Send a Telegram notification for a form
do_action(‘efb_send_telegram_notification’, $chat_ids, $message, $form_id, $bot_token);
do_action(‘efb_send_telegram_notification’, $chat_ids, $message, $form_id, $bot_token);
Filter: Full Notification Control
// Full control over the Telegram notification process
$result = apply_filters(
‘efb_handle_telegram_notification’,
$default_result,
$form_id,
$admin_chat_ids,
$bot_token,
$received_msg,
$new_msg_user,
$new_msg_admin,
$new_response
);
$result = apply_filters(
‘efb_handle_telegram_notification’,
$default_result,
$form_id,
$admin_chat_ids,
$bot_token,
$received_msg,
$new_msg_user,
$new_msg_admin,
$new_response
);
Filter: Modify Settings
// Filter settings when reading
add_filter(‘Emsfb_get_settings’, function($settings) {
// Apply custom modifications to settings
return $settings;
});
add_filter(‘Emsfb_get_settings’, function($settings) {
// Apply custom modifications to settings
return $settings;
});
Example: Send a Custom Message
// Send a custom message using the EFB Telegram addon
$telegram = new \Emsfb\telegramsendefb();
$result = $telegram->send_telegram_efb(
‘123456789’, // Chat ID(s)
‘<b>Test message</b>’, // Message (HTML)
$form_id, // Form ID
$bot_token // Bot Token
);
$telegram = new \Emsfb\telegramsendefb();
$result = $telegram->send_telegram_efb(
‘123456789’, // Chat ID(s)
‘<b>Test message</b>’, // Message (HTML)
$form_id, // Form ID
$bot_token // Bot Token
);
10. Database Schema
Table 1: {prefix}_emsfb_telegram_sent_list
Log of all sent messages
| Column | Type | Description |
|---|---|---|
id |
INT AUTO_INCREMENT | Primary key |
chat_id |
VARCHAR(255) | Recipient chat identifier |
message |
TEXT | Sent message text |
status |
VARCHAR(20) | sent or failed |
date |
DATETIME | Date sent |
form_id |
INT | Related form ID |
message_id |
VARCHAR(50) | Telegram message ID |
error_message |
TEXT | Error text (on failure) |
phone_number |
VARCHAR(20) | Phone number (optional) |
by |
VARCHAR(50) | Sender (default: admin) |
Table 2: {prefix}_emsfb_telegram_contact
Per-form Telegram settings
| Column | Type | Description |
|---|---|---|
id |
INT AUTO_INCREMENT | Primary key |
admin_chat_ids |
TEXT | Chat ID list (comma-separated) |
form_id |
INT | Form ID |
bot_token |
VARCHAR(255) | Bot Token |
received_message_noti_user |
TEXT | Receipt confirmation message template |
new_message_noti_user |
TEXT | New message notification template (user) |
new_message_noti_admin |
TEXT | New message notification template (admin) |
new_response_noti |
TEXT | New response notification template |
onboarding_token |
VARCHAR(50) | Temporary onboarding token |
is_active |
TINYINT(1) | Active/inactive |
date |
DATETIME | Date created |
Related wp_options
| Option Name | Description |
|---|---|
emsfb_telegram_bot_token |
Global Bot Token |
emsfb_telegram_chat_id |
Global Chat ID |
emsfb_telegram_enabled |
Enabled status |
Emsfb_telegram_efb |
Settings array |
emsfb_telegram_table_version |
Table version (primary class) |
emsfb_telegram_adv_table_version |
Table version (secondary class) |
emsfb_telegram_cap_added |
Whether capability has been added |
emsfb_addon_AdnTLG |
Addon status (2 = active) |
11. AJAX Actions Reference
🔒 All AJAX calls require a nonce:
wp_rest (sent in the header or request body)
| Action | Class | Parameters | Description |
|---|---|---|---|
test_telegram_connection_efb |
telegramlistefb | bot_token, nonce |
Test connection (getMe) |
send_telegram_test_efb |
telegramlistefb | chat_id, msg, bot_token, nonce |
Send test message |
save_telegram_settings_efb |
telegramlistefb | bot_token, chat_id, enabled, nonce |
Save settings |
load_telegram_activity_efb |
telegramlistefb | nonce |
Load sent message log |
clear_telegram_activity_efb |
telegramlistefb | nonce |
Clear all logs |
verify_telegram_bot_efb |
telegramsendefb | bot_token, nonce |
Validate Bot Token |
telegram_activate_efb |
telegramsendefb | form_id, _wpnonce |
Activate onboarding |
send_business_telegram_efb |
telegramsendefb | phone, message, form_id, nonce |
Send business message |
telegram_check_status_efb |
telegramsendefb | form_id, _wpnonce |
Check activation status |
12. Security Notes
✅ Implemented Security Measures:
| # | Security Item | Status |
|---|---|---|
| 1 | Nonce verification on all AJAX calls | ✅ check_ajax_referer('wp_rest', 'nonce') |
| 2 | Custom capability check | ✅ current_user_can('Emsfb_telegram_efb') |
| 3 | SQL Injection prevention | ✅ $wpdb->prepare() on all queries |
| 4 | XSS prevention | ✅ sanitize_text_field() and wp_json_encode() |
| 5 | Direct file access prevention | ✅ if (!defined('ABSPATH')) exit; |
| 6 | Conditional debug logging | ✅ Only when WP_DEBUG is enabled |
| 7 | Version-based table creation | ✅ Prevents redundant dbDelta execution |
13. Troubleshooting
❌ Problem: Telegram Menu Not Showing
- Check that the Pro version is active and the
emsfb_addon_AdnTLGvalue in the database is greater than or equal to 1 - Ensure the file
class-Emsfb-telegram.phpexists in thevendor/telegram/directory - The capability
Emsfb_telegram_efbmust be assigned to the Administrator role
❌ Problem: Test Connection Error
- Re-copy the Bot Token from BotFather
- Ensure the token follows the format
123456789:ABC... - Verify the server can connect to
api.telegram.org - Check that no firewall or security plugin is blocking outbound connections
❌ Problem: Messages Not Being Sent
- Ensure the Chat ID is correct (send
/startto the bot first) - For groups, the bot must be a member of the group
- Group Chat IDs are negative numbers (e.g.,
-1001234567890) - The Enabled field must be active
❌ Problem: 403 Forbidden Error
- The bot has been blocked by the user — the user must unblock the bot and send
/startagain - The bot has been removed from the group — add the bot back to the group
🐛 Enable Debug Logging
To view full logs, add the following to your wp-config.php:
define(‘WP_DEBUG’, true);
define(‘WP_DEBUG_LOG’, true);
define(‘WP_DEBUG_LOG’, true);
Then check the file wp-content/debug.log. Telegram logs are prefixed with [EFB Telegram].
WhiteStudio.team