Widget, doğrudan bir bot mesajına gömülü etkileşimli bir bileşendir: kopyalama butonlu bir promosyon kodu, geri sayım sayacı, sipariş durumu takipçisi, bir test veya tarih ve saat seçmek için bir takvim. Bir müşteri widget ile etkileşime girdiğinde, bot aynı mesajı yerinde günceller — yeni mesajlar göndermeden veya "düzenlendi" etiketi göstermeden.

Widget göndermenin iki yolu vardır:

• Hazır şablon — Hesaplayıcı'da tek bir satır. Düzen ve işlevsellik zaten uygulanmıştır.
• Özel widget — Kendi HTML kodunuzu yazın (veya Mavi'den oluşturmasını isteyin) ve etkileşimleri bot akış bloklarını kullanarak işleyin.

Widget'lar Nerede Çalışır

Mesajlaşma uygulaması	Yalnızca Telegram
Sohbet türü	Yalnızca müşteri ile bot arasındaki özel sohbetler
Desteklenmez	Gruplar, kanallar, Telegram Business
Telegram uygulaması	Güncel bir Telegram sürümü gerektirir. Eski sürümler "Desteklenmeyen mesaj" bildirimi ve başlığı görüntüler
İletme	Widget'lar iletilemez veya kopyalanamaz

Widget'lar metin giriş alanlarını veya klavyeleri desteklemez. Müşteriler yalnızca dokunarak etkileşim kurabilir. Müşterilerin metin girmesine ihtiyacınız varsa, normal bir bot sorusu veya Web App kullanın.

Widget'lar, Telegram olmadığı için kontrol panelindeki bot test penceresinde görüntülenmez. Widget'ları doğrudan Telegram'da botunuza mesaj göndererek test edin.

---

Hazır Şablonlar

Tüm şablonlar tek bir işlev kullanılarak gönderilir:

tg_send_widget(platform_id, template, params, caption)

Parametre	Açıklama
platform_id	Alıcı kimliği. Geçerli müşteri için platform_id değişkenini kullanın
template	Şablon adı: promo, timer, order_status, faq, quiz, calendar
params	Şablon ayarlarını içeren sözlük
caption	Widget'ın altında görüntülenen metin. Müşteriler bunu sohbet listesinde, bildirimlerde ve eski Telegram sürümlerinde de görür, bu nedenle kendi başına anlamlı olmalıdır

İşlev, Telegram API yanıtını döndürür. Gönderilen mesaj kimliği response['result']['message_id'] adresinde mevcuttur. Widget'ı daha sonra güncellemeyi planlıyorsanız kaydedin.

İşlev bir Telegram yanıtı yerine metin döndürürse, bir hata oluşmuştur: bilinmeyen bir şablon, geçersiz veya eksik bir parametre veya boyut sınırını aşan bir widget. Hata metni neyin yanlış gittiğini açıklar.

Parametreler Nasıl Oluşturulur

Bir sözlük oluşturun ve her parametreyi ayrı bir satıra atayın:

p = {}
p["code"] = "WIDGET10"
p["title"] = "Promosyon kodunuz"
p["note"] = "Tüm siparişlerde %10 indirim"
w = tg_send_widget(platform_id, "promo", p, "Promosyon kodunuz WIDGET10 — %10 indirim")

Kodu bloğun Hesaplayıcı alanına girin. Ekran görüntüsü, müşteri "sipariş widget" ifadesini gönderdiğinde bir sipariş durumu widget'ı gönderen bir Başlangıç Koşulu bloğunu gösterir.

Widget'ı gönderen blokta, yanıt alanını genellikle #{none} olarak ayarlarsınız. Blok ayrı bir metin mesajı göndermez çünkü widget başlığı mesaj metni olarak hizmet eder.

Dil

Şablonlar, düğme etiketleri, ay ve hafta günü adları, "Süre doldu" ve diğer mesajlar gibi yerleşik arayüz metinleri içerir.

Mavibot'ta varsayılan dil İngilizcedir (en).

Başka bir dil kullanmak için lang parametresini belirtin:

p["lang"] = "de"

Desteklenen diller:

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

Kendinizin sağladığı metinler — başlıklar, sorular, adımlar ve başlıklar — tam olarak girildiği gibi görüntülenir ve otomatik olarak çevrilmez.

---

Promosyon Kodu — promo

Tek dokunuşla kopyalayan bir düğmeyle bir promosyon kodu görüntüler.

Parametre	Açıklama
code	Promosyon kodu. Zorunlu
title	Kodun üzerinde görüntülenen metin
note	Kodun altında görüntülenen metin, örneğin son kullanma tarihi
button	Düğme etiketi. Varsayılan: "Promosyon kodunu kopyala"
used_text	Kod kullanılmış olarak işaretlendiğinde görüntülenen metin

p = {}
p["code"] = "WIDGET10"
p["title"] = "Promosyon kodunuz"
p["note"] = "Tüm siparişlerde %10 indirim"
p["button"] = "Kodu kopyala"
w = tg_send_widget(platform_id, "promo", p, "Promosyon kodunuz WIDGET10 — %10 indirim")
client.promo_widget_id = w['result']['message_id']

Kodu kullanılmış olarak işaretlemek için, kodu üzerini çizer ve düğmeyi kaldırır:

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

---

Geri Sayım Sayacı — timer

Belirtilen bir tarihe ve saate kadar geri sayımı görüntüler.

Geri sayım müşterinin cihazında çalışır. Bot, sayacın güncellenmesine dahil değildir.

Parametre	Açıklama
until	Projenin saat diliminde "GG.AA.YYYY SS:DD" biçiminde hedef tarih ve saat
seconds	Alternatif olarak, widget'ın gönderildiği andan itibaren saniye sayısı
title	Sayaç başlığı. Varsayılan: "Teklif bitiyor"
done	Geri sayım bittiğinde görüntülenen metin
text	Geri sayımın altında görüntülenen metin
button, url	Düğme etiketi ve hedef URL (yalnızca https://)
hide_button	Geri sayım bittiğinde düğmeyi gizlemek için 1 olarak ayarlayın

until veya seconds değerlerinden birini sağlamalısınız.

p = {}
p["seconds"] = 7200
p["title"] = "Teklif bitiyor"
p["button"] = "Web sitesini ziyaret et"
p["url"] = "https://salebot.pro"
w = tg_send_widget(platform_id, "timer", p, "Teklif 2 saat içinde bitiyor")

Geri sayım sıfıra ulaştığında, bot'a hiçbir mesaj veya geri arama gönderilmez. Botun teklif sona erdiğinde bir eylem gerçekleştirmesi gerekiyorsa, bot akışında normal bir zamanlayıcı bağlantısı kullanın.

---

Sipariş Durumu — order_status

Geçerli aşamanın vurgulandığı bir sipariş aşamaları listesi görüntüler.

Bot aşamayı yerinde güncelleyebilir, böylece müşteri her zaman aynı mesajı görür.

Parametre	Açıklama
title	Widget başlığı
steps	1'den 12'ye kadar aşama listesi. Varsayılan: kabul edildi, hazırlanıyor, kuryeye teslim edildi, yolda, teslim edildi
step	1'den başlayarak geçerli aşama numarası
text	Aşamaların altında görüntülenen metin

Widget'ı gönderme:

p = {}
p["title"] = "Sipariş durumu"
p["steps"] = ["Kabul edildi", "Hazırlanıyor", "Teslim edildi"]
p["step"] = 1
p["text"] = "Siparişiniz kabul edildi ve hazırlanıyor"
w = tg_send_widget(platform_id, "order_status", p, "Siparişiniz")
client.order_widget_id = w['result']['message_id']

Başka herhangi bir bloktan bir sonraki aşamaya geçin, örneğin bir anlaşma aşaması değiştiğinde, bir yönetici komut gönderdiğinde veya bir zamanlayıcı tetiklendiğinde:

p = {}
p["step"] = 2
p["text"] = "Siparişiniz hazırlanıyor ve yakında kuryeye teslim edilecek"
t = tg_edit_widget_data(platform_id, client.order_widget_id, p)

Widget'ın altındaki başlık, aşama güncellendiğinde değişmez. "Durum: Kabul edildi" yerine "Siparişiniz" gibi nötr bir başlık kullanın.

---

Sıkça Sorulan Sorular — faq

Bir soru listesi görüntüler. Müşteriler bir soruya dokunarak yanıtını genişletebilir.

Parametre	Açıklama
title	Widget başlığı
items	Soru-cevap çiftleri listesi. Zorunlu

p = {}
p["title"] = "Sıkça Sorulan Sorular"
p["items"] = [["Nasıl ödeyebilirim?", "Kartla ödeyebilirsiniz. Ödeme bağlantısı bu sohbete gönderilecek."], ["Teslimat ne kadar sürer?", "Teslimat genellikle yerel olarak 1-2 gün ve ülke genelinde 3-7 gün sürer."], ["Bir ürünü iade edebilir miyim?", "Evet, 14 gün içinde."]]
w = tg_send_widget(platform_id, "faq", p, "Sıkça sorulan soruların yanıtları")

Metin düz metin olarak görüntülenir. HTML etiketleri ve diğer biçimlendirmeler işlenmez.

---

Test ve Anket — quiz

Her seferinde bir soru olacak şekilde çoktan seçmeli yanıtlı sorular görüntüler.

Doğru yanıtlar belirtilirse, widget bir test görevi görür ve bir puan hesaplar. Doğru yanıtlar olmadan, bir anket olarak çalışır.

Parametre	Açıklama
title	Soruların üzerinde görüntülenen başlık
questions	Soru listesi. Zorunlu
retry	Sonda bir "Tekrar dene" düğmesi görüntülemek için 1 olarak ayarlayın
callback	widget_quiz_finished yerine özel geri arama metni

Her soru aşağıdakileri içeren bir sözlüktür:

• q — soru metni
• options — yanıt seçenekleri
• correct — 1 tabanlı dizini veya tam metniyle belirtilen doğru yanıt

p = {}
p["title"] = "Test: Bilginizi Sınayın"
p["retry"] = 1
p["questions"] = [{"q": "2 + 2 kaçtır?", "options": ["3", "4", "5"], "correct": 2}, {"q": "Fransa'nın başkenti neresidir?", "options": ["Londra", "Paris", "Berlin"], "correct": "Paris"}]
w = tg_send_widget(platform_id, "quiz", p, "Bu iki soruluk teste katılın!")

Puanlama olmadan bir anket oluşturmak için her sorudan correct değerini çıkarın.

Doğru yanıtlar platform tarafından kontrol edilir ve müşterinin cihazına gönderilmez.

Bot Akışı Ne Alır

Bireysel soru yanıtları sohbete gönderilmez.

Müşteri son soruyu yanıtladığında, bot widget_quiz_finished geri aramasını alır ve aşağıdaki değişkenler doldurulur:

Değişken	Değer
widget_quiz_score	Doğru yanıt sayısı; anketler için boş
widget_quiz_total	Toplam soru sayısı
widget_quiz_answers	Seçilen seçeneklerin dizinleri, örneğin [2,2]

Sonucu işlemek için, testi gönderen bloktan bir bağlantı oluşturun veya widget_quiz_finished koşuluyla bir Başlangıç Koşulu bloğu kullanın.

Örnek yanıt:

Sonucunuz: #{widget_quiz_score} / #{widget_quiz_total} doğru yanıt

---

Takvim — calendar

Müşterilerin bir tarih ve ardından bir saat aralığı seçebileceği aylık bir takvim görüntüler.

"Geri" ve "İleri" gezinme dahil olmak üzere birden çok tarih ve saat düğmesi sayfasının yerini alır.

Takvim üç modu destekler.

Özel Tarihler ve Saatler

Uygun saatler her zaman slots parametresi aracılığıyla iletilir.

Her gün aynı saat aralıkları — bir saat listesi ve bir tarih aralığı sağlayın:

p = {}
p["title"] = "Bir tarih ve saat seçin"
p["name"] = "Danışmanlık"
p["days"] = 10
p["slots"] = ["10:00", "12:00", "15:00"]
w = tg_send_widget(platform_id, "calendar", p, "Bir tarih ve saat seçin")

Belirli tarihler için farklı saat aralıkları — tarihleri saat listelerine eşleyen bir sözlük sağlayın. Uygun tarihler sözlük anahtarlarından alınır:

p = {}
p["slots"] = {"20.11.2026": ["10:00", "12:00"], "21.11.2026": ["15:00"]}
w = tg_send_widget(platform_id, "calendar", p, "Bir tarih ve saat seçin")

Parametre	Açıklama
slots	Uygun saatler, bir liste veya tarihe göre gruplandırılmış bir sözlük
days	Bugünden itibaren uygun gün sayısı
date_from, date_to	Alternatif olarak, "GG.AA.YYYY" biçiminde tarih aralığı sınırları
dates	Alternatif olarak, belirli tarihlerin listesi
weekdays_off	Uygun olmayan hafta günleri: 1 = Pazartesi ile 7 = Pazar
title	Takvim ızgarasının altında görüntülenen ipucu
name	Rezerve edilen öğenin veya hizmetin adı; seçimden sonra görüntülenir
change	Seçimden sonra bir "Başka bir saat seç" düğmesi görüntülemek için 1 olarak ayarlayın
callback	widget_calendar_selected yerine özel geri arama metni

Yalnızca Tarih

Müşterinin yalnızca bir tarih seçmesi gerekiyorsa slots parametresini geçmeyin.

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

Çevrimiçi Rezervasyon

Bir şube ve hizmet belirtin; takvim, Hizmetler modülünden uygun tarihleri ve saat aralıklarını otomatik olarak alacaktır.

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)

Parametre	Açıklama
company_id	Şube kimliği
service_ids	Hizmet veya hizmet listesi
employee_id	Çalışan kimliği; atlanırsa uygun herhangi bir çalışan kullanılır
days_limit	Uygunluk aranacak ileri gün sayısı. Varsayılan: 14
people_count	Grup hizmeti için gereken kişi sayısı
auto_booking	Platformun rezervasyonu otomatik oluşturması için 1 olarak ayarlayın

Bu parametreler, get_dates_for_booking ve get_slots_for_booking tarafından kullanılanlarla aynıdır.

Bot Akışının Aldıkları

Bireysel tarih seçimleri konuşmaya gönderilmez.

Müşteri bir saat aralığı seçtiğinde veya takvimde saat aralığı yoksa bir tarih seçtiğinde, bot widget_calendar_selected geri çağrısını alır ve aşağıdaki değişkenler doldurulur:

Değişken	Değer
widget_date	GG.AA.YYYY biçiminde seçilen tarih
widget_time	SS:DD biçiminde seçilen saat; yalnızca tarih içeren takvimler için boş
widget_message_id	Widget'ı içeren mesajın kimliği

Tarih ve saat biçimleri, create_booking ve modify_booking_time tarafından kabul edilenlerle aynıdır.

---

Takvimle Çevrimiçi Rezervasyon: Tam Örnek

Widget, tarih seçimini, saat aralıklarını ve gezinmeyi yönetir ve gereken bot bloklarının sayısını azaltır.

Blok 1. Hizmet Seçimi

"Randevu al" koşuluyla bir Başlangıç Koşulu bloğu kullanın.

Yanıt: "Bir hizmet seçin:"

Düğmeler alanını #{srv_buttons} olarak ayarlayın.

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']

Blok 2. Takvim

Yanıt: #{none}.

Blok 1'i Blok 2'ye #{srv_checker} koşulunu kullanarak bağlayın.

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)

Blok 3. Rezervasyon Oluştur

Yanıt: #{none}.

Blok 2'yi Blok 3'e widget_calendar_selected koşulunu Tam eşleşme ile kullanarak bağlayın.

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']

Blok 4. Rezervasyon Onaylandı

Blok 3'ü Blok 4'e booking_ok == True değişken koşulunu bir saniyelik gecikmeyle kullanarak bağlayın.

Yanıt:

Randevunuz onaylandı: #{serv_title}, #{booking_date} #{booking_time}. Görüşmek üzere!

Blok 5. Saat Aralığı Artık Uygun Değil

Yanıt: #{none}.

Blok 3'ü Blok 5'e booking_ok != True değişken koşulunu bir saniyelik gecikmeyle kullanarak bağlayın.

Bu blok, mevcut takvimi sıfırlar, müşterinin başka bir saat seçmesine olanak tanır ve bir hata mesajı görüntüler.

fix = {}
fix["reset"] = 1
fix["error"] = "Bu saat aralığı az önce rezerve edildi. Lütfen başka birini seçin."
t = tg_edit_widget_data(platform_id, widget_message_id, fix)

Blok 5'ten Blok 3'e widget_calendar_selected koşuluyla başka bir bağlantı ekleyin.

Müşteri artık aynı takvimde başka bir saat seçebilir.

Daha Basit Seçenek: Otomatik Rezervasyon

Takvim ayarlarına aşağıdaki parametreyi ekleyin:

cal["auto_booking"] = 1

Platform, müşteri bir saat seçtiğinde rezervasyonu hemen oluşturacaktır.

Seçilen saat aralığı kullanılamaz hale gelirse, widget doğrudan bir hata görüntüler.

widget_calendar_selected geri çağrısı yalnızca başarılı bir rezervasyondan sonra, widget_booking_id değişkeniyle birlikte gönderilir.

Bu yaklaşımla Blok 3 ve Blok 5 gerekli değildir.

Ön ödeme veya randevuyu onaylamadan önce özel kontroller gerekiyorsa, bot akışı üzerinden rezervasyonu (ilk yaklaşım) kullanın.

---

Gönderilmiş Bir Widget'ı Güncelleme

Widget verilerini güncellemek için aşağıdaki işlevi kullanın:

tg_edit_widget_data(platform_id, message_id, data)

Parametre	Açıklama
message_id	Widget mesajının kimliği; gönderirken kaydedilir veya bir etkileşimden sonra widget_message_id'den alınır
data	Yeni değerleri içeren sözlük

Yalnızca widget verileri güncellenebilir. Zaten gönderilmiş bir widget'ın düzenini değiştiremezsiniz. Farklı bir düzen kullanmak için yeni bir widget gönderin.

Güncellemelerin nasıl uygulandığı:

• Promosyon kodu, zamanlayıcı, sipariş durumu, SSS: yeni veriler önceki güncellemeyi tamamen değiştirir. Eksik alanlar, widget gönderilirken sağlanan orijinal değerlere geri döner. Bu nedenle, başlangıç verilerinden farklı olması gereken her alanı ekleyin; örneğin hem step hem de text gibi.
• Test ve takvim: yeni veriler, mevcut widget durumunun üzerine uygulanır.

Özel güncelleme parametreleri:

Şablon	Veri	Sonuç
promo	{"used": 1}	Promosyon kodunu kullanılmış olarak işaretler
timer	{"seconds": 600} veya {"until": "…"}	Geri sayımı yeniden başlatır
calendar	{"reset": 1, "error": "message"}	Seçimi temizler, takvimi yeniden açar ve bir mesaj görüntüler

---

Özel Widget'lar

Hazır şablonlar yeterli olmadığında — örneğin, alışveriş sepetli bir ürün kataloğu, yıldız derecelendirmesi veya fiyat hesaplayıcıya ihtiyacınız varsa — özel bir HTML widget'ı oluşturabilirsiniz.

Nasıl Çalışır

1. Widget'ı, stillerini ve JavaScript'ini içeren tek bir HTML dosyası olarak oluşturun.
2. Kodu projenin Dosyalar bölümünde bir .txt dosyası olarak kaydedin ve dosya URL'sini kopyalayın. Depolama sistemi .html dosyalarını kabul etmez.
3. Bir bot bloğu, widget'ı URL'yi kullanarak gönderir ve başlangıç verilerini iletir.
4. Müşteri widget ile etkileşime girdiğinde, bot widget kodunda tanımlanan metni içeren bir geri çağrı alır.
5. Bir işleyici bloğu yeni verileri hesaplar ve widget'a geri gönderir; widget kendi arayüzünü günceller.

Özel Widget Gönderme

tg_send_widget_file(platform_id, url, data, caption)

Örnek:

st = {}
st["rating"] = 0
w = tg_send_widget_file(platform_id, "https://files.mavibot.ai/…/rating.txt", st, "Siparişinizi değerlendirin — bir yıldıza dokunun")

data parametresi, widget'ı işlemek için kullanılan başlangıç durumunu içeren bir sözlüktür.

Etkileşimleri İşleme

Müşteri özel bir widget ile etkileşime girdiğinde, bot bir geri çağrı alır.

Aşağıdaki değişkenler de doldurulur:

Değişken	Değer
widget_data	Widget tarafından gönderilen istek metni, örneğin rate:4
widget_message_id	Etkileşimin gerçekleştiği mesajın kimliği
widget_query_id	İstek kimliği

İşleyiciyi bir Tetikleyici bloğu kullanarak oluşturun ve Yalnızca Geri Çağrıda Tetikle ayarını etkinleştirin.

Koşul, widget istek metniyle eşleşmelidir.

Bu tür bir blok, müşterinin bot akışındaki mevcut konumundan bağımsız olarak çalışır ve onları mevcut adımlarından uzaklaştırmaz.

Önemli: Özel widget etkileşimlerini işlemek için bir Başlangıç Koşulu bloğu kullanmayın. Bir widget sohbette kalır ve müşteri onunla herhangi bir zamanda etkileşime girebilir — bir anketi doldururken, randevu alırken veya ödeme yaparken bile. Bir Başlangıç Koşulu bloğu, müşteriyi işleyiciye yönlendirir ve mevcut adımlarını kesintiye uğratır.

Örnek derecelendirme işleyicisi:

Koşul (düzenli ifade):

^rate:[1-5]$

Hesaplayıcı:

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)

Özel widget verileri güncellemeler sırasında tamamen değiştirilir. Yalnızca değişen alanı değil, her zaman tam durumu gönderin.

Veri boyutu sınırı 1024 bayttır.

Büyük, statik veri kümelerini (ürün katalogları gibi) widget kodunun içinde tutun ve widget verileri aracılığıyla yalnızca değişen değerleri gönderin.

Widget İsteğine Yanıt Verme

Varsayılan olarak, widget isteğine anında boş bir yanıt alır ve güncellenmiş veriler ayrı bir widget güncellemesiyle gelir.

Widget'ın isteğine yanıt olarak doğrudan veri alması gerekiyorsa, istek metni ? ile başlamalıdır, örneğin:

?price

Bu durumda, işleyici bloğu aşağıdaki işlevi 15 saniye içinde çağırmalıdır:

tg_answer_widget_query(data)

Aksi takdirde, widget bir zaman aşımı hatası görüntüler.

Yanıt boyutu sınırı 1024 bayttır.

Kod Gereksinimleri

• Tek dosya: stilleri <style> içine ve JavaScript'i <script> içine ekleyin. Harici komut dosyaları, stil sayfaları, yazı tipleri ve görüntüler yüklenemez. Görüntüler data: URL'leri veya SVG kullanılarak gömülmelidir.
• Boyut sınırları: sıkıştırmadan önce maksimum 32 KB ve sıkıştırmadan sonra 4 KB.
• Giriş alanı yok: input, select, textarea ve form öğeleri kaldırılır. Etkileşimli kontroller olarak yalnızca <button> öğeleri desteklenir.
• Ağ isteği yok: fetch ve benzeri API'ler çalışmaz. Botla iletişim kurmanın tek yolu, 1–64 bayt istek boyutuyla TelegramWidget.request("text") işlevidir.
• İç kaydırma yok: maksimum widget yüksekliği 600 pikseldir. Bunun ötesindeki her şey kırpılır. Bir karusel oluşturmak için kaydırma kullanmak yerine bir kart satırını hareket ettirin.
• Öğe erişimi: document.getElementById kullanın. Öğelere kimliklerine göre genel değişkenler olarak erişmek çalışmaz.
• Telegram teması: widget'ın hem açık hem de koyu temalarda doğru görünmesi için var(--tg-theme-text-color) gibi Telegram tema değişkenlerini kullanın.
• Widget verileri: verileri TelegramWidget.chatData'dan okuyun ve chatDataChanged olayı gerçekleştiğinde widget'ı yeniden çizin.
• İstekler: request işlevini doğrudan bir kullanıcı etkileşim işleyicisinin içinde çağırın. Etkileşim başına yalnızca bir isteğe izin verilir.

Widget kodlama hatalarını görüntülemez. Desteklenmeyen öğeler sessizce kaldırılır ve bir JavaScript hatası boş bir widget ile sonuçlanabilir. Değişiklik yaptıktan sonra widget'ı her zaman Telegram'da test edin.

Minimal Özel Widget Örneği

Aşağıdaki örnek, bir ürünü, bot'a istek gönderen bir düğmeyi ve widget verilerine dayalı bir sepet sayacını görüntüler.

<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">Sepete ekle</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='Sepette: '+(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='Hata: '+x.code
    }
  )
};

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

---

Mavi ve Widget'lar

Mavi, widget'larla otomatik olarak eksiksiz bot akışları oluşturabilir.

İhtiyacınız olanı düz bir dille tanımlamanız yeterlidir.

Örneğin:

• "Müşteri 'sipariş' gönderdiğinde, üç aşamalı bir sipariş durumu widget'ı görüntüleyin. 'hazır' gönderdiğinde, siparişi ikinci aşamaya taşıyın."
• "Bir hizmet rezervasyon akışı oluşturun: müşteriler butonları kullanarak bir hizmet seçer, ardından bir takvim widget'ı kullanarak tarih ve saat seçer."
• "Siparişler için bir yıldız derecelendirme widget'ı oluşturun ve seçilen derecelendirmeyi bir müşteri değişkenine kaydedin."

Mavi, hazır şablonları otomatik olarak yapılandırır.

Özel widget'lar için Mavi kodu yazar ve kontrol eder, widget dosyasını projeye kaydeder ve widget'ı göndermek ile müşteri etkileşimlerini işlemek için gereken blokları oluşturur.

---

Referans

Fonksiyonlar

Fonksiyon	Açıklama
tg_send_widget(platform_id, template, params, caption)	Hazır bir widget şablonu gönderir
tg_send_widget_file(platform_id, url, data, caption)	Bir dosyadan özel bir widget gönderir
tg_edit_widget_data(platform_id, message_id, data)	Mevcut bir widget'taki verileri günceller
tg_answer_widget_query(data)	? ile başlayan özel bir widget isteğine yanıt verir

Geri Çağırmalar ve Değişkenler

Olay	Geri Çağırma	Değişkenler
Test tamamlandı	widget_quiz_finished	widget_quiz_score, widget_quiz_total, widget_quiz_answers
Takvimde tarih ve saat seçildi	widget_calendar_selected	widget_date, widget_time; ayrıca auto_booking etkinleştirildiğinde widget_booking_id
Özel widget etkileşimi	Widget kodunda tanımlanan istek metni	widget_data, widget_message_id, widget_query_id

Botunuz birden fazla test veya takvim içeriyorsa, her widget'a callback parametresini kullanarak benzersiz bir geri çağırma atayın; böylece bot akış koşullarında bunları ayırt edebilirsiniz.

Sınırlamalar

• Widget'lar yalnızca müşteri ile bot arasındaki özel Telegram sohbetlerinde çalışır.
• Her müşteri için yalnızca en son beş test ve takvim saklanır. Daha eskileri etkileşimlere yanıt vermeyi durdurur.
• Bir bot akışında tüm müşteri değişkenlerini temizlemek, daha önce gönderilen testleri ve takvimleri devre dışı bırakır.
• Widget verileri 1024 bayt ile sınırlıdır.
• Özel widget istekleri 64 bayt ile sınırlıdır.
• tg_answer_widget_query gerektiren özel widget isteklerine 15 saniye içinde yanıt verilmelidir.

Sorun Giderme

Sorun	Neden / Çözüm
Widget gönderilmiyor ve değişken Unknown parameter… içeriyor	Şablon desteklenmeyen bir parametre aldı. Hata mesajı izin verilen parametreleri listeler
Takvim, tarih seçiminden sonra saat dilimlerini göstermeden duruyor	slots parametresi sağlanmadı
Bir widget ile etkileşimden sonra bot, mevcut adımdaki butonlara yanıt vermeyi durduruyor	Etkileşim işleyicisi bir Başlangıç Koşulu bloğu kullanıyor. Bunu Koşullu Durum Dışı Blok ile değiştirin
Özel widget boş görünüyor	Widget kodunda bir hata var. Yaygın bir neden, document.getElementById kullanmadan bir öğeye kimliğiyle erişmektir
Telegram "Unsupported message" görüntülüyor	Müşteri eski bir Telegram sürümü kullanıyor
Bad Request: chat not found	Widget Telegram dışından, örneğin bot test penceresinden gönderildi