📨 دليل إضافة تيليجرام
منشئ النماذج السهل من WhiteStudio – تكامل تيليجرام
الإصدار 1.0.0
1. نظرة عامة
تقوم إضافة تيليجرام لـ منشئ النماذج السهل بربط نماذج ووردبريس الخاصة بك مع بوت تيليجرام.
عند التفعيل، يؤدي كل إرسال نموذج إلى تشغيل إشعار يُرسل إلى معرّف المحادثة (Chat ID) الخاص بالمشرف (أو عدة مستلمين) عبر واجهة برمجة تطبيقات تيليجرام.
الميزات الرئيسية
- الاتصال بتيليجرام عبر رمز البوت (Bot Token)
- إشعارات تلقائية عند إرسال النموذج
- إعداد معرّف محادثة منفصل لكل نموذج
- إرسال رسائل اختبارية من لوحة الإدارة
- نظام تسجيل تمهيدي لاسترداد معرّف المحادثة تلقائياً
- سجل نشاط الرسائل المرسلة
- دعم HTML في محتوى الرسائل
- الإرسال إلى عدة معرّفات محادثة في وقت واحد
كيف يعمل
المستخدم يرسل النموذج
→
يتم تشغيل خطاف النموذج
→
يتم إنشاء الرسالة
→
استدعاء واجهة تيليجرام
→
تم تسليم الرسالة
2. هيكل الملفات
vendor/telegram/
├── class-Emsfb-telegram.php // الفئة الرئيسية: القائمة، الإعدادات، AJAX الإداري
├── telegram-new-efb.php // الفئة المتقدمة: الإرسال، التسجيل التمهيدي، الويب هوك
├── onboarding.html // صفحة التسجيل التمهيدي للمستخدم
├── guide.html // هذا الدليل (EN)
├── guide-ar.html // هذا الدليل (AR)
└── assets/
├── css/
│ └── telegram-efb.css // أنماط صفحة الإعدادات
└── js/
└── telegram-efb.js // واجهة المستخدم الديناميكية (jQuery)
├── class-Emsfb-telegram.php // الفئة الرئيسية: القائمة، الإعدادات، AJAX الإداري
├── telegram-new-efb.php // الفئة المتقدمة: الإرسال، التسجيل التمهيدي، الويب هوك
├── onboarding.html // صفحة التسجيل التمهيدي للمستخدم
├── guide.html // هذا الدليل (EN)
├── guide-ar.html // هذا الدليل (AR)
└── assets/
├── css/
│ └── telegram-efb.css // أنماط صفحة الإعدادات
└── js/
└── telegram-efb.js // واجهة المستخدم الديناميكية (jQuery)
| الملف | الفئة | المسؤولية |
|---|---|---|
class-Emsfb-telegram.php |
telegramlistefb |
قائمة الإدارة، صفحة الإعدادات، معالجات AJAX (اختبار، حفظ، سجل) |
telegram-new-efb.php |
telegramsendefb |
إرسال الرسائل، إدارة المستخدمين، التسجيل التمهيدي، الويب هوك، خطافات النماذج |
3. المتطلبات الأساسية
- ووردبريس 5.0 أو أعلى
- إضافة منشئ النماذج السهل مثبتة ومفعلة
- النسخة الاحترافية (Pro) مفعلة (إضافة تيليجرام متاحة فقط في النسخة الاحترافية)
- بوت تيليجرام تم إنشاؤه عبر @BotFather
- يجب أن يسمح الخادم بالاتصالات الصادرة إلى
api.telegram.org(المنفذ 443)
4. التثبيت والإعداد
🤖 الخطوة 1: إنشاء بوت تيليجرام
- ابحث عن @BotFather في تيليجرام
- أرسل الأمر
/newbot - اختر اسماً للبوت الخاص بك (مثال:
My Form Notifier) - اختر اسم مستخدم ينتهي بـ
bot(مثال:myform_notify_bot) -
انسخ رمز البوت (Bot Token). الصيغة:
123456789:ABCdefGhIJKlmNoPQRsTUVwxyz_0123456789
💬 الخطوة 2: الحصول على معرّف المحادثة (Chat ID)
- أرسل
/startإلى البوت الخاص بك في تيليجرام -
افتح هذا الرابط في المتصفح (استبدل الرمز الخاص بك):
https://api.telegram.org/bot{YOUR_BOT_TOKEN}/getUpdates
-
في استجابة JSON، ابحث عن
"chat": {"id": ...}. هذا الرقم هو معرّف المحادثة الخاص بك.
💡 نصيحة: لإرسال الإشعارات إلى مجموعة، أضف البوت إلى المجموعة واستخدم معرّف محادثة المجموعة (رقم سالب).
⚙️ الخطوة 3: التفعيل في ووردبريس
- سجّل الدخول إلى لوحة إدارة ووردبريس الخاصة بك
- انتقل إلى منشئ النماذج السهل > Telegram في القائمة الجانبية
- أدخل رمز البوت (Bot Token) الخاص بك
- أدخل معرّف المحادثة (Chat ID) الخاص بك (افصل بين المعرّفات المتعددة بفواصل)
- انقر على اختبار الاتصال وانتظر رسالة النجاح
- احفظ إعداداتك
5. إعدادات لوحة الإدارة
يمكن الوصول إلى صفحة إعدادات تيليجرام من منشئ النماذج السهل > Telegram.
يتم بناء واجهة المستخدم ديناميكياً باستخدام JavaScript.
حقول الإعدادات الرئيسية
| الحقل | الوصف | مثال |
|---|---|---|
| رمز البوت (Bot Token) | رمز البوت الذي تم الحصول عليه من BotFather | 123456:ABCdef... |
| معرّف المحادثة (Chat ID) | معرّف محادثة المستلم (رقمي) | 987654321 |
| مفعّل | تشغيل/إيقاف الإرسال التلقائي | 1 أو 0 |
أزرار الإجراءات
| الزر | إجراء AJAX | الوظيفة |
|---|---|---|
| اختبار الاتصال | test_telegram_connection_efb |
التحقق من رمز البوت عن طريق استدعاء getMe |
| إرسال اختبار | send_telegram_test_efb |
إرسال رسالة اختبارية إلى معرّف المحادثة |
| حفظ الإعدادات | save_telegram_settings_efb |
حفظ الإعدادات في wp_options |
| عرض النشاط | load_telegram_activity_efb |
عرض سجل الرسائل المرسلة |
| مسح النشاط | clear_telegram_activity_efb |
مسح جميع السجلات |
6. إعدادات النموذج
يمكن أن يكون لكل نموذج إعدادات تيليجرام خاصة به. يتم تخزين هذه الإعدادات في جدول emsfb_telegram_contact.
المعلمات القابلة للتكوين لكل نموذج
| المعلمة | الوصف |
|---|---|
admin_chat_ids |
قائمة معرّفات محادثة المشرف (مفصولة بفواصل) |
bot_token |
رمز البوت الخاص بهذا النموذج |
received_message_noti_user |
رسالة التأكيد المرسلة إلى المستخدم عند استلام النموذج |
new_message_noti_user |
إشعار الرسالة الجديدة المرسل إلى المستخدم |
new_message_noti_admin |
إشعار الرسالة الجديدة المرسل إلى المشرف |
new_response_noti |
إشعار الرد الجديد |
💡 ملاحظة: إذا لم يتم تعيين رمز بوت خاص بالنموذج، سيتم استخدام رمز البوت العام (من الإعدادات الرئيسية).
7. نظام التسجيل التمهيدي (Onboarding)
يتيح نظام التسجيل التمهيدي للمشرفين استرداد معرّف المحادثة الخاص بهم تلقائياً
باستخدام رابط بسيط، دون إدخال يدوي.
مسار التسجيل التمهيدي
المشرف ينشئ رابط التسجيل
→
المستخدم يفتح الرابط
→
البوت يستقبل /start
→
يتم حفظ معرّف المحادثة
كيف يعمل
-
تقوم الدالة
generate_onboarding_link_efb()بإنشاء رابط فريد مع رمز مؤقت -
ينقر المستخدم على الرابط
https://t.me/BOT?start=...ويتم إرسال أمر/start -
تستقبل الدالة
handle_webhook_efb()الرسالة، وتتحقق من الرمز، وتخزّن معرّف المحادثة فيemsfb_telegram_contact -
يتم حفظ معلومات المستخدم (الاسم، اسم المستخدم) في جدول
emsfb_telegram_users - يتلقى المستخدم رسالة تأكيد
8. نظام الإشعارات
عند إرسال نموذج على الموقع، يتم تشغيل نظام إشعارات تيليجرام تلقائياً.
عملية الإشعار
- يقوم المستخدم بإرسال النموذج
-
يتم تشغيل الإجراء
efb_send_telegram_notification -
تتحقق الدالة
telegram_ready_for_send_efb()من إعدادات النموذج ورمز البوت - يتم بناء نص الرسالة بناءً على القالب المحدد (مع دعم HTML)
- يتم إرسال الرسالة إلى جميع معرّفات المحادثة المسجلة لهذا النموذج
-
يتم تسجيل نتيجة الإرسال في جدول
emsfb_telegram_sent_list
تنسيق الرسالة
تدعم الرسائل وضع HTML parse_mode في تيليجرام. العلامات المسموح بها:
<b>نص عريض</b>
<i>نص مائل</i>
<code>كود</code>
<a href=”URL”>رابط</a>
<i>نص مائل</i>
<code>كود</code>
<a href=”URL”>رابط</a>
⚠️ ملاحظة: يتم تحويل أحرف السطر الجديد
\n و @n# تلقائياً إلى فواصل أسطر.
9. الخطافات والفلاتر (للمطورين)
إجراء: إرسال إشعار تيليجرام
// إرسال إشعار تيليجرام لنموذج
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);
فلتر: التحكم الكامل في الإشعارات
// التحكم الكامل في عملية إشعار تيليجرام
$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
);
فلتر: تعديل الإعدادات
// فلترة الإعدادات عند القراءة
add_filter(‘Emsfb_get_settings’, function($settings) {
// تطبيق تعديلات مخصصة على الإعدادات
return $settings;
});
add_filter(‘Emsfb_get_settings’, function($settings) {
// تطبيق تعديلات مخصصة على الإعدادات
return $settings;
});
مثال: إرسال رسالة مخصصة
// إرسال رسالة مخصصة باستخدام إضافة EFB تيليجرام
$telegram = new \Emsfb\telegramsendefb();
$result = $telegram->send_telegram_efb(
‘123456789’, // معرّف(ات) المحادثة
‘<b>رسالة اختبار</b>’, // الرسالة (HTML)
$form_id, // معرّف النموذج
$bot_token // رمز البوت
);
$telegram = new \Emsfb\telegramsendefb();
$result = $telegram->send_telegram_efb(
‘123456789’, // معرّف(ات) المحادثة
‘<b>رسالة اختبار</b>’, // الرسالة (HTML)
$form_id, // معرّف النموذج
$bot_token // رمز البوت
);
10. مخطط قاعدة البيانات
الجدول 1: {prefix}_emsfb_telegram_sent_list
سجل جميع الرسائل المرسلة
| العمود | النوع | الوصف |
|---|---|---|
id |
INT AUTO_INCREMENT | المفتاح الأساسي |
chat_id |
VARCHAR(255) | معرّف محادثة المستلم |
message |
TEXT | نص الرسالة المرسلة |
status |
VARCHAR(20) | sent أو failed |
date |
DATETIME | تاريخ الإرسال |
form_id |
INT | معرّف النموذج المرتبط |
message_id |
VARCHAR(50) | معرّف رسالة تيليجرام |
error_message |
TEXT | نص الخطأ (عند الفشل) |
phone_number |
VARCHAR(20) | رقم الهاتف (اختياري) |
by |
VARCHAR(50) | المرسل (الافتراضي: admin) |
الجدول 2: {prefix}_emsfb_telegram_contact
إعدادات تيليجرام لكل نموذج
| العمود | النوع | الوصف |
|---|---|---|
id |
INT AUTO_INCREMENT | المفتاح الأساسي |
admin_chat_ids |
TEXT | قائمة معرّفات المحادثة (مفصولة بفواصل) |
form_id |
INT | معرّف النموذج |
bot_token |
VARCHAR(255) | رمز البوت |
received_message_noti_user |
TEXT | قالب رسالة تأكيد الاستلام |
new_message_noti_user |
TEXT | قالب إشعار الرسالة الجديدة (المستخدم) |
new_message_noti_admin |
TEXT | قالب إشعار الرسالة الجديدة (المشرف) |
new_response_noti |
TEXT | قالب إشعار الرد الجديد |
onboarding_token |
VARCHAR(50) | رمز التسجيل التمهيدي المؤقت |
is_active |
TINYINT(1) | نشط/غير نشط |
date |
DATETIME | تاريخ الإنشاء |
خيارات wp_options المرتبطة
| اسم الخيار | الوصف |
|---|---|
emsfb_telegram_bot_token |
رمز البوت العام |
emsfb_telegram_chat_id |
معرّف المحادثة العام |
emsfb_telegram_enabled |
حالة التفعيل |
Emsfb_telegram_efb |
مصفوفة الإعدادات |
emsfb_telegram_table_version |
إصدار الجدول (الفئة الأساسية) |
emsfb_telegram_adv_table_version |
إصدار الجدول (الفئة الثانوية) |
emsfb_telegram_cap_added |
ما إذا تمت إضافة الصلاحية |
emsfb_addon_AdnTLG |
حالة الإضافة (2 = نشطة) |
11. مرجع إجراءات AJAX
🔒 جميع استدعاءات AJAX تتطلب رمز nonce:
wp_rest (يُرسل في الرأس أو جسم الطلب)
| الإجراء | الفئة | المعلمات | الوصف |
|---|---|---|---|
test_telegram_connection_efb |
telegramlistefb | bot_token, nonce |
اختبار الاتصال (getMe) |
send_telegram_test_efb |
telegramlistefb | chat_id, msg, bot_token, nonce |
إرسال رسالة اختبارية |
save_telegram_settings_efb |
telegramlistefb | bot_token, chat_id, enabled, nonce |
حفظ الإعدادات |
load_telegram_activity_efb |
telegramlistefb | nonce |
تحميل سجل الرسائل المرسلة |
clear_telegram_activity_efb |
telegramlistefb | nonce |
مسح جميع السجلات |
verify_telegram_bot_efb |
telegramsendefb | bot_token, nonce |
التحقق من رمز البوت |
telegram_activate_efb |
telegramsendefb | form_id, _wpnonce |
تفعيل التسجيل التمهيدي |
send_business_telegram_efb |
telegramsendefb | phone, message, form_id, nonce |
إرسال رسالة تجارية |
telegram_check_status_efb |
telegramsendefb | form_id, _wpnonce |
التحقق من حالة التفعيل |
12. ملاحظات أمنية
✅ إجراءات الأمان المطبقة:
| # | عنصر الأمان | الحالة |
|---|---|---|
| 1 | التحقق من Nonce في جميع استدعاءات AJAX | ✅ check_ajax_referer('wp_rest', 'nonce') |
| 2 | فحص الصلاحيات المخصصة | ✅ current_user_can('Emsfb_telegram_efb') |
| 3 | منع حقن SQL | ✅ $wpdb->prepare() في جميع الاستعلامات |
| 4 | منع XSS | ✅ sanitize_text_field() و wp_json_encode() |
| 5 | منع الوصول المباشر للملفات | ✅ if (!defined('ABSPATH')) exit; |
| 6 | تسجيل التصحيح المشروط | ✅ فقط عند تفعيل WP_DEBUG |
| 7 | إنشاء الجداول بناءً على الإصدار | ✅ يمنع تنفيذ dbDelta المتكرر |
13. استكشاف الأخطاء وإصلاحها
❌ المشكلة: قائمة تيليجرام لا تظهر
- تحقق من أن النسخة الاحترافية نشطة وأن قيمة
emsfb_addon_AdnTLGفي قاعدة البيانات تساوي 1 أو أكثر - تأكد من وجود الملف
class-Emsfb-telegram.phpفي مجلدvendor/telegram/ - يجب أن تكون صلاحية
Emsfb_telegram_efbمخصصة لدور المدير (Administrator)
❌ المشكلة: خطأ في اختبار الاتصال
- أعد نسخ رمز البوت من BotFather
- تأكد من أن الرمز يتبع الصيغة
123456789:ABC... - تحقق من أن الخادم يمكنه الاتصال بـ
api.telegram.org - تأكد من عدم وجود جدار حماية أو إضافة أمان تحظر الاتصالات الصادرة
❌ المشكلة: الرسائل لا تُرسل
- تأكد من صحة معرّف المحادثة (أرسل
/startإلى البوت أولاً) - بالنسبة للمجموعات، يجب أن يكون البوت عضواً في المجموعة
- معرّفات محادثة المجموعات هي أرقام سالبة (مثال:
-1001234567890) - يجب أن يكون حقل “مفعّل” نشطاً
❌ المشكلة: خطأ 403 Forbidden
- تم حظر البوت من قبل المستخدم — يجب على المستخدم إلغاء الحظر وإرسال
/startمرة أخرى - تمت إزالة البوت من المجموعة — أعد إضافة البوت إلى المجموعة
🐛 تفعيل تسجيل التصحيح
لعرض السجلات الكاملة، أضف ما يلي إلى ملف wp-config.php:
define(‘WP_DEBUG’, true);
define(‘WP_DEBUG_LOG’, true);
define(‘WP_DEBUG_LOG’, true);
ثم تحقق من ملف wp-content/debug.log. سجلات تيليجرام تبدأ بالبادئة [EFB Telegram].
منشئ النماذج السهل