Entwicklerhandbuch für das Easy Form Builder Telegram-Add-on

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)

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 bot endet (z.B. meinformular_notify_bot)
Kopieren Sie den Bot-Token. Format:

123456789:ABCdefGhIJKlmNoPQRsTUVwxyz_0123456789

💬 Schritt 2: Chat-ID ermitteln

Senden Sie /start an 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 /start wird gesendet
Die Funktion handle_webhook_efb() empfängt die Nachricht, validiert den Token und speichert die Chat-ID in emsfb_telegram_contact
Benutzerinformationen (Name, Benutzername) werden in der Tabelle emsfb_telegram_users gespeichert
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_notification wird 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_list protokolliert

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>

⚠️ 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);

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

);

Filter: Einstellungen ändern

// Einstellungen beim Lesen filtern

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

);

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_AdnTLG in der Datenbank größer oder gleich 1 ist
Stellen Sie sicher, dass die Datei class-Emsfb-telegram.php im Verzeichnis vendor/telegram/ vorhanden ist
Die Berechtigung Emsfb_telegram_efb muss 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.org herstellen 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 /start an 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 /start senden
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);

Prüfen Sie anschließend die Datei wp-content/debug.log. Telegram-Protokolle sind mit dem Präfix [EFB Telegram] gekennzeichnet.

📨 Telegram-Addon-Anleitung

1. Übersicht

Hauptfunktionen

Funktionsweise

2. Dateistruktur

3. Voraussetzungen

4. Installation & Einrichtung

🤖 Schritt 1: Telegram-Bot erstellen

💬 Schritt 2: Chat-ID ermitteln

⚙️ Schritt 3: In WordPress aktivieren

5. Admin-Panel-Einstellungen

Haupteinstellungsfelder

Aktionsschaltflächen

6. Formularkonfiguration

Konfigurierbare Parameter pro Formular

7. Onboarding-System

Onboarding-Ablauf

Funktionsweise

8. Benachrichtigungssystem

Benachrichtigungsprozess

Nachrichtenformat

9. Hooks & Filter (Für Entwickler)

Action: Telegram-Benachrichtigung senden

Filter: Vollständige Benachrichtigungssteuerung

Filter: Einstellungen ändern

Beispiel: Benutzerdefinierte Nachricht senden

10. Datenbankschema

Tabelle 1: {prefix}_emsfb_telegram_sent_list

Tabelle 2: {prefix}_emsfb_telegram_contact

Zugehörige wp_options

11. AJAX-Aktionen-Referenz

12. Sicherheitshinweise

13. Fehlerbehebung

❌ Problem: Telegram-Menü wird nicht angezeigt

❌ Problem: Verbindungstest-Fehler

❌ Problem: Nachrichten werden nicht gesendet

❌ Problem: 403 Forbidden Fehler

🐛 Debug-Protokollierung aktivieren

WhiteStudio.team

Anleitungen

Links

Team

Soziale Netzwerke

Tabelle 1: `{prefix}_emsfb_telegram_sent_list`

Tabelle 2: `{prefix}_emsfb_telegram_contact`