Ein Widget ist eine interaktive Komponente, die direkt in eine Bot-Nachricht eingebettet ist: ein Promo-Code mit Kopier-Button, ein Countdown-Timer, ein Bestellstatus-Tracker, ein Quiz oder ein Kalender zur Auswahl von Datum und Uhrzeit. Wenn ein Kunde mit einem Widget interagiert, aktualisiert der Bot dieselbe Nachricht an Ort und Stelle – ohne neue Nachrichten zu senden oder ein „Bearbeitet“-Label anzuzeigen.

Es gibt zwei Möglichkeiten, ein Widget zu senden:

• Fertige Vorlage – eine einzelne Zeile im Rechner. Layout und Funktionalität sind bereits implementiert.
• Benutzerdefiniertes Widget – schreiben Sie Ihren eigenen HTML-Code (oder bitten Sie Mavi, ihn zu erstellen) und verarbeiten Sie Interaktionen mit Bot-Flow-Blöcken.

Wo Widgets funktionieren

Messenger	Nur Telegram
Chat-Typ	Nur private Chats zwischen einem Kunden und einem Bot
Nicht unterstützt	Gruppen, Kanäle, Telegram Business
Telegram-App	Erfordert eine aktuelle Version von Telegram. Ältere Versionen zeigen einen Hinweis „Nicht unterstützte Nachricht“ und die Bildunterschrift an
Weiterleiten	Widgets können nicht weitergeleitet oder kopiert werden

Widgets unterstützen keine Texteingabefelder oder Tastaturen. Kunden können nur durch Tippen interagieren. Wenn Sie möchten, dass Kunden Text eingeben, verwenden Sie eine reguläre Bot-Frage oder eine Web-App.

Widgets werden im Bot-Testfenster im Dashboard nicht angezeigt, da es sich nicht um Telegram handelt. Testen Sie Widgets direkt in Telegram, indem Sie Ihrem Bot eine Nachricht senden.

---

Fertige Vorlagen

Alle Vorlagen werden mit einer einzigen Funktion gesendet:

tg_send_widget(platform_id, template, params, caption)

Parameter	Beschreibung
platform_id	Empfänger-ID. Für den aktuellen Kunden verwenden Sie die Variable platform_id
template	Vorlagenname: promo, timer, order_status, faq, quiz, calendar
params	Wörterbuch mit Vorlageneinstellungen
caption	Text, der unter dem Widget angezeigt wird. Kunden sehen ihn auch in ihrer Chat-Liste, in Benachrichtigungen und in älteren Telegram-Versionen, daher sollte er für sich allein verständlich sein

Die Funktion gibt die Antwort der Telegram-API zurück. Die gesendete Nachrichten-ID ist unter response['result']['message_id'] verfügbar. Speichern Sie sie, wenn Sie das Widget später aktualisieren möchten.

Wenn die Funktion Text anstelle einer Telegram-Antwort zurückgibt, ist ein Fehler aufgetreten: eine unbekannte Vorlage, ein ungültiger oder fehlender Parameter oder ein Widget, das die Größenbeschränkung überschreitet. Der Fehlertext erklärt, was schiefgelaufen ist.

So erstellen Sie Parameter

Erstellen Sie ein Wörterbuch und weisen Sie jeden Parameter in einer separaten Zeile zu:

p = {}
p["code"] = "WIDGET10"
p["title"] = "Ihr Promo-Code"
p["note"] = "10% Rabatt auf jede Bestellung"
w = tg_send_widget(platform_id, "promo", p, "Ihr Promo-Code WIDGET10 – 10% Rabatt")

Geben Sie den Code im Feld Rechner des Blocks ein. Der Screenshot zeigt einen Startbedingung-Block, der ein Bestellstatus-Widget sendet, wenn der Kunde den Satz „Bestell-Widget“ sendet.

In dem Block, der das Widget sendet, würden Sie normalerweise das Antwortfeld auf #{none} setzen. Der Block sendet keine separate Textnachricht, da die Widget-Bildunterschrift als Nachrichtentext dient.

Sprache

Vorlagen enthalten integrierten Oberflächentext, wie Schaltflächenbeschriftungen, Monats- und Wochentagsnamen, „Zeit abgelaufen“ und andere Nachrichten.

Die Standardsprache in Mavibot ist Englisch (en).

Um eine andere Sprache zu verwenden, geben Sie den Parameter lang an:

p["lang"] = "de"

Unterstützte Sprachen:

ru, en, de, es, fr, pt, tr, uk, kk, ms, th, ar.

Texte, die Sie selbst angeben – Titel, Fragen, Schritte und Bildunterschriften – werden genau so angezeigt, wie sie eingegeben wurden, und nicht automatisch übersetzt.

---

Promo-Code – promo

Zeigt einen Promo-Code mit einer Schaltfläche an, die ihn mit einem Tippen kopiert.

Parameter	Beschreibung
code	Promo-Code. Erforderlich
title	Text, der über dem Code angezeigt wird
note	Text, der unter dem Code angezeigt wird, z. B. ein Ablaufdatum
button	Schaltflächenbeschriftung. Standard: „Promo-Code kopieren“
used_text	Text, der angezeigt wird, wenn der Code als verwendet markiert ist

p = {}
p["code"] = "WIDGET10"
p["title"] = "Ihr Promo-Code"
p["note"] = "10% Rabatt auf jede Bestellung"
p["button"] = "Code kopieren"
w = tg_send_widget(platform_id, "promo", p, "Ihr Promo-Code WIDGET10 – 10% Rabatt")
client.promo_widget_id = w['result']['message_id']

Um den Code als verwendet zu markieren, was den Code durchstreicht und die Schaltfläche entfernt:

p = {}
p["used"] = 1
t = tg_edit_widget_data(platform_id, client.promo_widget_id, p)

---

Countdown-Timer – timer

Zeigt einen Countdown bis zu einem bestimmten Datum und einer bestimmten Uhrzeit an.

Der Countdown läuft auf dem Gerät des Kunden. Der Bot ist nicht an der Aktualisierung des Timers beteiligt.

Parameter	Beschreibung
until	Zieldatum und -uhrzeit im Format "DD.MM.YYYY HH:MM", unter Verwendung der Zeitzone des Projekts
seconds	Alternativ die Anzahl der Sekunden ab dem Zeitpunkt des Sendens des Widgets
title	Timer-Überschrift. Standard: „Angebot endet in“
done	Text, der angezeigt wird, wenn der Countdown endet
text	Text, der unter dem Countdown angezeigt wird
button, url	Schaltflächenbeschriftung und Ziel-URL (nur https://)
hide_button	Setzen Sie auf 1, um die Schaltfläche zu verbergen, wenn der Countdown endet

Sie müssen entweder until oder seconds angeben.

p = {}
p["seconds"] = 7200
p["title"] = "Angebot endet in"
p["button"] = "Website besuchen"
p["url"] = "https://salebot.pro"
w = tg_send_widget(platform_id, "timer", p, "Das Angebot endet in 2 Stunden")

Wenn der Countdown Null erreicht, wird keine Nachricht oder kein Callback an den Bot gesendet. Wenn der Bot eine Aktion ausführen muss, wenn das Angebot abläuft, verwenden Sie eine reguläre Timer-Verbindung im Bot-Flow.

---

Bestellstatus – order_status

Zeigt eine Liste der Bestellphasen an, wobei die aktuelle Phase hervorgehoben ist.

Der Bot kann die Phase direkt aktualisieren, sodass der Kunde immer dieselbe Nachricht sieht.

Parameter	Beschreibung
title	Widget-Titel
steps	Liste der Phasen, von 1 bis 12. Standard: angenommen, in Vorbereitung, an Kurier übergeben, unterwegs, zugestellt
step	Aktuelle Phasennummer, beginnend bei 1
text	Text, der unter den Phasen angezeigt wird

Senden des Widgets:

p = {}
p["title"] = "Bestellstatus"
p["steps"] = ["Angenommen", "In Vorbereitung", "Zugestellt"]
p["step"] = 1
p["text"] = "Ihre Bestellung wurde angenommen und wird vorbereitet"
w = tg_send_widget(platform_id, "order_status", p, "Ihre Bestellung")
client.order_widget_id = w['result']['message_id']

Wechseln Sie zur nächsten Phase von jedem anderen Block aus, z. B. wenn sich eine Deal-Phase ändert, ein Manager einen Befehl sendet oder ein Timer ausgelöst wird:

p = {}
p["step"] = 2
p["text"] = "Ihre Bestellung wird vorbereitet und bald an den Kurier übergeben"
t = tg_edit_widget_data(platform_id, client.order_widget_id, p)

Die Bildunterschrift unter dem Widget ändert sich nicht, wenn die Phase aktualisiert wird. Verwenden Sie eine neutrale Bildunterschrift wie „Ihre Bestellung“ anstelle von „Status: Angenommen“.

---

Häufig gestellte Fragen – faq

Zeigt eine Liste von Fragen an. Kunden können auf eine Frage tippen, um die Antwort zu erweitern.

Parameter	Beschreibung
title	Widget-Titel
items	Liste von Frage-Antwort-Paaren. Erforderlich

p = {}
p["title"] = "Häufig gestellte Fragen"
p["items"] = [["Wie kann ich bezahlen?", "Sie können mit Karte bezahlen. Ein Zahlungslink wird an diesen Chat gesendet."], ["Wie lange dauert die Lieferung?", "Die Lieferung dauert normalerweise 1–2 Tage lokal und 3–7 Tage landesweit."], ["Kann ich einen Artikel zurückgeben?", "Ja, innerhalb von 14 Tagen."]]
w = tg_send_widget(platform_id, "faq", p, "Antworten auf häufig gestellte Fragen")

Text wird als Klartext angezeigt. HTML-Tags und andere Auszeichnungen werden nicht verarbeitet.

---

Quiz und Umfrage – quiz

Zeigt Fragen mit Multiple-Choice-Antworten an, eine Frage nach der anderen.

Wenn richtige Antworten angegeben sind, fungiert das Widget als Quiz und berechnet eine Punktzahl. Ohne richtige Antworten funktioniert es als Umfrage.

Parameter	Beschreibung
title	Überschrift, die über den Fragen angezeigt wird
questions	Liste der Fragen. Erforderlich
retry	Setzen Sie auf 1, um am Ende eine Schaltfläche „Erneut versuchen“ anzuzeigen
callback	Benutzerdefinierter Callback-Text anstelle von widget_quiz_finished

Jede Frage ist ein Wörterbuch, das Folgendes enthält:

• q – Fragetext
• options – Antwortoptionen
• correct – richtige Antwort, angegeben durch ihren 1-basierten Index oder exakten Text

p = {}
p["title"] = "Quiz: Testen Sie Ihr Wissen"
p["retry"] = 1
p["questions"] = [{"q": "Was ist 2 + 2?", "options": ["3", "4", "5"], "correct": 2}, {"q": "Was ist die Hauptstadt von Frankreich?", "options": ["London", "Paris", "Berlin"], "correct": "Paris"}]
w = tg_send_widget(platform_id, "quiz", p, "Machen Sie dieses Quiz mit zwei Fragen!")

Um eine Umfrage ohne Bewertung zu erstellen, lassen Sie correct bei jeder Frage weg.

Richtige Antworten werden von der Plattform überprüft und nicht an das Gerät des Kunden gesendet.

Was der Bot-Flow empfängt

Einzelne Antworten auf Fragen werden nicht an die Konversation gesendet.

Wenn der Kunde die letzte Frage beantwortet, empfängt der Bot den Callback widget_quiz_finished und die folgenden Variablen werden gefüllt:

Variable	Wert
widget_quiz_score	Anzahl der richtigen Antworten; leer bei Umfragen
widget_quiz_total	Gesamtzahl der Fragen
widget_quiz_answers	Indizes der ausgewählten Optionen, z. B. [2,2]

Um das Ergebnis zu verarbeiten, erstellen Sie eine Verbindung von dem Block, der das Quiz gesendet hat, oder verwenden Sie einen Startbedingung-Block mit der Bedingung widget_quiz_finished.

Beispielantwort:

Ihr Ergebnis: #{widget_quiz_score} von #{widget_quiz_total} richtigen Antworten

---

Kalender – calendar

Zeigt einen Monatskalender an, in dem Kunden ein Datum und dann einen Zeitraum auswählen können.

Er ersetzt mehrere Seiten mit Datums- und Uhrzeitschaltflächen, einschließlich „Zurück“- und „Weiter“-Navigation.

Der Kalender unterstützt drei Modi.

Benutzerdefinierte Daten und Uhrzeiten

Verfügbare Uhrzeiten werden immer über den Parameter slots übergeben.

Gleiche Zeitfenster jeden Tag – geben Sie eine Liste von Uhrzeiten und einen Datumsbereich an:

p = {}
p["title"] = "Datum und Uhrzeit auswählen"
p["name"] = "Beratung"
p["days"] = 10
p["slots"] = ["10:00", "12:00", "15:00"]
w = tg_send_widget(platform_id, "calendar", p, "Datum und Uhrzeit wählen")

Verschiedene Zeitfenster für bestimmte Daten – geben Sie ein Wörterbuch an, das Daten Zeitlisten zuordnet. Verfügbare Daten werden aus den Wörterbuchschlüsseln übernommen:

p = {}
p["slots"] = {"20.11.2026": ["10:00", "12:00"], "21.11.2026": ["15:00"]}
w = tg_send_widget(platform_id, "calendar", p, "Datum und Uhrzeit wählen")

Parameter	Beschreibung
slots	Verfügbare Uhrzeiten, als Liste oder als nach Datum gruppiertes Wörterbuch
days	Anzahl der verfügbaren Tage ab heute
date_from, date_to	Alternativ die Grenzen des Datumsbereichs im Format "DD.MM.YYYY"
dates	Alternativ eine Liste bestimmter Daten
weekdays_off	Nicht verfügbare Wochentage: 1 = Montag bis 7 = Sonntag
title	Hinweis, der unter dem Kalenderraster angezeigt wird
name	Name des gebuchten Artikels oder Dienstes; wird nach der Auswahl angezeigt
change	Setzen Sie auf 1, um nach der Auswahl eine Schaltfläche „Andere Uhrzeit wählen“ anzuzeigen
callback	Benutzerdefinierter Callback-Text anstelle von widget_calendar_selected

Nur Datum

Übergeben Sie slots nicht, wenn der Kunde nur ein Datum auswählen muss.

p = {}
p["days"] = 45
p["weekdays_off"] = [7]
w = tg_send_widget(platform_id, "calendar", p, "Choose a date")

Online-Buchung

Geben Sie eine Filiale und eine Dienstleistung an, und der Kalender ruft automatisch verfügbare Termine und Zeitfenster aus dem Modul Services ab.

cal = {}
cal["company_id"] = comp_id
cal["service_ids"] = serv_id
cal["days_limit"] = 30
cal["name"] = serv_title
w = tg_send_widget(platform_id, "calendar", cal, serv_title)

Parameter	Beschreibung
company_id	Filialkennung
service_ids	Dienstleistung oder Liste von Dienstleistungen
employee_id	Mitarbeiterkennung; wenn nicht angegeben, wird ein beliebiger verfügbarer Mitarbeiter verwendet
days_limit	Anzahl der Tage im Voraus, nach denen Verfügbarkeit gesucht wird. Standard: 14
people_count	Anzahl der benötigten Plätze für eine Gruppendienstleistung
auto_booking	Setzen Sie auf 1, damit die Plattform die Buchung automatisch erstellt

Diese Parameter sind dieselben wie die von get_dates_for_booking und get_slots_for_booking verwendeten.

Was der Bot-Flow empfängt

Einzelne Datumsauswahlen werden nicht an die Konversation gesendet.

Wenn der Kunde ein Zeitfenster auswählt oder ein Datum, falls der Kalender keine Zeitfenster hat, empfängt der Bot den Callback widget_calendar_selected und die folgenden Variablen werden befüllt:

Variable	Wert
widget_date	Ausgewähltes Datum im Format DD.MM.YYYY
widget_time	Ausgewählte Uhrzeit im Format HH:MM; leer bei Kalendern nur mit Datum
widget_message_id	ID der Nachricht, die das Widget enthält

Die Datums- und Zeitformate sind dieselben wie die von create_booking und modify_booking_time akzeptierten.

---

Online-Buchung mit Kalender: Vollständiges Beispiel

Das Widget übernimmt Datumsauswahl, Zeitfenster und Navigation und reduziert so die Anzahl der benötigten Bot-Blöcke.

Block 1. Dienstleistungsauswahl

Verwenden Sie einen Startbedingung-Block mit der Bedingung "Termin buchen".

Antwort: "Wählen Sie eine Dienstleistung:"

Setzen Sie das Feld Schaltflächen auf #{srv_buttons}.

comp_id = 8
srv_data = get_services_for_booking(comp_id)
srv_kb = tools_make_button_str_checker(srv_data, 'title', 1)
srv_buttons = srv_kb['buttons']
srv_checker = srv_kb['checker']

Block 2. Kalender

Antwort: #{none}.

Verbinden Sie Block 1 mit Block 2 unter Verwendung der Bedingung #{srv_checker}.

serv_id = tools_check_user_input(srv_data, question, 'title', 'id')
serv_title = tools_check_user_input(srv_data, question, 'title', 'title')
cal = {}
cal["company_id"] = comp_id
cal["service_ids"] = serv_id
cal["days_limit"] = 30
cal["name"] = serv_title
cal_sent = tg_send_widget(platform_id, "calendar", cal, serv_title)

Block 3. Buchung erstellen

Antwort: #{none}.

Verbinden Sie Block 2 mit Block 3 unter Verwendung der Bedingung widget_calendar_selected mit Exakter Übereinstimmung.

booking_date = widget_date
booking_time = widget_time
booking_result = create_booking(comp_id, serv_id, booking_date, booking_time, '')
booking_ok = booking_result['status']

Block 4. Buchung bestätigt

Verbinden Sie Block 3 mit Block 4 unter Verwendung der Variablenbedingung booking_ok == True mit einer Verzögerung von einer Sekunde.

Antwort:

Ihr Termin ist bestätigt: #{serv_title}, #{booking_date} um #{booking_time}. Wir freuen uns auf Sie!

Block 5. Zeitfenster nicht mehr verfügbar

Antwort: #{none}.

Verbinden Sie Block 3 mit Block 5 unter Verwendung der Variablenbedingung booking_ok != True mit einer Verzögerung von einer Sekunde.

Dieser Block setzt den vorhandenen Kalender zurück, sodass der Kunde eine andere Zeit auswählen kann, und zeigt eine Fehlermeldung an.

fix = {}
fix["reset"] = 1
fix["error"] = "Dieses Zeitfenster wurde gerade gebucht. Bitte wählen Sie ein anderes."
t = tg_edit_widget_data(platform_id, widget_message_id, fix)

Fügen Sie eine weitere Verbindung von Block 5 zu Block 3 mit der Bedingung widget_calendar_selected hinzu.

Der Kunde kann nun im selben Kalender eine andere Zeit auswählen.

Einfachere Option: Automatische Buchung

Fügen Sie den folgenden Parameter zu den Kalendereinstellungen hinzu:

cal["auto_booking"] = 1

Die Plattform erstellt die Buchung sofort, wenn der Kunde eine Zeit auswählt.

Wenn das ausgewählte Zeitfenster nicht mehr verfügbar ist, zeigt das Widget direkt einen Fehler an.

Der Callback widget_calendar_selected wird nur nach einer erfolgreichen Buchung gesendet, zusammen mit der Variablen widget_booking_id.

Bei diesem Ansatz sind die Blöcke 3 und 5 nicht erforderlich.

Verwenden Sie die Buchung über den Bot-Flow (der erste Ansatz), wenn Sie Vorauszahlung oder benutzerdefinierte Prüfungen vor der Bestätigung eines Termins benötigen.

---

Aktualisieren eines gesendeten Widgets

Verwenden Sie die folgende Funktion, um Widget-Daten zu aktualisieren:

tg_edit_widget_data(platform_id, message_id, data)

Parameter	Beschreibung
message_id	ID der Widget-Nachricht, gespeichert beim Senden oder erhalten von widget_message_id nach einer Interaktion
data	Wörterbuch mit den neuen Werten

Nur Widget-Daten können aktualisiert werden. Sie können das Layout eines bereits gesendeten Widgets nicht ändern. Um ein anderes Layout zu verwenden, senden Sie ein neues Widget.

So werden Aktualisierungen angewendet:

• Promo-Code, Timer, Bestellstatus, FAQ: Die neuen Daten ersetzen die vorherige Aktualisierung vollständig. Fehlende Felder fallen auf die ursprünglichen Werte zurück, die beim Senden des Widgets angegeben wurden. Geben Sie daher jedes Feld an, das sich von den ursprünglichen Daten unterscheiden soll, z. B. sowohl step als auch text.
• Quiz und Kalender: Neue Daten werden auf den aktuellen Widget-Zustand angewendet.

Spezielle Aktualisierungsparameter:

Vorlage	Daten	Ergebnis
promo	{"used": 1}	Markiert den Promo-Code als verwendet
timer	{"seconds": 600} oder {"until": "…"}	Startet den Countdown neu
calendar	{"reset": 1, "error": "message"}	Löscht die Auswahl, öffnet den Kalender erneut und zeigt eine Meldung an

---

Benutzerdefinierte Widgets

Wenn vorgefertigte Vorlagen nicht ausreichen – zum Beispiel, wenn Sie einen Produktkatalog mit Warenkorb, eine Sternebewertung oder einen Preisrechner benötigen – können Sie ein benutzerdefiniertes HTML-Widget erstellen.

So funktioniert es

1. Erstellen Sie ein Widget als einzelne HTML-Datei, die ihre Stile und JavaScript enthält.
2. Speichern Sie den Code als .txt-Datei im Bereich Dateien des Projekts und kopieren Sie die Datei-URL. Das Speichersystem akzeptiert keine .html-Dateien.
3. Ein Bot-Block sendet das Widget mithilfe der URL und übergibt seine Anfangsdaten.
4. Wenn ein Kunde mit dem Widget interagiert, empfängt der Bot einen Callback mit dem im Widget-Code definierten Text.
5. Ein Handler-Block berechnet die neuen Daten und sendet sie zurück an das Widget, das seine eigene Oberfläche aktualisiert.

Senden eines benutzerdefinierten Widgets

tg_send_widget_file(platform_id, url, data, caption)

Beispiel:

st = {}
st["rating"] = 0
w = tg_send_widget_file(platform_id, "https://files.mavibot.ai/…/rating.txt", st, "Bewerten Sie Ihre Bestellung – tippen Sie auf einen Stern")

Der Parameter data ist ein Wörterbuch, das den Anfangszustand enthält, der zum Rendern des Widgets verwendet wird.

Verarbeiten von Interaktionen

Wenn ein Kunde mit einem benutzerdefinierten Widget interagiert, empfängt der Bot einen Callback.

Die folgenden Variablen werden ebenfalls befüllt:

Variable	Wert
widget_data	Anforderungstext, der vom Widget gesendet wird, z. B. rate:4
widget_message_id	ID der Nachricht, in der die Interaktion stattfand
widget_query_id	Anforderungskennung

Erstellen Sie den Handler mit einem Trigger-Block und aktivieren Sie die Einstellung Trigger nur bei Callback.

Die Bedingung sollte mit dem Anforderungstext des Widgets übereinstimmen.

Dieser Blocktyp funktioniert unabhängig von der aktuellen Position des Kunden im Bot-Flow und entfernt ihn nicht von seinem aktuellen Schritt.

Wichtig: Verwenden Sie keinen Startbedingung-Block, um Interaktionen mit benutzerdefinierten Widgets zu verarbeiten. Ein Widget bleibt im Chat, und der Kunde kann jederzeit damit interagieren – sogar während er einen Fragebogen ausfüllt, einen Termin bucht oder eine Zahlung vornimmt. Ein Startbedingung-Block würde den Kunden zum Handler umleiten und seinen aktuellen Schritt unterbrechen.

Beispiel für einen Bewertungs-Handler:

Bedingung (regulärer Ausdruck):

^rate:[1-5]$

Rechner:

local a = splitter(widget_data, ":")
client.widget_rating = a[1]
st = {}
st["rating"] = client.widget_rating
t = tg_edit_widget_data(platform_id, widget_message_id, st)

Benutzerdefinierte Widget-Daten werden bei Aktualisierungen vollständig ersetzt. Senden Sie immer den vollständigen Zustand und nicht nur das geänderte Feld.

Das Datenlimit beträgt 1024 Bytes.

Halten Sie große, statische Datensätze (wie Produktkataloge) im Widget-Code und senden Sie nur die Werte, die sich ändern, über die Widget-Daten.

Antworten auf eine Widget-Anfrage

Standardmäßig empfängt das Widget sofort eine leere Antwort, und aktualisierte Daten kommen über eine separate Widget-Aktualisierung.

Wenn das Widget Daten direkt als Antwort auf seine Anfrage empfangen muss, muss der Anforderungstext mit ? beginnen, zum Beispiel:

?price

In diesem Fall muss der Handler-Block die folgende Funktion innerhalb von 15 Sekunden aufrufen:

tg_answer_widget_query(data)

Andernfalls zeigt das Widget einen Timeout-Fehler an.

Das Antwortlimit beträgt 1024 Bytes.

Code-Anforderungen

• Einzelne Datei: Fügen Sie Stile innerhalb von <style> und JavaScript innerhalb von <script> ein. Externe Skripte, Stylesheets, Schriftarten und Bilder können nicht geladen werden. Bilder müssen mit data:-URLs oder SVG eingebettet werden.
• Größenlimits: maximal 32 KB vor der Komprimierung und 4 KB nach der Komprimierung.
• Keine Eingabefelder: input, select, textarea und form-Elemente werden entfernt. Nur <button>-Elemente werden als interaktive Steuerelemente unterstützt.
• Keine Netzwerkanfragen: fetch und ähnliche APIs funktionieren nicht. Die einzige Möglichkeit, mit dem Bot zu kommunizieren, ist TelegramWidget.request("text"), mit einer Anforderungsgröße von 1–64 Bytes.
• Kein internes Scrollen: Die maximale Widget-Höhe beträgt 600 Pixel. Alles darüber wird abgeschnitten. Um ein Karussell zu erstellen, bewegen Sie eine Reihe von Karten, anstatt zu scrollen.
• Elementzugriff: Verwenden Sie document.getElementById. Der Zugriff auf Elemente als globale Variablen basierend auf ihren IDs funktioniert nicht.
• Telegram-Design: Verwenden Sie Telegram-Designvariablen wie var(--tg-theme-text-color), damit das Widget sowohl in hellen als auch in dunklen Designs korrekt aussieht.
• Widget-Daten: Lesen Sie Daten aus TelegramWidget.chatData und zeichnen Sie das Widget neu, wenn das Ereignis chatDataChanged auftritt.
• Anfragen: Rufen Sie request direkt innerhalb eines Benutzerinteraktions-Handlers auf. Pro Interaktion ist nur eine Anfrage zulässig.

Das Widget zeigt keine Codierungsfehler an. Nicht unterstützte Elemente werden stillschweigend entfernt, und ein JavaScript-Fehler kann zu einem leeren Widget führen. Testen Sie das Widget nach Änderungen immer in Telegram.

Minimales Beispiel für ein benutzerdefiniertes Widget

Das folgende Beispiel zeigt ein Produkt, eine Schaltfläche, die eine Anfrage an den Bot sendet, und einen Warenkorbzähler basierend auf Widget-Daten.

<style>
body{margin:0;padding:14px}
.h{color:var(--tg-theme-hint-color);font-size:.85em}
button{width:100%;margin-top:8px}
</style>

<b>Margherita · $10</b>
<div class="h" id="c"></div>
<button id="add">In den Warenkorb</button>
<div class="h" id="e"></div>

<script>
var W=window.TelegramWidget,$=function(i){return document.getElementById(i)},busy=0;

function draw(){
  var s={};
  try{s=JSON.parse(W.chatData)||{}}catch(e){}
  $('c').textContent='Im Warenkorb: '+(s.count||0)
}

$('add').onclick=function(){
  if(busy)return;
  busy=1;
  $('e').textContent='';
  W.request('cart_add').then(
    function(){busy=0},
    function(x){
      busy=0;
      $('e').textContent='Fehler: '+x.code
    }
  )
};

W.onEvent('chatDataChanged',draw);
draw();
</script>

---

Mavi und Widgets

Mavi kann mit Widgets automatisch vollständige Bot-Abläufe erstellen.

Beschreiben Sie einfach in einfacher Sprache, was Sie benötigen.

Zum Beispiel:

• „Wenn der Kunde ‚order‘ sendet, zeige ein Bestellstatus-Widget mit drei Stufen an. Wenn er ‚ready‘ sendet, verschiebe die Bestellung auf die zweite Stufe.“
• „Erstellen Sie einen Service-Buchungsablauf: Kunden wählen einen Service über Schaltflächen aus und wählen dann Datum und Uhrzeit über ein Kalender-Widget.“
• „Erstellen Sie ein Sternebewertungs-Widget für Bestellungen und speichern Sie die ausgewählte Bewertung in einer Kunden-Variable.“

Mavi konfiguriert automatisch vorgefertigte Vorlagen.

Für benutzerdefinierte Widgets schreibt und prüft Mavi den Code, speichert die Widget-Datei im Projekt und erstellt die Blöcke, die zum Senden des Widgets und zur Verarbeitung von Kundeninteraktionen erforderlich sind.

---

Referenz

Funktionen

Funktion	Beschreibung
tg_send_widget(platform_id, template, params, caption)	Sendet eine vorgefertigte Widget-Vorlage
tg_send_widget_file(platform_id, url, data, caption)	Sendet ein benutzerdefiniertes Widget aus einer Datei
tg_edit_widget_data(platform_id, message_id, data)	Aktualisiert Daten in einem vorhandenen Widget
tg_answer_widget_query(data)	Antwortet auf eine benutzerdefinierte Widget-Anfrage, die mit ? beginnt

Callbacks und Variablen

Ereignis	Callback	Variablen
Quiz abgeschlossen	widget_quiz_finished	widget_quiz_score, widget_quiz_total, widget_quiz_answers
Datum und Uhrzeit im Kalender ausgewählt	widget_calendar_selected	widget_date, widget_time; auch widget_booking_id, wenn auto_booking aktiviert ist
Benutzerdefinierte Widget-Interaktion	Anfragetext, der im Widget-Code definiert ist	widget_data, widget_message_id, widget_query_id

Wenn Ihr Bot mehrere Quizze oder Kalender enthält, weisen Sie jedem Widget über den Parameter callback einen eindeutigen Callback zu, damit Sie sie in Ihren Bot-Ablaufbedingungen unterscheiden können.

Einschränkungen

• Widgets funktionieren nur in privaten Telegram-Chats zwischen einem Kunden und einem Bot.
• Für jeden Kunden werden nur die fünf neuesten Quizze und Kalender aufbewahrt. Ältere reagieren nicht mehr auf Interaktionen.
• Das Löschen aller Kunden-Variablen in einem Bot-Ablauf deaktiviert zuvor gesendete Quizze und Kalender.
• Widget-Daten sind auf 1024 Bytes begrenzt.
• Anfragen von benutzerdefinierten Widgets sind auf 64 Bytes begrenzt.
• Benutzerdefinierte Widget-Anfragen, die tg_answer_widget_query erfordern, müssen innerhalb von 15 Sekunden beantwortet werden.

Fehlerbehebung

Problem	Ursache / Lösung
Widget wird nicht gesendet und die Variable enthält Unknown parameter…	Die Vorlage hat einen nicht unterstützten Parameter erhalten. Die Fehlermeldung listet die zulässigen Parameter auf
Kalender stoppt nach der Datumsauswahl, ohne Zeitfenster anzuzeigen	Der Parameter slots wurde nicht angegeben
Nach der Interaktion mit einem Widget reagiert der Bot nicht mehr auf Schaltflächen im aktuellen Schritt	Der Interaktions-Handler verwendet einen Startbedingungs-Block. Ersetzen Sie ihn durch einen Nicht-Zustands-Block mit Bedingung
Benutzerdefiniertes Widget erscheint leer	Es gibt einen Fehler im Widget-Code. Eine häufige Ursache ist der Zugriff auf ein Element über seine ID ohne Verwendung von document.getElementById
Telegram zeigt „Unsupported message“ an	Der Kunde verwendet eine veraltete Version von Telegram
Bad Request: chat not found	Das Widget wurde außerhalb von Telegram gesendet, z. B. aus dem Bot-Testfenster