📨 Telegram-Addon-Anleitung
Easy Form Builder von WhiteStudio – Telegram-Integration
Version 1.0.0
1. Übersicht
Das Telegram-Addon für Easy Form Builder verbindet Ihre WordPress-Formulare mit einem Telegram-Bot.
Wenn aktiviert, löst jede Formularübermittlung eine Benachrichtigung aus, die über die Telegram Bot API an die Chat-ID des Administrators (oder mehrere Empfänger) gesendet wird.
Hauptfunktionen
- Verbindung zu Telegram über Bot-Token
- Automatische Benachrichtigungen bei Formularübermittlung
- Separate Chat-ID-Konfiguration pro Formular
- Testnachrichten direkt aus dem Admin-Panel senden
- Onboarding-System zur automatischen Chat-ID-Ermittlung
- Aktivitätsprotokoll gesendeter Nachrichten
- HTML-Unterstützung im Nachrichteninhalt
- Gleichzeitiger Versand an mehrere Chat-IDs
Funktionsweise
Benutzer sendet Formular ab
→
Formular-Hook wird ausgelöst
→
Nachricht wird erstellt
→
Telegram API wird aufgerufen
→
Nachricht zugestellt
2. Dateistruktur
vendor/telegram/
├── class-Emsfb-telegram.php // Hauptklasse: Menü, Einstellungen, Admin-AJAX
├── telegram-new-efb.php // Erweiterte Klasse: Versand, Onboarding, Webhook
├── onboarding.html // Benutzer-Onboarding-Seite
├── guide.html // Diese Anleitung (EN)
├── guide-de.html // Diese Anleitung (DE)
└── assets/
├── css/
│ └── telegram-efb.css // Styles der Einstellungsseite
└── js/
└── telegram-efb.js // Dynamische UI (jQuery)
├── class-Emsfb-telegram.php // Hauptklasse: Menü, Einstellungen, Admin-AJAX
├── telegram-new-efb.php // Erweiterte Klasse: Versand, Onboarding, Webhook
├── onboarding.html // Benutzer-Onboarding-Seite
├── guide.html // Diese Anleitung (EN)
├── guide-de.html // Diese Anleitung (DE)
└── assets/
├── css/
│ └── telegram-efb.css // Styles der Einstellungsseite
└── js/
└── telegram-efb.js // Dynamische UI (jQuery)
| Datei | Klasse | Zuständigkeit |
|---|---|---|
class-Emsfb-telegram.php |
telegramlistefb |
Admin-Menü, Einstellungsseite, AJAX-Handler (Test, Speichern, Protokoll) |
telegram-new-efb.php |
telegramsendefb |
Nachrichtenversand, Benutzerverwaltung, Onboarding, Webhook, Formular-Hooks |
3. Voraussetzungen
- WordPress 5.0 oder höher
- Easy Form Builder Plugin installiert und aktiviert
- Pro-Version aktiviert (das Telegram-Addon ist nur in der Pro-Edition verfügbar)
- Ein Telegram-Bot, erstellt über @BotFather
- Der Server muss ausgehende Verbindungen zu
api.telegram.org(Port 443) erlauben
4. Installation & Einrichtung
🤖 Schritt 1: Telegram-Bot erstellen
- Suchen Sie in Telegram nach @BotFather
- Senden Sie den Befehl
/newbot - Wählen Sie einen Namen für Ihren Bot (z.B.
Mein Formular-Benachrichtiger) - Wählen Sie einen Benutzernamen, der auf
botendet (z.B.meinformular_notify_bot) -
Kopieren Sie den Bot-Token. Format:
123456789:ABCdefGhIJKlmNoPQRsTUVwxyz_0123456789
💬 Schritt 2: Chat-ID ermitteln
- Senden Sie
/startan Ihren Bot in Telegram -
Öffnen Sie diese URL in Ihrem Browser (ersetzen Sie Ihren Token):
https://api.telegram.org/bot{IHR_BOT_TOKEN}/getUpdates
-
In der JSON-Antwort finden Sie
"chat": {"id": ...}. Diese Zahl ist Ihre Chat-ID.
💡 Tipp: Um Benachrichtigungen an eine Gruppe zu senden, fügen Sie den Bot zur Gruppe hinzu und verwenden Sie die Chat-ID der Gruppe (eine negative Zahl).
⚙️ Schritt 3: In WordPress aktivieren
- Melden Sie sich in Ihrem WordPress-Admin-Dashboard an
- Navigieren Sie zu Easy Form Builder > Telegram in der Seitenleiste
- Geben Sie Ihren Bot-Token ein
- Geben Sie Ihre Chat-ID ein (mehrere IDs mit Kommas trennen)
- Klicken Sie auf Verbindung testen und warten Sie auf eine Erfolgsmeldung
- Speichern Sie Ihre Einstellungen
5. Admin-Panel-Einstellungen
Die Telegram-Einstellungsseite ist über Easy Form Builder > Telegram erreichbar.
Die Benutzeroberfläche wird dynamisch mit JavaScript erstellt.
Haupteinstellungsfelder
| Feld | Beschreibung | Beispiel |
|---|---|---|
| Bot-Token | Von BotFather erhaltener Bot-Token | 123456:ABCdef... |
| Chat-ID | Chat-Kennung des Empfängers (numerisch) | 987654321 |
| Aktiviert | Automatischen Versand ein-/ausschalten | 1 oder 0 |
Aktionsschaltflächen
| Schaltfläche | AJAX-Aktion | Funktion |
|---|---|---|
| Verbindung testen | test_telegram_connection_efb |
Validiert den Bot-Token durch Aufruf von getMe |
| Testnachricht senden | send_telegram_test_efb |
Sendet eine Testnachricht an die Chat-ID |
| Einstellungen speichern | save_telegram_settings_efb |
Speichert Einstellungen in wp_options |
| Aktivität anzeigen | load_telegram_activity_efb |
Zeigt das Protokoll gesendeter Nachrichten an |
| Aktivität löschen | clear_telegram_activity_efb |
Löscht alle Protokolle |
6. Formularkonfiguration
Jedes Formular kann eigene Telegram-Einstellungen haben. Diese Einstellungen werden in der Tabelle emsfb_telegram_contact gespeichert.
Konfigurierbare Parameter pro Formular
| Parameter | Beschreibung |
|---|---|
admin_chat_ids |
Liste der Admin-Chat-IDs (kommagetrennt) |
bot_token |
Formularspezifischer Bot-Token |
received_message_noti_user |
Bestätigungsnachricht an den Benutzer bei Formulareingang |
new_message_noti_user |
Neue-Nachricht-Benachrichtigung an den Benutzer |
new_message_noti_admin |
Neue-Nachricht-Benachrichtigung an den Administrator |
new_response_noti |
Neue-Antwort-Benachrichtigung |
💡 Hinweis: Wenn kein formularspezifischer Bot-Token festgelegt ist, wird der globale Bot-Token (aus den Haupteinstellungen) verwendet.
7. Onboarding-System
Das Onboarding-System ermöglicht es Administratoren, ihre Chat-ID automatisch
über einen einfachen Link abzurufen, ohne manuelle Eingabe.
Onboarding-Ablauf
Admin erstellt Onboarding-Link
→
Benutzer öffnet den Link
→
Bot empfängt /start
→
Chat-ID wird gespeichert
Funktionsweise
-
Die Funktion
generate_onboarding_link_efb()erstellt einen eindeutigen Link mit einem temporären Token -
Der Benutzer klickt auf den Link
https://t.me/BOT?start=...und der Befehl/startwird gesendet -
Die Funktion
handle_webhook_efb()empfängt die Nachricht, validiert den Token und speichert die Chat-ID inemsfb_telegram_contact -
Benutzerinformationen (Name, Benutzername) werden in der Tabelle
emsfb_telegram_usersgespeichert - Der Benutzer erhält eine Bestätigungsnachricht
8. Benachrichtigungssystem
Wenn ein Formular auf der Website abgesendet wird, wird das Telegram-Benachrichtigungssystem automatisch ausgelöst.
Benachrichtigungsprozess
- Ein Benutzer sendet das Formular ab
-
Die Aktion
efb_send_telegram_notificationwird ausgelöst -
Die Funktion
telegram_ready_for_send_efb()prüft die Formulareinstellungen und den Bot-Token - Der Nachrichtentext wird basierend auf der definierten Vorlage erstellt (mit HTML-Unterstützung)
- Die Nachricht wird an alle für dieses Formular registrierten Chat-IDs gesendet
-
Das Sendeergebnis wird in der Tabelle
emsfb_telegram_sent_listprotokolliert
Nachrichtenformat
Nachrichten unterstützen Telegrams HTML parse_mode. Erlaubte Tags:
<b>Fetter Text</b>
<i>Kursiver Text</i>
<code>Code</code>
<a href=“URL“>Link</a>
<i>Kursiver Text</i>
<code>Code</code>
<a href=“URL“>Link</a>
⚠️ Hinweis: Zeilenumbruchzeichen
\n und @n# werden automatisch in Zeilenumbrüche umgewandelt.
9. Hooks & Filter (Für Entwickler)
Action: Telegram-Benachrichtigung senden
// Telegram-Benachrichtigung für ein Formular senden
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: Vollständige Benachrichtigungssteuerung
// Vollständige Kontrolle über den Telegram-Benachrichtigungsprozess
$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: Einstellungen ändern
// Einstellungen beim Lesen filtern
add_filter(‚Emsfb_get_settings‘, function($settings) {
// Benutzerdefinierte Änderungen an den Einstellungen vornehmen
return $settings;
});
add_filter(‚Emsfb_get_settings‘, function($settings) {
// Benutzerdefinierte Änderungen an den Einstellungen vornehmen
return $settings;
});
Beispiel: Benutzerdefinierte Nachricht senden
// Benutzerdefinierte Nachricht über das EFB Telegram-Addon senden
$telegram = new \Emsfb\telegramsendefb();
$result = $telegram->send_telegram_efb(
‚123456789‘, // Chat-ID(s)
‚<b>Testnachricht</b>‘, // Nachricht (HTML)
$form_id, // Formular-ID
$bot_token // Bot-Token
);
$telegram = new \Emsfb\telegramsendefb();
$result = $telegram->send_telegram_efb(
‚123456789‘, // Chat-ID(s)
‚<b>Testnachricht</b>‘, // Nachricht (HTML)
$form_id, // Formular-ID
$bot_token // Bot-Token
);
10. Datenbankschema
Tabelle 1: {prefix}_emsfb_telegram_sent_list
Protokoll aller gesendeten Nachrichten
| Spalte | Typ | Beschreibung |
|---|---|---|
id |
INT AUTO_INCREMENT | Primärschlüssel |
chat_id |
VARCHAR(255) | Chat-Kennung des Empfängers |
message |
TEXT | Gesendeter Nachrichtentext |
status |
VARCHAR(20) | sent oder failed |
date |
DATETIME | Sendedatum |
form_id |
INT | Zugehörige Formular-ID |
message_id |
VARCHAR(50) | Telegram-Nachrichten-ID |
error_message |
TEXT | Fehlertext (bei Misserfolg) |
phone_number |
VARCHAR(20) | Telefonnummer (optional) |
by |
VARCHAR(50) | Absender (Standard: admin) |
Tabelle 2: {prefix}_emsfb_telegram_contact
Formularspezifische Telegram-Einstellungen
| Spalte | Typ | Beschreibung |
|---|---|---|
id |
INT AUTO_INCREMENT | Primärschlüssel |
admin_chat_ids |
TEXT | Chat-ID-Liste (kommagetrennt) |
form_id |
INT | Formular-ID |
bot_token |
VARCHAR(255) | Bot-Token |
received_message_noti_user |
TEXT | Vorlage für Empfangsbestätigung |
new_message_noti_user |
TEXT | Vorlage für Neue-Nachricht-Benachrichtigung (Benutzer) |
new_message_noti_admin |
TEXT | Vorlage für Neue-Nachricht-Benachrichtigung (Admin) |
new_response_noti |
TEXT | Vorlage für Neue-Antwort-Benachrichtigung |
onboarding_token |
VARCHAR(50) | Temporärer Onboarding-Token |
is_active |
TINYINT(1) | Aktiv/Inaktiv |
date |
DATETIME | Erstellungsdatum |
Zugehörige wp_options
| Optionsname | Beschreibung |
|---|---|
emsfb_telegram_bot_token |
Globaler Bot-Token |
emsfb_telegram_chat_id |
Globale Chat-ID |
emsfb_telegram_enabled |
Aktivierungsstatus |
Emsfb_telegram_efb |
Einstellungs-Array |
emsfb_telegram_table_version |
Tabellenversion (Hauptklasse) |
emsfb_telegram_adv_table_version |
Tabellenversion (Sekundärklasse) |
emsfb_telegram_cap_added |
Ob Berechtigung hinzugefügt wurde |
emsfb_addon_AdnTLG |
Addon-Status (2 = aktiv) |
11. AJAX-Aktionen-Referenz
🔒 Alle AJAX-Aufrufe erfordern einen Nonce:
wp_rest (gesendet im Header oder im Anfrage-Body)
| Aktion | Klasse | Parameter | Beschreibung |
|---|---|---|---|
test_telegram_connection_efb |
telegramlistefb | bot_token, nonce |
Verbindung testen (getMe) |
send_telegram_test_efb |
telegramlistefb | chat_id, msg, bot_token, nonce |
Testnachricht senden |
save_telegram_settings_efb |
telegramlistefb | bot_token, chat_id, enabled, nonce |
Einstellungen speichern |
load_telegram_activity_efb |
telegramlistefb | nonce |
Protokoll gesendeter Nachrichten laden |
clear_telegram_activity_efb |
telegramlistefb | nonce |
Alle Protokolle löschen |
verify_telegram_bot_efb |
telegramsendefb | bot_token, nonce |
Bot-Token validieren |
telegram_activate_efb |
telegramsendefb | form_id, _wpnonce |
Onboarding aktivieren |
send_business_telegram_efb |
telegramsendefb | phone, message, form_id, nonce |
Geschäftsnachricht senden |
telegram_check_status_efb |
telegramsendefb | form_id, _wpnonce |
Aktivierungsstatus prüfen |
12. Sicherheitshinweise
✅ Implementierte Sicherheitsmaßnahmen:
| # | Sicherheitselement | Status |
|---|---|---|
| 1 | Nonce-Verifizierung bei allen AJAX-Aufrufen | ✅ check_ajax_referer('wp_rest', 'nonce') |
| 2 | Benutzerdefinierte Berechtigungsprüfung | ✅ current_user_can('Emsfb_telegram_efb') |
| 3 | Schutz vor SQL-Injection | ✅ $wpdb->prepare() bei allen Abfragen |
| 4 | Schutz vor XSS | ✅ sanitize_text_field() und wp_json_encode() |
| 5 | Schutz vor direktem Dateizugriff | ✅ if (!defined('ABSPATH')) exit; |
| 6 | Bedingtes Debug-Logging | ✅ Nur wenn WP_DEBUG aktiviert ist |
| 7 | Versionsbasierte Tabellenerstellung | ✅ Verhindert redundante dbDelta-Ausführung |
13. Fehlerbehebung
❌ Problem: Telegram-Menü wird nicht angezeigt
- Prüfen Sie, ob die Pro-Version aktiv ist und der Wert
emsfb_addon_AdnTLGin der Datenbank größer oder gleich 1 ist - Stellen Sie sicher, dass die Datei
class-Emsfb-telegram.phpim Verzeichnisvendor/telegram/vorhanden ist - Die Berechtigung
Emsfb_telegram_efbmuss der Administrator-Rolle zugewiesen sein
❌ Problem: Verbindungstest-Fehler
- Kopieren Sie den Bot-Token erneut aus BotFather
- Stellen Sie sicher, dass der Token dem Format
123456789:ABC...entspricht - Prüfen Sie, ob der Server eine Verbindung zu
api.telegram.orgherstellen kann - Stellen Sie sicher, dass keine Firewall oder Sicherheits-Plugin ausgehende Verbindungen blockiert
❌ Problem: Nachrichten werden nicht gesendet
- Stellen Sie sicher, dass die Chat-ID korrekt ist (senden Sie zuerst
/startan den Bot) - Für Gruppen muss der Bot Mitglied der Gruppe sein
- Gruppen-Chat-IDs sind negative Zahlen (z.B.
-1001234567890) - Das Feld „Aktiviert“ muss eingeschaltet sein
❌ Problem: 403 Forbidden Fehler
- Der Bot wurde vom Benutzer blockiert — der Benutzer muss den Bot entsperren und erneut
/startsenden - Der Bot wurde aus der Gruppe entfernt — fügen Sie den Bot erneut zur Gruppe hinzu
🐛 Debug-Protokollierung aktivieren
Um vollständige Protokolle anzuzeigen, fügen Sie Folgendes in Ihre wp-config.php ein:
define(‚WP_DEBUG‘, true);
define(‚WP_DEBUG_LOG‘, true);
define(‚WP_DEBUG_LOG‘, true);
Prüfen Sie anschließend die Datei wp-content/debug.log. Telegram-Protokolle sind mit dem Präfix [EFB Telegram] gekennzeichnet.
WhiteStudio.team