Yerel bileşenler
Yerel bileşenler, inkiveta'ya özgü hazır arayüz parçalarıdır: ürün ızgarası, sepet, takvim, saat seçici, form, canlı kurye haritası, grafik… Sen yalnız veriyi JSON olarak gönderirsin; uygulama onu kendi tasarımıyla, açık/koyu temaya, yazı boyutuna ve erişilebilirlik ayarlarına uygun çizer. HTML ya da CSS yazmazsın.
Bileşen göndermek#
inkiSendComponent yöntemiyle:
bashcurl -s "https://app.inkiveta.com/bot$BOT_TOKEN/inkiSendComponent" -H 'Content-Type: application/json' -d '{
"chat_id": 4185489292941965,
"component": {"type":"notice","version":1,"tone":"success",
"title":"Randevun alındı","text":"Salı 14:30, Kadıköy şubesi."},
"fallback_text": "Randevun alındı: Salı 14:30, Kadıköy şubesi.",
"inki_importance": "high"
}'
| Parametre | Zorunlu | Açıklama |
|---|---|---|
chat_id | evet | Kullanıcının sohbet kimliği |
component | evet | Bileşen nesnesi: type, version (şimdilik hep 1) ve türe özel alanlar |
fallback_text | evet | Bileşeni tanımayan eski uygulama sürümlerinde gösterilen düz metin (≤ 4.096) |
reply_markup | Altına satır içi düğmeler | |
inki_importance | normal ya da high. Kullanıcı bildirimleri "önemliler" ya da "günde 1 özet" sıklığına ayarladıysa high bildirimi hemen gönderir (mesaj her durumda sohbete anında düşer) | |
message_thread_id, reply_parameters, disable_notification, protect_content | Normal mesajlardaki gibi |
Dönen Message nesnesinde bileşen inki_component alanındadır.
Kütüphanelerden çağırmak — inki önekli yöntemler kütüphanelerde hazır gelmez; ham çağrı kullanılır:
| Kütüphane | Ham çağrı |
|---|---|
| python-telegram-bot | await context.bot.do_api_request("inkiSendComponent", api_kwargs={...}) |
| aiogram | kendi TelegramMethod alt sınıfını yaz ya da aiohttp ile doğrudan POST et |
| Telegraf | await ctx.telegram.callApi("inkiSendComponent", {...}) |
| grammY | await bot.api.raw.inkiSendComponent({...}) (TypeScript'te as any) |
| Diğer | POST https://app.inkiveta.com/bot<token>/inkiSendComponent, JSON gövde |
Görünüm: renk yok, ton var#
Bileşenlerde renk, yazı tipi ya da boyut alanı yoktur. Görünümü iki ortak alanla yönlendirirsin:
tone:neutral·success·warning·danger·brandbrand_color:mavi·turuncu·mor·pembe·altin·yesil·turkuaz(Atölye paleti)
Tek istisna: [option_picker](#option-picker) içindeki swatch (#RRGGBB) — bu ürünün kendi rengidir (ör. saç boyası tonu), arayüz rengi değil.
Kurallar#
- Her nesnede bilinmeyen alan reddedilir. Hata biçimi:
400 Bad Request: component schema: <json-yolu>: <kural>, ör.component schema: /color: additionalProperties. - Alanlar arası kurallar da denetlenir (tablo satırının sütun sayısı,
selected'ın seçeneklerde olması gibi):duplicate,not-in-options,out-of-range,row-length,invalid-date… - Serileştirilmiş bileşen en çok 32 KiB.
- Medya alanları uygulamanın aldığı bir
file_idya dahttps://adresi alır. Adresler inkiveta tarafından indirilip yeniden barındırılır. - Formlarda parola, kart numarası, CVV, tek kullanımlık kod alanı yoktur. Kullanıcının uygulamaya yazdığı içerikte gizli bilgi algılayıcısı çalışır; uygulama "kodunu / şifreni / kart bilgini yaz" gibi bir şey isterse kullanıcıya güvenlik uyarısı gösterilir.
Etkileşime yanıt vermek#
Etkileşimli bileşenler (düğme, seçim, form…) kullanıcı bir şey yapınca sana inki_component_action update'i gönderir. Bunun için allowed_updates listende inki_component_action olmalı.
json{"update_id":5522,"inki_component_action":{
"id":"9f2c4a1b0d7e3c55",
"from":{"id":4185489292941965,"is_bot":false,"first_name":"Kullanıcı"},
"message":{"message_id":42,"chat":{"id":4185489292941965,"type":"private"}},
"component_type":"calendar","action":"select","values":{"date":"2026-11-18"}}}
action:submit(gönderdi),select(seçti),change(değiştirdi),close(form/sayfayı kapattı —valuesboş, yanıt beklenmez).- Her bileşenin hangi
valuesgönderdiği aşağıdaki katalogda "Kullanıcı etkileşince sana gelen" satırında yazılı. - 10 saniye içinde ve bir kez
inkiAnswerComponentActionile yanıtla:
| Parametre | Açıklama |
|---|---|
component_action_id | Update'teki id (zorunlu) |
toast | Kısa bildirim (≤ 200 karakter) |
close_sheet | true ise açık form/sayfayı kapatır |
replace_component | Mesajdaki bileşeni bununla değiştirir (ör. seçilen günün dolu saatlerini göster) |
fallback_text | replace_component için düz metin |
Geç ya da ikinci yanıt 400 Bad Request: query is too old and response timeout expired or query ID is invalid döner. values sunucuda şemaya göre yeniden doğrulanır; yine de kendi tarafında da doğrula.
pythonfrom telegram import Update
from telegram.ext import TypeHandler
async def bilesen(update: Update, context):
e = update.api_kwargs.get("inki_component_action")
if not e:
return
if e["component_type"] == "calendar" and e["action"] == "select":
gun = e["values"]["date"]
await context.bot.do_api_request("inkiAnswerComponentAction", api_kwargs={
"component_action_id": e["id"],
"replace_component": {"type": "time_strip", "version": 1,
"slots": [{"value": "1000", "time": "10:00"},
{"value": "1430", "time": "14:30"}]},
"fallback_text": f"{gun} için saatler: 10:00, 14:30",
})
app.add_handler(TypeHandler(Update, bilesen))
app.run_polling(allowed_updates=["message", "callback_query", "inki_component_action"])
Bileşeni güncellemek#
inkiEditMessageComponent gönderilmiş bir bileşeni yerinde değiştirir: chat_id, message_id, component (zorunlu), fallback_text, reply_markup (verilmezse satır içi düğmeler kalkar).
Canlı bileşenler — [live_courier](#live-courier), [goal_progress](#goal-progress), [live_poll](#live-poll), [live_score](#live-score) ve mode:"progress" kipindeki [steps](#steps) — bu yöntemle canlı güncellenmek için tasarlandı. Sınır: bileşen başına saniyede 1 güncelleme.
Not: Aşağıdaki örneklerdeki
*.exampleadresleri vefile_iddeğerleri yer tutucudur. Göndermeden önce kendi görselininhttps://adresini ya da uygulamanın aldığı birfile_id'yi koy; yoksa medya indirilemez ve istek reddedilir.
Katalog#
Metin ve bilgi: Zengin metin · Bilgi / başarı / uyarı kutusu · Anahtar–değer listesi · Tablo · Açılır sorular (SSS) · Zaman çizelgesi · Adım adım / canlı durum · Güvenlik kartı
Medya ve konum: Görsel kartı · Galeri · Video · Ses / podcast · Konum kartı · Bilet / QR · Belge · Kişi kartı
Alışveriş ve ödeme: Ürün ızgarası / karusel · Sepet · Seçenek seçici · Abonelik planları · Kupon · Bahşiş · Ink ile öde · Ödeme durumu
Seçiciler: Ay takvimi · Saat şeridi · Tekli seçim · Açılır menü · Aralık kaydırıcı · Adet + anahtarlar · Arayarak seç · Konum seç
Form ve akış: Çok adımlı form · Uzun metin · Fotoğraf / dosya yükleme · 0–10 öneri ölçeği · Duygu / puan · Onay · Geri al şeridi · Form özeti
Canlı ve veri: Canlı kurye · Geri sayım · Hedef ilerlemesi · Canlı anket · Çizgi grafik · Metrik kutuları · Canlı skor · Saatlik hava
Etkileşim ve oyun: Yarışma sorusu · Yarışma sonucu · Hızlı yanıtlar · Sekmeli menü · Takvime ekle / hatırlat · Davet / paylaş · Çekiliş · Sıralama tablosu
Oda çerçevesi: Uygulama ana sayfası
Metin ve bilgi#
Zengin metin — rich_text#
Zengin metin: başlık, paragraf, liste, alıntı, kod, LaTeX, ayraç. Telegram sendRichMessage blokları buna eşlenir. Serileştirilmiş bileşen en çok 32 KiB (bileşen boyut sınırı); blok/parça sınırları buna göre seçildi, uzun içerik birden çok bileşene bölünür.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | en çok 120 karakter | |
blocks | nesne dizisi | evet | en az 1 öğe; en çok 100 öğe |
blocks[].kind | metin | evet | şunlardan biri: heading, paragraph, list, quote, code, math, divider, footer |
blocks[].text | metin | en çok 4096 karakter; heading/quote/code/math/footer düz metni (math: LaTeX kaynağı) | |
blocks[].runs | nesne dizisi | en az 1 öğe; en çok 100 öğe; paragraph/quote/footer için satır içi parçalar; verilirse text'e üstündür | |
blocks[].runs[].text | metin | evet | en az 1 karakter; en çok 1000 karakter |
blocks[].runs[].marks | string dizisi | en az 0 öğe; en çok 9 öğe | |
blocks[].runs[].url | metin | desen ^https://[^\s\x00-\x1f\x7f]{1,2040}$ | |
blocks[].runs[].footnote | metin | en çok 500 karakter; dipnot metni (Telegram RichTextReference eşlemesi) | |
blocks[].items | nesne dizisi | en az 1 öğe; en çok 50 öğe | |
blocks[].items[].runs | nesne dizisi | evet | en az 1 öğe; en çok 50 öğe |
blocks[].items[].runs[].text | metin | evet | en az 1 karakter; en çok 1000 karakter |
blocks[].items[].runs[].marks | string dizisi | en az 0 öğe; en çok 9 öğe | |
blocks[].items[].runs[].url | metin | desen ^https://[^\s\x00-\x1f\x7f]{1,2040}$ | |
blocks[].items[].runs[].footnote | metin | en çok 500 karakter; dipnot metni (Telegram RichTextReference eşlemesi) | |
blocks[].ordered | evet/hayır | ||
blocks[].level | tam sayı | ≥ 1; ≤ 3; heading düzeyi | |
blocks[].language | metin | en çok 32 karakter; code bloğu dili | |
blocks[].anchor | metin | desen ^[A-Za-z0-9_-]{1,64}$; bağlantı çapası (RichBlockAnchor) |
Örnek JSON
json{
"type": "rich_text",
"version": 1,
"title": "Randevudan önce",
"blocks": [
{
"kind": "list",
"items": [
{
"runs": [
{
"text": "Saçın kuru gelsin"
}
]
},
{
"runs": [
{
"text": "5 dakika erken gel"
}
]
},
{
"runs": [
{
"text": "İptal için 2 saat önce yaz"
}
]
}
]
},
{
"kind": "paragraph",
"runs": [
{
"text": "Kampanya kodu "
},
{
"text": "KASIM25",
"marks": [
"code"
]
},
{
"text": " · "
},
{
"text": "koşulları oku",
"url": "https://sacstudyosu.example/kosullar"
}
]
}
]
}
Şema: [rich_text.schema.json](/gelistiriciler/semalar/rich_text.schema.json)
Bilgi / başarı / uyarı kutusu — notice#
Bilgi/başarı/dikkat/hata kutusu. Varyant tone ile seçilir: neutral=bilgi, success=tamam, warning=dikkat, danger=olmadı.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | en çok 80 karakter | |
text | metin | evet | en az 1 karakter; en çok 2000 karakter |
Örnek JSON
json{
"type": "notice",
"version": 1,
"tone": "warning",
"title": "Dikkat",
"text": "Yarın 1 saat gecikme olabilir."
}
Şema: [notice.schema.json](/gelistiriciler/semalar/notice.schema.json)
Anahtar–değer listesi — key_value#
Etkileşimli: inki_component_action üretir
Anahtar–değer listesi (sipariş özeti, makbuz). Satırın tone'u varsa değer rozet olarak çizilir.
Kullanıcı etkileşince sana gelen: submit → values = {"action_id": "actions[].action_id"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | en çok 80 karakter | |
rows | nesne dizisi | evet | en az 1 öğe; en çok 50 öğe |
rows[].label | metin | evet | en az 1 karakter; en çok 60 karakter |
rows[].value | metin | evet | en az 1 karakter; en çok 200 karakter |
rows[].tone | metin | şunlardan biri: neutral, success, warning, danger, brand | |
actions | nesne dizisi | en az 1 öğe; en çok 3 öğe | |
actions[].action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
actions[].label | metin | evet | en az 1 karakter; en çok 40 karakter |
actions[].style | metin | şunlardan biri: primary, secondary, danger | |
actions[].disabled | evet/hayır |
Örnek JSON
json{
"type": "key_value",
"version": 1,
"rows": [
{
"label": "Sipariş no",
"value": "#48213"
},
{
"label": "Tarih",
"value": "11 Kas 2026, 10:40"
},
{
"label": "Teslimat",
"value": "Kapıya, 14:00–16:00"
},
{
"label": "Durum",
"value": "Hazırlanıyor",
"tone": "warning"
}
]
}
Şema: [key_value.schema.json](/gelistiriciler/semalar/key_value.schema.json)
Tablo — table#
Tablo. Her satırın hücre sayısı columns sayısına eşit olmalı (istemci eksiği boş, fazlayı kırpar).
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | en çok 80 karakter | |
columns | nesne dizisi | evet | en az 1 öğe; en çok 8 öğe |
columns[].label | metin | evet | en çok 60 karakter |
columns[].align | metin | şunlardan biri: start, center, end | |
columns[].highlight | evet/hayır | sütun vurgulu (ör. önerilen plan) | |
rows | array dizisi | evet | en az 1 öğe; en çok 50 öğe |
caption | metin | en çok 200 karakter |
Örnek JSON
json{
"type": "table",
"version": 1,
"columns": [
{
"label": "",
"align": "start"
},
{
"label": "Temel",
"align": "center"
},
{
"label": "Artı",
"align": "center",
"highlight": true
}
],
"rows": [
[
"Aylık ders",
"4",
"12"
],
[
"Canlı soru",
"—",
"Var"
],
[
"Fiyat",
"₺199",
"₺349"
]
]
}
Şema: [table.schema.json](/gelistiriciler/semalar/table.schema.json)
Açılır sorular (SSS) — accordion#
Açılır sorular (SSS). Aç/kapa istemcide yerel; bota eylem gitmez.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | en çok 80 karakter | |
items | nesne dizisi | evet | en az 1 öğe; en çok 30 öğe |
items[].id | metin | evet | desen ^[a-z][a-z0-9_]{0,31}$; form alanı/grup kimliği; values anahtarı |
items[].question | metin | evet | en az 1 karakter; en çok 200 karakter |
items[].answer | metin | evet | en az 1 karakter; en çok 2000 karakter |
items[].open | evet/hayır | başlangıçta açık | |
allow_multiple | evet/hayır | birden fazla madde aynı anda açık kalabilir |
Örnek JSON
json{
"type": "accordion",
"version": 1,
"items": [
{
"id": "kart",
"question": "Kart ile ödeyebilir miyim?",
"answer": "Evet, salonda kredi ve banka kartı geçer."
},
{
"id": "iptal",
"question": "Randevuyu nasıl iptal ederim?",
"answer": "Randevu kartındaki “Değiştir”e dokun ya da bana “iptal” yaz. 2 saatten kısa sürede ücret alınmaz.",
"open": true
},
{
"id": "otopark",
"question": "Otopark var mı?",
"answer": "Sokak arkasında ücretsiz otopark var."
}
]
}
Şema: [accordion.schema.json](/gelistiriciler/semalar/accordion.schema.json)
Zaman çizelgesi — timeline#
Zaman çizelgesi (kargo takibi vb.).
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | en çok 80 karakter | |
events | nesne dizisi | evet | en az 1 öğe; en çok 40 öğe |
events[].time | metin | en çok 20 karakter | |
events[].text | metin | evet | en az 1 karakter; en çok 300 karakter |
events[].state | metin | evet | şunlardan biri: done, current, pending |
Örnek JSON
json{
"type": "timeline",
"version": 1,
"events": [
{
"time": "09:12",
"text": "Kargo yola çıktı · Tuzla",
"state": "done"
},
{
"time": "11:40",
"text": "Aktarma merkezinde",
"state": "done"
},
{
"time": "13:05",
"text": "Dağıtıma çıktı",
"state": "current"
},
{
"time": "—",
"text": "Teslim edilecek",
"state": "pending"
}
]
}
Şema: [timeline.schema.json](/gelistiriciler/semalar/timeline.schema.json)
Adım adım / canlı durum — steps#
Etkileşimli: inki_component_action üretirCanlı güncellenebilir (1/sn)
Adım adım talimat; mode:"progress" ise canlı durum kartı (sıra/ilerleme çizgisi, current adımı vurgular, live rozeti).
Kullanıcı etkileşince sana gelen: submit → values = {"action_id": "actions[].action_id"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | en çok 80 karakter | |
subtitle | metin | en çok 200 karakter | |
mode | metin | şunlardan biri: instructions, progress | |
steps | nesne dizisi | evet | en az 1 öğe; en çok 20 öğe |
steps[].text | metin | evet | en az 1 karakter; en çok 300 karakter |
steps[].detail | metin | en çok 300 karakter | |
current | tam sayı | ≥ 0; ≤ 19; progress modunda geçerli adım (0'dan) | |
live | evet/hayır | canlı rozeti; güncellemeler inkiEditMessageComponent ile | |
actions | nesne dizisi | en az 1 öğe; en çok 3 öğe | |
actions[].action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
actions[].label | metin | evet | en az 1 karakter; en çok 40 karakter |
actions[].style | metin | şunlardan biri: primary, secondary, danger | |
actions[].disabled | evet/hayır |
Örnek JSON
json{
"type": "steps",
"version": 1,
"title": "Modemi yeniden başlat",
"mode": "instructions",
"steps": [
{
"text": "Arkadaki güç düğmesine 10 sn bas"
},
{
"text": "Işıklar sönünce 30 sn bekle"
},
{
"text": "Tekrar aç, internet ışığı yeşil yanmalı"
}
],
"actions": [
{
"action_id": "yaptim",
"label": "Yaptım, düzeldi",
"style": "primary"
},
{
"action_id": "hala_yok",
"label": "Hâlâ yok",
"style": "secondary"
}
]
}
Şema: [steps.schema.json](/gelistiriciler/semalar/steps.schema.json)
Güvenlik kartı — security_card#
Yalnız sistem üretir — uygulama gönderemezEtkileşimli: inki_component_action üretir
Güvenlik kartı. YALNIZ sistem üretir (istemci algılayıcısı / sunucu algılayıcı): bot gönderemez.
Kullanıcı etkileşince sana gelen: submit → values = {"action_id": "block_report|continue (istemci/sistem işler; bota gitmez)"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | evet | en az 1 karakter; en çok 120 karakter |
text | metin | evet | en az 1 karakter; en çok 500 karakter |
risk | metin | evet | şunlardan biri: code_request, password_request, card_request, payment_request, unverified_bot |
actions | nesne dizisi | evet | en az 1 öğe; en çok 3 öğe |
actions[].action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
actions[].label | metin | evet | en az 1 karakter; en çok 40 karakter |
actions[].style | metin | şunlardan biri: primary, secondary, danger | |
actions[].disabled | evet/hayır |
Örnek JSON
json{
"type": "security_card",
"version": 1,
"tone": "danger",
"title": "Bu uygulama senden doğrulama kodu istiyor",
"text": "Gerçek destek ekipleri şifre, SMS kodu ya da kart bilgisi istemez. Bu uygulama doğrulanmamış ve 3 gün önce açıldı.",
"risk": "code_request",
"actions": [
{
"action_id": "block_report",
"label": "Engelle, bildir",
"style": "danger"
},
{
"action_id": "continue",
"label": "Yine de devam",
"style": "secondary"
}
]
}
Şema: [security_card.schema.json](/gelistiriciler/semalar/security_card.schema.json)
Medya ve konum#
Görsel kartı — image_card#
Etkileşimli: inki_component_action üretir
Görsel kartı.
Kullanıcı etkileşince sana gelen: submit → values = {"action_id": "actions[].action_id"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
image | metin | evet | desen ^(https://[^\s\x00-\x1f\x7f]{1,2040}|[A-Za-z0-9_.:-]{8,256})$; medya (photo): botunun aldığı file_id ya da https:// adresi; Telegram sözleşmesi: file_id ya da https URL (sunucu egress ile indirip yeniden barındırır) |
alt | metin | en çok 200 karakter | |
title | metin | en çok 120 karakter | |
text | metin | en çok 500 karakter | |
actions | nesne dizisi | en az 1 öğe; en çok 3 öğe | |
actions[].action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
actions[].label | metin | evet | en az 1 karakter; en çok 40 karakter |
actions[].style | metin | şunlardan biri: primary, secondary, danger | |
actions[].disabled | evet/hayır |
Örnek JSON
json{
"type": "image_card",
"version": 1,
"brand_color": "pembe",
"image": "https://cdn.ornek-bot.example/gorsel/kis-boyasi.jpg",
"alt": "Bakır ve kestane tonlarında boyanmış saç",
"title": "Kış boyası koleksiyonu",
"text": "Bakır ve kestane tonları bu ay %20 indirimli.",
"actions": [
{
"action_id": "tonlari_gor",
"label": "Tonları gör",
"style": "primary"
}
]
}
Şema: [image_card.schema.json](/gelistiriciler/semalar/image_card.schema.json)
Galeri — gallery#
Galeri (kolaj). total_count > görüntü sayısı ise son karoda “+N” gösterilir; dokunma tam ekran görüntüleyiciyi açar (yerel).
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
images | string dizisi | evet | en az 1 öğe; en çok 10 öğe |
total_count | tam sayı | ≥ 1; ≤ 9999 | |
caption | metin | en çok 200 karakter |
Örnek JSON
json{
"type": "gallery",
"version": 1,
"images": [
"https://cdn.ornek-bot.example/gorsel/model-1.jpg",
"https://cdn.ornek-bot.example/gorsel/model-2.jpg",
"https://cdn.ornek-bot.example/gorsel/model-3.jpg",
"https://cdn.ornek-bot.example/gorsel/model-4.jpg",
"https://cdn.ornek-bot.example/gorsel/model-5.jpg"
],
"total_count": 17,
"caption": "Son çalışmalarımız"
}
Şema: [gallery.schema.json](/gelistiriciler/semalar/gallery.schema.json)
Video — video#
Video. animation:true ise sessiz döngü (Telegram animasyonu).
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
source | metin | evet | desen ^(https://[^\s\x00-\x1f\x7f]{1,2040}|[A-Za-z0-9_.:-]{8,256})$; medya (video): botunun aldığı file_id ya da https:// adresi; Telegram sözleşmesi: file_id ya da https URL (sunucu egress ile indirip yeniden barındırır) |
poster | metin | desen ^(https://[^\s\x00-\x1f\x7f]{1,2040}|[A-Za-z0-9_.:-]{8,256})$; medya (photo): botunun aldığı file_id ya da https:// adresi; Telegram sözleşmesi: file_id ya da https URL (sunucu egress ile indirip yeniden barındırır) | |
duration_seconds | tam sayı | ≥ 0; ≤ 86400 | |
title | metin | en çok 120 karakter | |
animation | evet/hayır |
Örnek JSON
json{
"type": "video",
"version": 1,
"brand_color": "mor",
"source": "BAACAgQAAxkBAAIC_video_fon_teknigi",
"poster": "https://cdn.ornek-bot.example/gorsel/fon-teknigi.jpg",
"duration_seconds": 102,
"title": "Fön tekniği"
}
Şema: [video.schema.json](/gelistiriciler/semalar/video.schema.json)
Ses / podcast — audio#
Ses / podcast / sesli mesaj. waveform 0–100 genlikler; çalma durumu istemcide.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
source | metin | evet | desen ^(https://[^\s\x00-\x1f\x7f]{1,2040}|[A-Za-z0-9_.:-]{8,256})$; medya (audio): botunun aldığı file_id ya da https:// adresi; Telegram sözleşmesi: file_id ya da https URL (sunucu egress ile indirip yeniden barındırır) |
title | metin | evet | en az 1 karakter; en çok 120 karakter |
duration_seconds | tam sayı | evet | ≥ 0; ≤ 86400 |
position_seconds | tam sayı | ≥ 0; ≤ 86400 | |
waveform | integer dizisi | en az 1 öğe; en çok 128 öğe | |
kind | metin | şunlardan biri: music, podcast, voice |
Örnek JSON
json{
"type": "audio",
"version": 1,
"kind": "podcast",
"source": "CQACAgQAAxkBAAIC_bolum_41",
"title": "Günün 5 kelimesi · Bölüm 41",
"duration_seconds": 182,
"position_seconds": 68,
"waveform": [
15,
14,
13,
12,
11,
10,
9,
8,
7,
6,
5,
4,
22,
21,
20,
19,
18,
17,
16,
15,
14,
13,
12,
11,
10,
9,
8,
7,
6,
5,
4,
22,
21,
20
]
}
Şema: [audio.schema.json](/gelistiriciler/semalar/audio.schema.json)
Konum kartı — location#
Konum kartı (harita + yol tarifi düğmesi istemcide).
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
latitude | sayı | evet | ≥ -90; ≤ 90 |
longitude | sayı | evet | ≥ -180; ≤ 180 |
title | metin | en çok 120 karakter | |
address | metin | en çok 200 karakter |
Örnek JSON
json{
"type": "location",
"version": 1,
"latitude": 40.9876,
"longitude": 29.0262,
"title": "Saç Stüdyosu",
"address": "Caferağa Mh. Moda Cd. 41, Kadıköy"
}
Şema: [location.schema.json](/gelistiriciler/semalar/location.schema.json)
Bilet / QR — ticket#
Bilet / QR. code QR içeriğidir; istemci çizer.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
code | metin | evet | en az 1 karakter; en çok 1024 karakter |
title | metin | evet | en az 1 karakter; en çok 120 karakter |
badge | metin | en çok 40 karakter | |
details | string dizisi | en az 0 öğe; en çok 4 öğe | |
hint | metin | en çok 80 karakter |
Örnek JSON
json{
"type": "ticket",
"version": 1,
"code": "INK-TKT-48213-G12",
"badge": "Salon 4 · G12",
"title": "Ay Işığı Sokağı",
"details": [
"Cuma 21:15",
"Kadıköy Seans"
],
"hint": "Girişte okut"
}
Şema: [ticket.schema.json](/gelistiriciler/semalar/ticket.schema.json)
Belge — document#
Belge (indir). Boyut sınırı Bot API belge sınırıdır (50 MB).
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
file | metin | evet | desen ^(https://[^\s\x00-\x1f\x7f]{1,2040}|[A-Za-z0-9_.:-]{8,256})$; medya (document): botunun aldığı file_id ya da https:// adresi; Telegram sözleşmesi: file_id ya da https URL (sunucu egress ile indirip yeniden barındırır) |
file_name | metin | evet | en az 1 karakter; en çok 200 karakter |
size_bytes | tam sayı | ≥ 0; ≤ 52428800 | |
pages | tam sayı | ≥ 1; ≤ 100000 | |
mime_type | metin | desen ^[a-z]+/[A-Za-z0-9.+-]{1,100}$ |
Örnek JSON
json{
"type": "document",
"version": 1,
"file": "BQACAgQAAxkBAAIC_fatura_kasim",
"file_name": "Fatura_Kasım.pdf",
"size_bytes": 188416,
"pages": 2,
"mime_type": "application/pdf"
}
Şema: [document.schema.json](/gelistiriciler/semalar/document.schema.json)
Kişi kartı — contact_card#
Kişi kartı. Ara/Rehbere ekle düğmeleri phone varlığından istemcide türetilir (rehbere ekleme izin ister).
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
name | metin | evet | en az 1 karakter; en çok 80 karakter |
subtitle | metin | en çok 120 karakter | |
avatar | metin | desen ^(https://[^\s\x00-\x1f\x7f]{1,2040}|[A-Za-z0-9_.:-]{8,256})$; medya (photo): botunun aldığı file_id ya da https:// adresi; Telegram sözleşmesi: file_id ya da https URL (sunucu egress ile indirip yeniden barındırır) | |
phone | metin | desen ^\+?[0-9 ()-]{5,20}$ | |
email | metin | desen ^[^@\s]{1,64}@[^@\s]{1,190}\.[^@\s]{2,63}$ |
Örnek JSON
json{
"type": "contact_card",
"version": 1,
"brand_color": "mavi",
"name": "Mert Usta",
"subtitle": "Saç Stüdyosu · kıdemli usta",
"phone": "+90 555 010 20 30"
}
Şema: [contact_card.schema.json](/gelistiriciler/semalar/contact_card.schema.json)
Alışveriş ve ödeme#
Ürün ızgarası / karusel — product_grid#
Etkileşimli: inki_component_action üretir
Ürün ızgarası; layout:"carousel" ise yatay karusel (hizmet kartı: meta süre, cta_label düğme).
Kullanıcı etkileşince sana gelen: select → values = {"value": "items[].value"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
layout | metin | şunlardan biri: grid, carousel | |
items | nesne dizisi | evet | en az 1 öğe; en çok 30 öğe |
items[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
items[].name | metin | evet | en az 1 karakter; en çok 80 karakter |
items[].price | nesne | tutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar | |
items[].price.amount | sayı | evet | ≥ 0; ≤ 1000000000 |
items[].price.currency | metin | evet | şunlardan biri: TRY, INK, USD, EUR |
items[].subtitle | metin | en çok 120 karakter | |
items[].meta | metin | en çok 40 karakter | |
items[].image | metin | desen ^(https://[^\s\x00-\x1f\x7f]{1,2040}|[A-Za-z0-9_.:-]{8,256})$; medya (photo): botunun aldığı file_id ya da https:// adresi; Telegram sözleşmesi: file_id ya da https URL (sunucu egress ile indirip yeniden barındırır) | |
items[].brand_color | metin | şunlardan biri: mavi, turuncu, mor, pembe, altin, yesil, turkuaz | |
items[].quantity | tam sayı | ≥ 0; ≤ 99; sepetteki adet | |
items[].badge | metin | en çok 30 karakter | |
items[].unavailable | evet/hayır | ||
items[].cta_label | metin | en çok 30 karakter |
Örnek JSON
json{
"type": "product_grid",
"version": 1,
"layout": "grid",
"items": [
{
"value": "margarita",
"name": "Margarita",
"price": {
"amount": 240,
"currency": "TRY"
},
"brand_color": "pembe",
"quantity": 2
},
{
"value": "sucuklu",
"name": "Sucuklu",
"price": {
"amount": 285,
"currency": "TRY"
},
"brand_color": "turuncu"
},
{
"value": "ayran",
"name": "Ayran",
"price": {
"amount": 35,
"currency": "TRY"
},
"brand_color": "mavi"
},
{
"value": "tiramisu",
"name": "Tiramisu",
"price": {
"amount": 120,
"currency": "TRY"
},
"brand_color": "altin"
}
]
}
Şema: [product_grid.schema.json](/gelistiriciler/semalar/product_grid.schema.json)
Sepet — cart#
Etkileşimli: inki_component_action üretir
Sepet. Satır adedi değişince change; total botun otoriter toplamıdır.
Kullanıcı etkileşince sana gelen: change → values = {"lines[].id": "yeni adet (0 = çıkar)"}; submit → values = {"action_id": "actions[].action_id"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
lines | nesne dizisi | evet | en az 1 öğe; en çok 50 öğe |
lines[].id | metin | evet | desen ^[a-z][a-z0-9_]{0,31}$; form alanı/grup kimliği; values anahtarı |
lines[].name | metin | evet | en az 1 karakter; en çok 80 karakter |
lines[].unit_price | nesne | evet | tutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar |
lines[].unit_price.amount | sayı | evet | ≥ 0; ≤ 1000000000 |
lines[].unit_price.currency | metin | evet | şunlardan biri: TRY, INK, USD, EUR |
lines[].quantity | tam sayı | evet | ≥ 0; ≤ 99 |
lines[].max_quantity | tam sayı | ≥ 1; ≤ 99 | |
total | nesne | evet | tutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar |
total.amount | sayı | evet | ≥ 0; ≤ 1000000000 |
total.currency | metin | evet | şunlardan biri: TRY, INK, USD, EUR |
actions | nesne dizisi | en az 1 öğe; en çok 3 öğe | |
actions[].action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
actions[].label | metin | evet | en az 1 karakter; en çok 40 karakter |
actions[].style | metin | şunlardan biri: primary, secondary, danger | |
actions[].disabled | evet/hayır |
Örnek JSON
json{
"type": "cart",
"version": 1,
"lines": [
{
"id": "margarita",
"name": "Margarita",
"unit_price": {
"amount": 240,
"currency": "TRY"
},
"quantity": 2
},
{
"id": "ayran",
"name": "Ayran",
"unit_price": {
"amount": 35,
"currency": "TRY"
},
"quantity": 1
}
],
"total": {
"amount": 515,
"currency": "TRY"
},
"actions": [
{
"action_id": "checkout",
"label": "Siparişi tamamla",
"style": "primary"
}
]
}
Şema: [cart.schema.json](/gelistiriciler/semalar/cart.schema.json)
Seçenek seçici — option_picker#
Etkileşimli: inki_component_action üretir
Seçenek seçici (beden, renk, ek hizmet). kind:"swatches" renk örneği; swatch ÜRÜN VERİSİ (kumaş/ürün rengi), tema rengi DEĞİL — tek sanctioned istisna.
Kullanıcı etkileşince sana gelen: change → values = {"groups[].id": "seçili değer (multiple:true ise değer dizisi)"}; submit → values = {"action_id": "actions[].action_id"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | en çok 80 karakter | |
groups | nesne dizisi | evet | en az 1 öğe; en çok 6 öğe |
groups[].id | metin | evet | desen ^[a-z][a-z0-9_]{0,31}$; form alanı/grup kimliği; values anahtarı |
groups[].label | metin | evet | en az 1 karakter; en çok 60 karakter |
groups[].kind | metin | şunlardan biri: chips, swatches, checklist | |
groups[].multiple | evet/hayır | ||
groups[].options | nesne dizisi | evet | en az 1 öğe; en çok 30 öğe |
groups[].options[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
groups[].options[].label | metin | evet | en az 1 karakter; en çok 40 karakter |
groups[].options[].swatch | metin | desen ^#[0-9A-Fa-f]{6}$; ürün rengi (#RRGGBB) | |
groups[].options[].detail | metin | en çok 60 karakter; ör. +₺150 | |
groups[].options[].unavailable | evet/hayır | ||
groups[].selected | string dizisi | en az 0 öğe; en çok 30 öğe | |
actions | nesne dizisi | en az 1 öğe; en çok 3 öğe | |
actions[].action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
actions[].label | metin | evet | en az 1 karakter; en çok 40 karakter |
actions[].style | metin | şunlardan biri: primary, secondary, danger | |
actions[].disabled | evet/hayır |
Örnek JSON
json{
"type": "option_picker",
"version": 1,
"groups": [
{
"id": "beden",
"label": "Beden",
"kind": "chips",
"options": [
{
"value": "s",
"label": "S"
},
{
"value": "m",
"label": "M"
},
{
"value": "l",
"label": "L"
},
{
"value": "xl",
"label": "XL",
"unavailable": true
}
],
"selected": [
"m"
]
},
{
"id": "renk",
"label": "Renk",
"kind": "swatches",
"options": [
{
"value": "lacivert",
"label": "Lacivert",
"swatch": "#233A6B"
},
{
"value": "gri",
"label": "Gri",
"swatch": "#8A8F94"
},
{
"value": "kiremit",
"label": "Kiremit",
"swatch": "#B4462F"
},
{
"value": "krem",
"label": "Krem",
"swatch": "#E9E1D3"
}
],
"selected": [
"lacivert"
]
}
]
}
Şema: [option_picker.schema.json](/gelistiriciler/semalar/option_picker.schema.json)
Abonelik planları — plans#
Etkileşimli: inki_component_action üretir
Abonelik planları. Ödeme ink_pay/sendInvoice ile; bu bileşen yalnız seçtirir.
Kullanıcı etkileşince sana gelen: select → values = {"value": "plans[].value"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
plans | nesne dizisi | evet | en az 1 öğe; en çok 6 öğe |
plans[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
plans[].name | metin | evet | en az 1 karakter; en çok 40 karakter |
plans[].price | nesne | evet | tutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar |
plans[].price.amount | sayı | evet | ≥ 0; ≤ 1000000000 |
plans[].price.currency | metin | evet | şunlardan biri: TRY, INK, USD, EUR |
plans[].period | metin | şunlardan biri: week, month, year | |
plans[].features | string dizisi | en az 0 öğe; en çok 8 öğe | |
plans[].recommended | evet/hayır | ||
plans[].cta_label | metin | en çok 30 karakter |
Örnek JSON
json{
"type": "plans",
"version": 1,
"plans": [
{
"value": "temel",
"name": "Temel",
"price": {
"amount": 99,
"currency": "TRY"
},
"period": "month",
"features": [
"4 ders",
"Sınav"
]
},
{
"value": "arti",
"name": "Artı",
"price": {
"amount": 199,
"currency": "TRY"
},
"period": "month",
"features": [
"12 ders",
"Canlı soru",
"Sertifika"
],
"recommended": true
},
{
"value": "aile",
"name": "Aile",
"price": {
"amount": 299,
"currency": "TRY"
},
"period": "month",
"features": [
"4 kişi",
"Her şey"
]
}
]
}
Şema: [plans.schema.json](/gelistiriciler/semalar/plans.schema.json)
Kupon — coupon#
Kupon. Kodu kopyalama istemcide yerel.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
code | metin | evet | en az 1 karakter; en çok 32 karakter |
discount | nesne | evet | |
discount.kind | metin | evet | şunlardan biri: percent, amount |
discount.value | sayı | evet | ≥ 0; ≤ 1000000000 |
discount.currency | metin | şunlardan biri: TRY, INK, USD, EUR | |
title | metin | en çok 80 karakter | |
min_spend | nesne | tutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar | |
min_spend.amount | sayı | evet | ≥ 0; ≤ 1000000000 |
min_spend.currency | metin | evet | şunlardan biri: TRY, INK, USD, EUR |
valid_until | metin | desen ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$; YYYY-MM-DD |
Örnek JSON
json{
"type": "coupon",
"version": 1,
"brand_color": "altin",
"code": "KASIM25",
"discount": {
"kind": "percent",
"value": 25
},
"min_spend": {
"amount": 300,
"currency": "TRY"
},
"valid_until": "2026-11-30"
}
Şema: [coupon.schema.json](/gelistiriciler/semalar/coupon.schema.json)
Bahşiş — tip#
Etkileşimli: inki_component_action üretir
Bahşiş. allow_custom ise “Diğer” düğmesi tutar girişi açar.
Kullanıcı etkileşince sana gelen: select → values = {"value": "options[].value | custom", "amount": "value=custom ise girilen tutar"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | evet | en az 1 karakter; en çok 80 karakter |
options | nesne dizisi | evet | en az 1 öğe; en çok 6 öğe |
options[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
options[].amount | nesne | evet | tutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar |
options[].amount.amount | sayı | evet | ≥ 0; ≤ 1000000000 |
options[].amount.currency | metin | evet | şunlardan biri: TRY, INK, USD, EUR |
allow_custom | evet/hayır | “Diğer” tutar girişi. custom değeri bu eyleme AYRILMIŞTIR: seçenek değeri olamaz (/options/i/value: not-allowed); allow_custom kapalıyken select {value:"custom"} reddedilir. | |
selected | metin | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
Örnek JSON
json{
"type": "tip",
"version": 1,
"title": "Kuryene bahşiş bırak",
"options": [
{
"value": "t20",
"amount": {
"amount": 20,
"currency": "TRY"
}
},
{
"value": "t40",
"amount": {
"amount": 40,
"currency": "TRY"
}
},
{
"value": "t60",
"amount": {
"amount": 60,
"currency": "TRY"
}
}
],
"allow_custom": true,
"selected": "t40"
}
Şema: [tip.schema.json](/gelistiriciler/semalar/tip.schema.json)
Ink ile öde — ink_pay#
Ödemeler açıkken çizilir; kapalıyken fallback_text görünürEtkileşimli: inki_component_action üretir
Ink ile öde (satır içi; ödemeler açıkken). Düğme invoice ile ödeme sayfasını açar; tutarı sunucu faturayla karşılaştırır (uyuşmazlık = bileşen reddi). Yalnız dijital ürün.
Kullanıcı etkileşince sana gelen: submit → values = {"action_id": "pay (ödeme sayfası açılır; sonuç pre_checkout_query / successful_payment ile gelir)"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | evet | en az 1 karakter; en çok 80 karakter |
description | metin | en çok 200 karakter | |
invoice | metin | evet | desen ^[A-Za-z0-9_-]{1,64}$; createInvoiceLink/sendInvoice fatura kodu |
amount | tam sayı | evet | ≥ 1; ≤ 100000000; Ink, tam sayı |
invoice_payload | metin | en çok 128 karakter | |
urun_sinifi | metin | evet | şunlardan biri: dijital; Ink yalnız dijital ürün için; fiziksel ürün sağlayıcı akışıdır |
button_label | metin | en çok 30 karakter |
Örnek JSON
json{
"type": "ink_pay",
"version": 1,
"brand_color": "altin",
"title": "Pro tema paketi",
"description": "Bot içi dijital ürün",
"invoice": "pro_tema_8f3a2c",
"amount": 120,
"invoice_payload": "pro-tema-v1",
"urun_sinifi": "dijital"
}
Şema: [ink_pay.schema.json](/gelistiriciler/semalar/ink_pay.schema.json)
Ödeme durumu — payment_status#
Ödemeler açıkken çizilir; kapalıyken fallback_text görünürEtkileşimli: inki_component_action üretir
Ödeme durumu (ödemeler açıkken). payment_id = telegram_payment_charge_id (bc_<ulid>).
Kullanıcı etkileşince sana gelen: submit → values = {"action_id": "actions[].action_id"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
status | metin | evet | şunlardan biri: paid, pending, failed, refunded, partially_refunded |
amount | nesne | evet | tutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar |
amount.amount | sayı | evet | ≥ 0; ≤ 1000000000 |
amount.currency | metin | evet | şunlardan biri: TRY, INK, USD, EUR |
description | metin | en çok 160 karakter | |
paid_at | tam sayı | ≥ 0; ≤ 4102444800; Unix saniye (UTC) | |
method | metin | şunlardan biri: ink, provider | |
payment_id | metin | desen ^bc_[0-9A-Za-z]{10,40}$ | |
actions | nesne dizisi | en az 1 öğe; en çok 2 öğe | |
actions[].action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
actions[].label | metin | evet | en az 1 karakter; en çok 40 karakter |
actions[].style | metin | şunlardan biri: primary, secondary, danger | |
actions[].disabled | evet/hayır |
Örnek JSON
json{
"type": "payment_status",
"version": 1,
"tone": "success",
"status": "paid",
"amount": {
"amount": 515,
"currency": "INK"
},
"description": "Pizza Ev",
"paid_at": 1794383520,
"method": "ink",
"payment_id": "bc_01JCKZ3N8M5Q7R2T4V6W9X1Y3Z",
"actions": [
{
"action_id": "request_refund",
"label": "İade iste",
"style": "secondary"
}
]
}
Şema: [payment_status.schema.json](/gelistiriciler/semalar/payment_status.schema.json)
Seçiciler#
Ay takvimi — calendar#
Etkileşimli: inki_component_action üretir
Ay takvimi. Gün seçimi select; ay değişimi change (bot yeni ayın doluluğunu inkiAnswerComponentAction.replace_component ile gönderir).
Kullanıcı etkileşince sana gelen: select → values = {"date": "YYYY-MM-DD"}; change → values = {"month": "YYYY-MM"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
month | metin | evet | desen ^\d{4}-(0[1-9]|1[0-2])$; YYYY-MM |
selected | metin | desen ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$; YYYY-MM-DD | |
min_date | metin | desen ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$; YYYY-MM-DD | |
max_date | metin | desen ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$; YYYY-MM-DD | |
disabled_dates | string dizisi | en az 0 öğe; en çok 31 öğe; seçilemez (dolu/kapalı) günler | |
marked_dates | string dizisi | en az 0 öğe; en çok 31 öğe; nokta ile işaretli günler (müsait vb.) |
Örnek JSON
json{
"type": "calendar",
"version": 1,
"month": "2026-11",
"selected": "2026-11-13",
"min_date": "2026-11-11",
"disabled_dates": [
"2026-11-01",
"2026-11-08",
"2026-11-15",
"2026-11-22",
"2026-11-29"
],
"marked_dates": [
"2026-11-12",
"2026-11-14",
"2026-11-18",
"2026-11-20"
]
}
Şema: [calendar.schema.json](/gelistiriciler/semalar/calendar.schema.json)
Saat şeridi — time_strip#
Etkileşimli: inki_component_action üretir
Saat şeridi (yatay kaydırılır).
Kullanıcı etkileşince sana gelen: select → values = {"value": "slots[].value"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
slots | nesne dizisi | evet | en az 1 öğe; en çok 48 öğe |
slots[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
slots[].time | metin | evet | desen ^([01]\d|2[0-3]):[0-5]\d$; HH:MM |
slots[].detail | metin | en çok 20 karakter; ör. 40 dk | |
slots[].unavailable | evet/hayır | ||
selected | metin | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
Örnek JSON
json{
"type": "time_strip",
"version": 1,
"slots": [
{
"value": "1000",
"time": "10:00",
"unavailable": true
},
{
"value": "1030",
"time": "10:30",
"detail": "40 dk"
},
{
"value": "1100",
"time": "11:00",
"detail": "40 dk"
},
{
"value": "1130",
"time": "11:30",
"detail": "40 dk"
},
{
"value": "1430",
"time": "14:30",
"detail": "40 dk"
},
{
"value": "1500",
"time": "15:00",
"detail": "40 dk"
}
],
"selected": "1030"
}
Şema: [time_strip.schema.json](/gelistiriciler/semalar/time_strip.schema.json)
Tekli seçim — single_choice#
Etkileşimli: inki_component_action üretir
Tekli seçim (radyo listesi).
Kullanıcı etkileşince sana gelen: select → values = {"value": "options[].value"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | en çok 120 karakter | |
options | nesne dizisi | evet | en az 2 öğe; en çok 10 öğe |
options[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
options[].label | metin | evet | en az 1 karakter; en çok 80 karakter |
options[].detail | metin | en çok 120 karakter | |
selected | metin | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
Örnek JSON
json{
"type": "single_choice",
"version": 1,
"options": [
{
"value": "standart",
"label": "Standart teslimat",
"detail": "2–3 gün · ücretsiz"
},
{
"value": "hizli",
"label": "Hızlı teslimat",
"detail": "Yarın · ₺49"
},
{
"value": "magaza",
"label": "Mağazadan al",
"detail": "Bugün 18:00’den sonra"
}
],
"selected": "hizli"
}
Şema: [single_choice.schema.json](/gelistiriciler/semalar/single_choice.schema.json)
Açılır menü — dropdown#
Etkileşimli: inki_component_action üretir
Açılır menü.
Kullanıcı etkileşince sana gelen: select → values = {"value": "options[].value"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
placeholder | metin | evet | en az 1 karakter; en çok 60 karakter |
options | nesne dizisi | evet | en az 1 öğe; en çok 100 öğe |
options[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
options[].label | metin | evet | en az 1 karakter; en çok 80 karakter |
selected | metin | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir | |
searchable | evet/hayır |
Örnek JSON
json{
"type": "dropdown",
"version": 1,
"placeholder": "İlçe seç",
"options": [
{
"value": "besiktas",
"label": "Beşiktaş"
},
{
"value": "kadikoy",
"label": "Kadıköy"
},
{
"value": "uskudar",
"label": "Üsküdar"
},
{
"value": "sisli",
"label": "Şişli"
}
],
"selected": "kadikoy"
}
Şema: [dropdown.schema.json](/gelistiriciler/semalar/dropdown.schema.json)
Aralık kaydırıcı — range_slider#
Etkileşimli: inki_component_action üretir
Aralık kaydırıcı (iki tutamaç). open_ended_max ise üst uç “6.000+” biçimindedir.
Kullanıcı etkileşince sana gelen: change → values = {"from": "sayı", "to": "sayı"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | evet | en az 1 karakter; en çok 80 karakter |
min | sayı | evet | ≥ -1000000000.0; ≤ 1000000000.0 |
max | sayı | evet | ≥ -1000000000.0; ≤ 1000000000.0 |
step | sayı | ≥ 1e-06; ≤ 1000000000.0 | |
from | sayı | evet | ≥ -1000000000.0; ≤ 1000000000.0 |
to | sayı | evet | ≥ -1000000000.0; ≤ 1000000000.0 |
unit | metin | en çok 8 karakter | |
open_ended_max | evet/hayır |
Örnek JSON
json{
"type": "range_slider",
"version": 1,
"title": "Bütçe",
"min": 0,
"max": 6000,
"step": 100,
"from": 1500,
"to": 4000,
"unit": "₺",
"open_ended_max": true
}
Şema: [range_slider.schema.json](/gelistiriciler/semalar/range_slider.schema.json)
Adet + anahtarlar — stepper_toggles#
Etkileşimli: inki_component_action üretir
Adet + anahtarlar.
Kullanıcı etkileşince sana gelen: change → values = {"steppers[].id | toggles[].id": "yeni değer (sayı | boolean)"}; submit → values = {"action_id": "actions[].action_id"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
steppers | nesne dizisi | en az 0 öğe; en çok 6 öğe | |
steppers[].id | metin | evet | desen ^[a-z][a-z0-9_]{0,31}$; form alanı/grup kimliği; values anahtarı |
steppers[].label | metin | evet | en az 1 karakter; en çok 60 karakter |
steppers[].value | tam sayı | evet | ≥ -1000000; ≤ 1000000 |
steppers[].min | tam sayı | ≥ -1000000; ≤ 1000000 | |
steppers[].max | tam sayı | ≥ -1000000; ≤ 1000000 | |
toggles | nesne dizisi | en az 0 öğe; en çok 10 öğe | |
toggles[].id | metin | evet | desen ^[a-z][a-z0-9_]{0,31}$; form alanı/grup kimliği; values anahtarı |
toggles[].label | metin | evet | en az 1 karakter; en çok 60 karakter |
toggles[].value | evet/hayır | evet | |
actions | nesne dizisi | en az 1 öğe; en çok 2 öğe | |
actions[].action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
actions[].label | metin | evet | en az 1 karakter; en çok 40 karakter |
actions[].style | metin | şunlardan biri: primary, secondary, danger | |
actions[].disabled | evet/hayır |
Örnek JSON
json{
"type": "stepper_toggles",
"version": 1,
"steppers": [
{
"id": "kisi",
"label": "Kişi sayısı",
"value": 4,
"min": 1,
"max": 12
}
],
"toggles": [
{
"id": "bebek_sandalyesi",
"label": "Bebek sandalyesi",
"value": true
},
{
"id": "cam_kenari",
"label": "Cam kenarı",
"value": false
}
]
}
Şema: [stepper_toggles.schema.json](/gelistiriciler/semalar/stepper_toggles.schema.json)
Arayarak seç — search_select#
Etkileşimli: inki_component_action üretir
Arayarak seç. Yazdıkça change{query} gider; bot sonuçları replace_component ile yeniler. İstemci query ile eşleşen öneki vurgular.
Kullanıcı etkileşince sana gelen: change → values = {"query": "yazılan metin"}; select → values = {"value": "results[].value"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
placeholder | metin | en çok 60 karakter | |
query | metin | en çok 100 karakter | |
results | nesne dizisi | evet | en az 0 öğe; en çok 20 öğe |
results[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
results[].label | metin | evet | en az 1 karakter; en çok 120 karakter |
results[].detail | metin | en çok 160 karakter | |
selected | metin | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
Örnek JSON
json{
"type": "search_select",
"version": 1,
"placeholder": "Yer ara",
"query": "ist",
"results": [
{
"value": "ist",
"label": "İstanbul Havalimanı",
"detail": "IST"
},
{
"value": "saw",
"label": "İstanbul Sabiha Gökçen",
"detail": "SAW"
},
{
"value": "istiklal",
"label": "İstiklal Cd.",
"detail": "Beyoğlu"
}
]
}
Şema: [search_select.schema.json](/gelistiriciler/semalar/search_select.schema.json)
Konum seç — location_pick#
Etkileşimli: inki_component_action üretir
Konum seç (harita + sürüklenebilir iğne). Konum yalnız kullanıcı düğmeye basınca bir kez gönderilir.
Kullanıcı etkileşince sana gelen: submit → values = {"latitude": "sayı", "longitude": "sayı"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
latitude | sayı | evet | ≥ -90; ≤ 90 |
longitude | sayı | evet | ≥ -180; ≤ 180 |
hint | metin | en çok 120 karakter | |
button_label | metin | en çok 40 karakter | |
one_time | evet/hayır | “yalnız bu bir kez gönderilir” notu |
Örnek JSON
json{
"type": "location_pick",
"version": 1,
"latitude": 41.0082,
"longitude": 28.9784,
"hint": "Pimi sürükleyerek tam yeri göster",
"button_label": "Bu konumu gönder",
"one_time": true
}
Şema: [location_pick.schema.json](/gelistiriciler/semalar/location_pick.schema.json)
Form ve akış#
Çok adımlı form — multistep_form#
Etkileşimli: inki_component_action üretir
Çok adımlı form; presentation:"page" ise tam sayfa form . İstemci anlık doğrular, sunucu (bot) yeniden doğrular.
Kullanıcı etkileşince sana gelen: change → values = {"steps[].fields[].id": "yeni değer"}; submit → values = {"step": "steps[].id", "direction": "back|next|submit", "<alan id>": "tüm alan değerleri"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | en çok 80 karakter | |
presentation | metin | şunlardan biri: inline, page | |
steps | nesne dizisi | evet | en az 1 öğe; en çok 10 öğe |
steps[].id | metin | evet | desen ^[a-z][a-z0-9_]{0,31}$; form alanı/grup kimliği; values anahtarı |
steps[].title | metin | evet | en az 1 karakter; en çok 80 karakter |
steps[].fields | nesne dizisi | evet | en az 1 öğe; en çok 20 öğe |
steps[].fields[].id | metin | evet | desen ^[a-z][a-z0-9_]{0,31}$; form alanı/grup kimliği; values anahtarı |
steps[].fields[].type | metin | evet | şunlardan biri: text, long_text, number, phone, email, date, time, datetime_range, single_choice, multi_choice, dropdown, slider, stepper, toggle, rating, nps, mood, location, photo, file |
steps[].fields[].label | metin | evet | en az 1 karakter; en çok 60 karakter |
steps[].fields[].required | evet/hayır | ||
steps[].fields[].placeholder | metin | en çok 80 karakter | |
steps[].fields[].hint | metin | en çok 120 karakter | |
steps[].fields[].value | metin | en çok 2000 karakter; geçerli değer (metin/sayı/tarih/saat dizgesi; toggle için "true"/"false") | |
steps[].fields[].values | string dizisi | en az 0 öğe; en çok 20 öğe; multi_choice seçili değerler | |
steps[].fields[].options | nesne dizisi | en az 1 öğe; en çok 30 öğe | |
steps[].fields[].options[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
steps[].fields[].options[].label | metin | evet | en az 1 karakter; en çok 80 karakter |
steps[].fields[].min | sayı | ≥ -1000000000.0; ≤ 1000000000.0 | |
steps[].fields[].max | sayı | ≥ -1000000000.0; ≤ 1000000000.0 | |
steps[].fields[].step | sayı | ≥ 1e-06; ≤ 1000000000.0 | |
steps[].fields[].min_length | tam sayı | ≥ 0; ≤ 4000 | |
steps[].fields[].max_length | tam sayı | ≥ 1; ≤ 4000 | |
steps[].fields[].error | metin | en çok 200 karakter; geçerli doğrulama hatası (bot yeniden gönderince gösterilir) | |
current | tam sayı | ≥ 0; ≤ 9 | |
back_label | metin | en çok 30 karakter | |
next_label | metin | en çok 30 karakter | |
submit_label | metin | en çok 30 karakter |
Örnek JSON
json{
"type": "multistep_form",
"version": 1,
"presentation": "inline",
"current": 1,
"back_label": "Geri",
"next_label": "Devam",
"submit_label": "Gönder",
"steps": [
{
"id": "kisi",
"title": "Kişisel",
"fields": [
{
"id": "ad_soyad",
"type": "text",
"label": "Ad soyad",
"required": true,
"value": "Deniz Kaya"
}
]
},
{
"id": "iletisim",
"title": "İletişim bilgileri",
"fields": [
{
"id": "telefon",
"type": "phone",
"label": "Telefon",
"required": true,
"value": "0532 418 00 00"
},
{
"id": "eposta",
"type": "email",
"label": "E-posta",
"required": true,
"value": "deniz@ornek",
"error": "E-posta eksik görünüyor: @ sonrası alan adı yok"
}
]
},
{
"id": "tercih",
"title": "Tercihler",
"fields": [
{
"id": "bolum",
"type": "single_choice",
"label": "Bölüm",
"options": [
{
"value": "pilates",
"label": "Pilates"
},
{
"value": "yoga",
"label": "Yoga"
}
]
}
]
},
{
"id": "onay",
"title": "Onay",
"fields": [
{
"id": "kvkk",
"type": "toggle",
"label": "Aydınlatma metnini okudum",
"required": true,
"value": "false"
}
]
}
]
}
Şema: [multistep_form.schema.json](/gelistiriciler/semalar/multistep_form.schema.json)
Uzun metin — long_text#
Etkileşimli: inki_component_action üretir
Uzun metin + karakter sayacı.
Kullanıcı etkileşince sana gelen: change → values = {"text": "metin"}; submit → values = {"action_id": "actions[].action_id", "text": "metin"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
label | metin | en çok 60 karakter | |
value | metin | en çok 4000 karakter | |
placeholder | metin | en çok 80 karakter | |
min_length | tam sayı | ≥ 0; ≤ 4000 | |
max_length | tam sayı | evet | ≥ 1; ≤ 4000 |
actions | nesne dizisi | en az 1 öğe; en çok 2 öğe | |
actions[].action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
actions[].label | metin | evet | en az 1 karakter; en çok 40 karakter |
actions[].style | metin | şunlardan biri: primary, secondary, danger | |
actions[].disabled | evet/hayır |
Örnek JSON
json{
"type": "long_text",
"version": 1,
"label": "Ustaya notun",
"value": "Önden kısa, arkada uzun kalsın. Geçen seferki gibi katlı olmasın.",
"max_length": 300,
"actions": [
{
"action_id": "gonder",
"label": "Gönder",
"style": "primary"
}
]
}
Şema: [long_text.schema.json](/gelistiriciler/semalar/long_text.schema.json)
Fotoğraf / dosya yükleme — upload#
Etkileşimli: inki_component_action üretir
Fotoğraf / dosya yükleme. Yüklenen dosyalar bota file_id olarak gider; ilerleme istemcidedir.
Kullanıcı etkileşince sana gelen: submit → values = {"files": "yüklenen file_id dizisi"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | evet | en az 1 karakter; en çok 80 karakter |
accept | string dizisi | evet | en az 1 öğe; en çok 3 öğe |
max_files | tam sayı | evet | ≥ 1; ≤ 10 |
max_size_bytes | tam sayı | ≥ 1; ≤ 52428800 | |
hint | metin | en çok 120 karakter | |
files | nesne dizisi | en az 0 öğe; en çok 10 öğe | |
files[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
files[].name | metin | en çok 120 karakter | |
files[].progress | tam sayı | ≥ 0; ≤ 100 | |
files[].preview | metin | desen ^(https://[^\s\x00-\x1f\x7f]{1,2040}|[A-Za-z0-9_.:-]{8,256})$; medya (photo): botunun aldığı file_id ya da https:// adresi; Telegram sözleşmesi: file_id ya da https URL (sunucu egress ile indirip yeniden barındırır) |
Örnek JSON
json{
"type": "upload",
"version": 1,
"title": "Örnek saç modeli ekle",
"accept": [
"photo"
],
"max_files": 3,
"hint": "En çok 3 fotoğraf · yalnız bu bota gider",
"files": [
{
"value": "model_1",
"progress": 100
},
{
"value": "model_2",
"progress": 62
}
]
}
Şema: [upload.schema.json](/gelistiriciler/semalar/upload.schema.json)
0–10 öneri ölçeği — nps#
Etkileşimli: inki_component_action üretir
0–10 öneri ölçeği.
Kullanıcı etkileşince sana gelen: select → values = {"value": "0..10"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
question | metin | evet | en az 1 karakter; en çok 200 karakter |
low_label | metin | en çok 30 karakter | |
high_label | metin | en çok 30 karakter | |
selected | tam sayı | ≥ 0; ≤ 10 |
Örnek JSON
json{
"type": "nps",
"version": 1,
"question": "Bizi bir arkadaşına önerir misin?",
"low_label": "Hiç",
"high_label": "Kesinlikle",
"selected": 9
}
Şema: [nps.schema.json](/gelistiriciler/semalar/nps.schema.json)
Duygu / puan — mood#
Etkileşimli: inki_component_action üretir
Duygu / puan ölçeği. style:"faces" yüzler (etiketli), "stars" yıldız.
Kullanıcı etkileşince sana gelen: select → values = {"value": "1..scale"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
question | metin | evet | en az 1 karakter; en çok 200 karakter |
style | metin | şunlardan biri: faces, stars | |
scale | tam sayı | evet | ≥ 3; ≤ 7 |
labels | string dizisi | en az 0 öğe; en çok 7 öğe | |
selected | tam sayı | ≥ 1; ≤ 7 |
Örnek JSON
json{
"type": "mood",
"version": 1,
"question": "Bugünkü antrenman nasıldı?",
"style": "faces",
"scale": 5,
"labels": [
"Çok zor",
"Zor",
"İyi",
"Rahat",
"Çok kolay"
],
"selected": 3
}
Şema: [mood.schema.json](/gelistiriciler/semalar/mood.schema.json)
Onay — confirm#
Etkileşimli: inki_component_action üretir
Onay (geri alınamaz işlem). Yıkıcı onayda confirm.style danger olmalı.
Kullanıcı etkileşince sana gelen: submit → values = {"action_id": "confirm.action_id | cancel.action_id"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | evet | en az 1 karakter; en çok 160 karakter |
text | metin | en çok 300 karakter | |
confirm | nesne | evet | basılınca inki_component_action{action:"submit", values:{action_id}} |
confirm.action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
confirm.label | metin | evet | en az 1 karakter; en çok 40 karakter |
confirm.style | metin | şunlardan biri: primary, secondary, danger | |
confirm.disabled | evet/hayır | ||
cancel | nesne | evet | basılınca inki_component_action{action:"submit", values:{action_id}} |
cancel.action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
cancel.label | metin | evet | en az 1 karakter; en çok 40 karakter |
cancel.style | metin | şunlardan biri: primary, secondary, danger | |
cancel.disabled | evet/hayır |
Örnek JSON
json{
"type": "confirm",
"version": 1,
"title": "Perşembe 14:30 randevusu iptal edilsin mi?",
"text": "Saatine 2 saatten az kaldığı için ₺100 iptal ücreti alınır.",
"confirm": {
"action_id": "iptal_et",
"label": "İptal et",
"style": "danger"
},
"cancel": {
"action_id": "vazgec",
"label": "Vazgeç",
"style": "secondary"
}
}
Şema: [confirm.schema.json](/gelistiriciler/semalar/confirm.schema.json)
Geri al şeridi — undo_bar#
Etkileşimli: inki_component_action üretir
Geri al şeridi (geçici). expires_in_seconds sonra şerit kendiliğinden kapanır.
Kullanıcı etkileşince sana gelen: submit → values = {"action_id": "undo.action_id"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
text | metin | evet | en az 1 karakter; en çok 160 karakter |
undo | nesne | evet | basılınca inki_component_action{action:"submit", values:{action_id}} |
undo.action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
undo.label | metin | evet | en az 1 karakter; en çok 40 karakter |
undo.style | metin | şunlardan biri: primary, secondary, danger | |
undo.disabled | evet/hayır | ||
expires_in_seconds | tam sayı | ≥ 3; ≤ 30 |
Örnek JSON
json{
"type": "undo_bar",
"version": 1,
"text": "Sucuklu sepetten çıkarıldı",
"undo": {
"action_id": "geri_al",
"label": "Geri al",
"style": "primary"
},
"expires_in_seconds": 8
}
Şema: [undo_bar.schema.json](/gelistiriciler/semalar/undo_bar.schema.json)
Form özeti — form_summary#
Etkileşimli: inki_component_action üretir
Gönderilen form özeti.
Kullanıcı etkileşince sana gelen: submit → values = {"action_id": "actions[].action_id"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | evet | en az 1 karakter; en çok 80 karakter |
rows | nesne dizisi | evet | en az 1 öğe; en çok 30 öğe |
rows[].label | metin | evet | en az 1 karakter; en çok 60 karakter |
rows[].value | metin | evet | en az 1 karakter; en çok 200 karakter |
actions | nesne dizisi | en az 1 öğe; en çok 2 öğe | |
actions[].action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
actions[].label | metin | evet | en az 1 karakter; en çok 40 karakter |
actions[].style | metin | şunlardan biri: primary, secondary, danger | |
actions[].disabled | evet/hayır |
Örnek JSON
json{
"type": "form_summary",
"version": 1,
"tone": "success",
"title": "Başvurun gönderildi",
"rows": [
{
"label": "Ad",
"value": "Deniz Kaya"
},
{
"label": "Telefon",
"value": "0532 418 ·· ··"
},
{
"label": "Bölüm",
"value": "Pilates · akşam"
}
],
"actions": [
{
"action_id": "duzenle",
"label": "Düzenle",
"style": "secondary"
}
]
}
Şema: [form_summary.schema.json](/gelistiriciler/semalar/form_summary.schema.json)
Canlı ve veri#
Canlı kurye — live_courier#
Canlı güncellenebilir (1/sn)
Canlı kurye takibi. Konum/ETA inkiEditMessageComponent ile yerinde güncellenir (1/sn/bileşen).
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
courier | nesne | evet | |
courier.latitude | sayı | evet | ≥ -90; ≤ 90 |
courier.longitude | sayı | evet | ≥ -180; ≤ 180 |
courier.name | metin | en çok 60 karakter | |
destination | nesne | evet | |
destination.latitude | sayı | evet | ≥ -90; ≤ 90 |
destination.longitude | sayı | evet | ≥ -180; ≤ 180 |
route | nesne dizisi | en az 2 öğe; en çok 200 öğe | |
route[].latitude | sayı | evet | ≥ -90; ≤ 90 |
route[].longitude | sayı | evet | ≥ -180; ≤ 180 |
eta_minutes | tam sayı | evet | ≥ 0; ≤ 1440 |
status_text | metin | en çok 120 karakter | |
phone | metin | desen ^\+?[0-9 ()-]{5,20}$ | |
live | evet/hayır |
Örnek JSON
json{
"type": "live_courier",
"version": 1,
"courier": {
"latitude": 40.9921,
"longitude": 29.023,
"name": "Emre"
},
"destination": {
"latitude": 40.9876,
"longitude": 29.0262
},
"route": [
{
"latitude": 40.995,
"longitude": 29.019
},
{
"latitude": 40.9921,
"longitude": 29.023
},
{
"latitude": 40.9895,
"longitude": 29.0236
},
{
"latitude": 40.9876,
"longitude": 29.0262
}
],
"eta_minutes": 8,
"status_text": "2 durak sonra sen",
"phone": "+90 555 010 20 31",
"live": true
}
Şema: [live_courier.schema.json](/gelistiriciler/semalar/live_courier.schema.json)
Geri sayım — countdown#
Geri sayım; kalan süreyi istemci ends_at'ten hesaplar.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | en çok 120 karakter | |
ends_at | tam sayı | evet | ≥ 0; ≤ 4102444800; Unix saniye (UTC) |
finished_text | metin | en çok 120 karakter |
Örnek JSON
json{
"type": "countdown",
"version": 1,
"title": "Kasım indirimi bitiyor",
"ends_at": 1794614400,
"finished_text": "İndirim sona erdi"
}
Şema: [countdown.schema.json](/gelistiriciler/semalar/countdown.schema.json)
Hedef ilerlemesi — goal_progress#
Etkileşimli: inki_component_action üretirCanlı güncellenebilir (1/sn)
Hedef ilerlemesi; yüzdeyi istemci current/target'ten hesaplar.
Kullanıcı etkileşince sana gelen: submit → values = {"action_id": "actions[].action_id"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | evet | en az 1 karakter; en çok 120 karakter |
current | nesne | evet | tutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar |
current.amount | sayı | evet | ≥ 0; ≤ 1000000000 |
current.currency | metin | evet | şunlardan biri: TRY, INK, USD, EUR |
target | nesne | evet | tutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar |
target.amount | sayı | evet | ≥ 0; ≤ 1000000000 |
target.currency | metin | evet | şunlardan biri: TRY, INK, USD, EUR |
backers | tam sayı | ≥ 0; ≤ 100000000 | |
ends_at | tam sayı | ≥ 0; ≤ 4102444800; Unix saniye (UTC) | |
actions | nesne dizisi | en az 1 öğe; en çok 2 öğe | |
actions[].action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
actions[].label | metin | evet | en az 1 karakter; en çok 40 karakter |
actions[].style | metin | şunlardan biri: primary, secondary, danger | |
actions[].disabled | evet/hayır |
Örnek JSON
json{
"type": "goal_progress",
"version": 1,
"title": "Köy okuluna kitap",
"current": {
"amount": 34000,
"currency": "TRY"
},
"target": {
"amount": 50000,
"currency": "TRY"
},
"backers": 412,
"ends_at": 1795208400,
"actions": [
{
"action_id": "destek_ol",
"label": "Destek ol",
"style": "primary"
}
]
}
Şema: [goal_progress.schema.json](/gelistiriciler/semalar/goal_progress.schema.json)
Canlı anket — live_poll#
Etkileşimli: inki_component_action üretirCanlı güncellenebilir (1/sn)
Canlı anket sonucu; yüzdeleri istemci votes/total_votes'tan hesaplar.
Kullanıcı etkileşince sana gelen: select → values = {"value": "options[].value"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
question | metin | evet | en az 1 karakter; en çok 200 karakter |
options | nesne dizisi | evet | en az 2 öğe; en çok 10 öğe |
options[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
options[].label | metin | evet | en az 1 karakter; en çok 80 karakter |
options[].votes | tam sayı | evet | ≥ 0; ≤ 100000000 |
total_votes | tam sayı | evet | ≥ 0; ≤ 100000000 |
selected | metin | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir | |
closed | evet/hayır | ||
live | evet/hayır |
Örnek JSON
json{
"type": "live_poll",
"version": 1,
"question": "Cumartesi hangi rota?",
"options": [
{
"value": "belgrad",
"label": "Belgrad Ormanı",
"votes": 68
},
{
"value": "sahil",
"label": "Sahil yolu",
"votes": 39
},
{
"value": "adalar",
"label": "Adalar",
"votes": 19
}
],
"total_votes": 126,
"selected": "belgrad",
"live": true
}
Şema: [live_poll.schema.json](/gelistiriciler/semalar/live_poll.schema.json)
Çizgi grafik — line_chart#
Çizgi grafik; eksen etiketleri eşit aralıkla yayılır.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | en çok 80 karakter | |
current | nesne | tutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar | |
current.amount | sayı | evet | ≥ 0; ≤ 1000000000 |
current.currency | metin | evet | şunlardan biri: TRY, INK, USD, EUR |
change_percent | sayı | ≥ -100000; ≤ 100000 | |
points | number dizisi | evet | en az 2 öğe; en çok 366 öğe |
x_labels | string dizisi | en az 0 öğe; en çok 12 öğe |
Örnek JSON
json{
"type": "line_chart",
"version": 1,
"title": "Bu ay harcaman",
"current": {
"amount": 8420,
"currency": "TRY"
},
"change_percent": 18,
"points": [
3200,
4575,
3843,
5490,
5033,
7137,
6405,
8420
],
"x_labels": [
"1",
"5",
"10",
"15",
"20",
"25",
"30"
]
}
Şema: [line_chart.schema.json](/gelistiriciler/semalar/line_chart.schema.json)
Metrik kutuları — metric_tiles#
Metrik kutuları.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
tiles | nesne dizisi | evet | en az 1 öğe; en çok 6 öğe |
tiles[].value | metin | evet | en az 1 karakter; en çok 16 karakter |
tiles[].label | metin | evet | en az 1 karakter; en çok 30 karakter |
tiles[].brand_color | metin | şunlardan biri: mavi, turuncu, mor, pembe, altin, yesil, turkuaz |
Örnek JSON
json{
"type": "metric_tiles",
"version": 1,
"tiles": [
{
"value": "7.240",
"label": "adım",
"brand_color": "turuncu"
},
{
"value": "412",
"label": "kalori",
"brand_color": "pembe"
},
{
"value": "6,4 sa",
"label": "uyku",
"brand_color": "mor"
}
]
}
Şema: [metric_tiles.schema.json](/gelistiriciler/semalar/metric_tiles.schema.json)
Canlı skor — live_score#
Canlı güncellenebilir (1/sn)
Canlı skor.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
competition | metin | en çok 60 karakter | |
state | metin | evet | şunlardan biri: scheduled, live, finished |
minute | tam sayı | ≥ 0; ≤ 150 | |
home | nesne | evet | |
home.name | metin | evet | en az 1 karakter; en çok 40 karakter |
home.score | tam sayı | evet | ≥ 0; ≤ 999 |
home.logo | metin | desen ^(https://[^\s\x00-\x1f\x7f]{1,2040}|[A-Za-z0-9_.:-]{8,256})$; medya (photo): botunun aldığı file_id ya da https:// adresi; Telegram sözleşmesi: file_id ya da https URL (sunucu egress ile indirip yeniden barındırır) | |
home.brand_color | metin | şunlardan biri: mavi, turuncu, mor, pembe, altin, yesil, turkuaz | |
away | nesne | evet | |
away.name | metin | evet | en az 1 karakter; en çok 40 karakter |
away.score | tam sayı | evet | ≥ 0; ≤ 999 |
away.logo | metin | desen ^(https://[^\s\x00-\x1f\x7f]{1,2040}|[A-Za-z0-9_.:-]{8,256})$; medya (photo): botunun aldığı file_id ya da https:// adresi; Telegram sözleşmesi: file_id ya da https URL (sunucu egress ile indirip yeniden barındırır) | |
away.brand_color | metin | şunlardan biri: mavi, turuncu, mor, pembe, altin, yesil, turkuaz | |
events | nesne dizisi | en az 0 öğe; en çok 10 öğe | |
events[].minute | tam sayı | ≥ 0; ≤ 150 | |
events[].text | metin | evet | en az 1 karakter; en çok 120 karakter |
Örnek JSON
json{
"type": "live_score",
"version": 1,
"competition": "Süper Lig",
"state": "live",
"minute": 67,
"home": {
"name": "Moda SK",
"score": 2,
"brand_color": "altin"
},
"away": {
"name": "Kartal FK",
"score": 1,
"brand_color": "mavi"
},
"events": [
{
"minute": 64,
"text": "Gol: Arda (Moda SK)"
}
]
}
Şema: [live_score.schema.json](/gelistiriciler/semalar/live_score.schema.json)
Saatlik hava — hourly_weather#
Saatlik hava; ikon seçimi condition enumundan istemcide.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
location | metin | evet | en az 1 karakter; en çok 80 karakter |
temperature | tam sayı | ≥ -90; ≤ 70 | |
unit | metin | şunlardan biri: celsius, fahrenheit | |
summary | metin | en çok 80 karakter | |
hours | nesne dizisi | evet | en az 1 öğe; en çok 24 öğe |
hours[].label | metin | evet | en az 1 karakter; en çok 12 karakter |
hours[].temperature | tam sayı | evet | ≥ -90; ≤ 70 |
hours[].condition | metin | evet | şunlardan biri: clear, partly_cloudy, cloudy, rain, storm, snow, fog, wind |
Örnek JSON
json{
"type": "hourly_weather",
"version": 1,
"location": "Kadıköy",
"temperature": 14,
"unit": "celsius",
"summary": "Akşam yağmurlu",
"hours": [
{
"label": "Şimdi",
"temperature": 14,
"condition": "clear"
},
{
"label": "15",
"temperature": 15,
"condition": "clear"
},
{
"label": "17",
"temperature": 13,
"condition": "rain"
},
{
"label": "19",
"temperature": 11,
"condition": "rain"
},
{
"label": "21",
"temperature": 10,
"condition": "clear"
}
]
}
Şema: [hourly_weather.schema.json](/gelistiriciler/semalar/hourly_weather.schema.json)
Etkileşim ve oyun#
Yarışma sorusu — quiz_question#
Etkileşimli: inki_component_action üretir
Bilgi yarışması sorusu. Şık harflerini (A, B…) istemci sıraya göre üretir.
Kullanıcı etkileşince sana gelen: select → values = {"value": "options[].value"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
index | tam sayı | ≥ 1; ≤ 999 | |
total | tam sayı | ≥ 1; ≤ 999 | |
question | metin | evet | en az 1 karakter; en çok 300 karakter |
options | nesne dizisi | evet | en az 2 öğe; en çok 6 öğe |
options[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
options[].label | metin | evet | en az 1 karakter; en çok 120 karakter |
time_limit_seconds | tam sayı | ≥ 1; ≤ 3600 | |
remaining_seconds | tam sayı | ≥ 0; ≤ 3600 | |
selected | metin | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
Örnek JSON
json{
"type": "quiz_question",
"version": 1,
"index": 3,
"total": 10,
"question": "“Ephemeral” kelimesinin anlamı?",
"options": [
{
"value": "a",
"label": "Kalıcı"
},
{
"value": "b",
"label": "Geçici"
},
{
"value": "c",
"label": "Görünmez"
},
{
"value": "d",
"label": "Değerli"
}
],
"time_limit_seconds": 20,
"remaining_seconds": 7,
"selected": "b"
}
Şema: [quiz_question.schema.json](/gelistiriciler/semalar/quiz_question.schema.json)
Yarışma sonucu — quiz_result#
Yarışma sonucu.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
options | nesne dizisi | evet | en az 1 öğe; en çok 6 öğe |
options[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
options[].label | metin | evet | en az 1 karakter; en çok 120 karakter |
options[].state | metin | evet | şunlardan biri: correct, wrong, neutral |
correct_count | tam sayı | evet | ≥ 0; ≤ 999 |
total | tam sayı | evet | ≥ 1; ≤ 999 |
points | tam sayı | ≥ 0; ≤ 100000000 | |
rank | tam sayı | ≥ 1; ≤ 100000000 | |
rank_period | metin | şunlardan biri: daily, weekly, monthly, all_time |
Örnek JSON
json{
"type": "quiz_result",
"version": 1,
"options": [
{
"value": "b",
"label": "Geçici",
"state": "correct"
},
{
"value": "a",
"label": "Kalıcı",
"state": "wrong"
}
],
"correct_count": 8,
"total": 10,
"points": 1240,
"rank": 14,
"rank_period": "weekly"
}
Şema: [quiz_result.schema.json](/gelistiriciler/semalar/quiz_result.schema.json)
Hızlı yanıtlar — quick_replies#
Etkileşimli: inki_component_action üretir
Hızlı yanıtlar (mesaj altı çipler). Seçilince çipler kaybolur.
Kullanıcı etkileşince sana gelen: select → values = {"value": "replies[].value"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
prompt | metin | en çok 300 karakter | |
replies | nesne dizisi | evet | en az 1 öğe; en çok 12 öğe |
replies[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
replies[].label | metin | evet | en az 1 karakter; en çok 40 karakter |
Örnek JSON
json{
"type": "quick_replies",
"version": 1,
"prompt": "Siparişinle ilgili ne yapmak istersin?",
"replies": [
{
"value": "nerede",
"label": "Nerede?"
},
{
"value": "adres",
"label": "Adresi değiştir"
},
{
"value": "iptal",
"label": "İptal et"
},
{
"value": "insan",
"label": "Biriyle konuş"
}
]
}
Şema: [quick_replies.schema.json](/gelistiriciler/semalar/quick_replies.schema.json)
Sekmeli menü — tabbed_menu#
Etkileşimli: inki_component_action üretir
Sekmeli menü. Sekme geçişi yereldir (içerik bileşende); öğe seçimi select gönderir.
Kullanıcı etkileşince sana gelen: select → values = {"value": "tabs[].items[].value"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
tabs | nesne dizisi | evet | en az 1 öğe; en çok 8 öğe |
tabs[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
tabs[].label | metin | evet | en az 1 karakter; en çok 30 karakter |
tabs[].items | nesne dizisi | evet | en az 0 öğe; en çok 30 öğe |
tabs[].items[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
tabs[].items[].name | metin | evet | en az 1 karakter; en çok 80 karakter |
tabs[].items[].description | metin | en çok 160 karakter | |
tabs[].items[].price | nesne | tutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar | |
tabs[].items[].price.amount | sayı | evet | ≥ 0; ≤ 1000000000 |
tabs[].items[].price.currency | metin | evet | şunlardan biri: TRY, INK, USD, EUR |
tabs[].items[].image | metin | desen ^(https://[^\s\x00-\x1f\x7f]{1,2040}|[A-Za-z0-9_.:-]{8,256})$; medya (photo): botunun aldığı file_id ya da https:// adresi; Telegram sözleşmesi: file_id ya da https URL (sunucu egress ile indirip yeniden barındırır) | |
tabs[].items[].brand_color | metin | şunlardan biri: mavi, turuncu, mor, pembe, altin, yesil, turkuaz | |
active_tab | metin | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
Örnek JSON
json{
"type": "tabbed_menu",
"version": 1,
"active_tab": "pizza",
"tabs": [
{
"value": "pizza",
"label": "Pizzalar",
"items": [
{
"value": "margarita",
"name": "Margarita",
"description": "Domates, mozzarella, fesleğen",
"price": {
"amount": 240,
"currency": "TRY"
},
"brand_color": "pembe"
},
{
"value": "dort_peynir",
"name": "Dört peynirli",
"description": "Gorgonzola, parmesan, kaşar",
"price": {
"amount": 310,
"currency": "TRY"
},
"brand_color": "pembe"
}
]
},
{
"value": "tatli",
"label": "Tatlılar",
"items": [
{
"value": "tiramisu",
"name": "Tiramisu",
"price": {
"amount": 120,
"currency": "TRY"
}
}
]
},
{
"value": "icecek",
"label": "İçecek",
"items": [
{
"value": "ayran",
"name": "Ayran",
"price": {
"amount": 35,
"currency": "TRY"
}
}
]
}
]
}
Şema: [tabbed_menu.schema.json](/gelistiriciler/semalar/tabbed_menu.schema.json)
Takvime ekle / hatırlat — damla_link#
Damla’ya bağla: etkinlik takvime eklenir / Damla hatırlatır (istemci yerel; kullanıcı izniyle, bota veri gitmez).
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | evet | en az 1 karakter; en çok 120 karakter |
starts_at | tam sayı | evet | ≥ 0; ≤ 4102444800; Unix saniye (UTC) |
ends_at | tam sayı | ≥ 0; ≤ 4102444800; Unix saniye (UTC) | |
location | metin | en çok 120 karakter | |
buttons | string dizisi | evet | en az 1 öğe; en çok 2 öğe |
Örnek JSON
json{
"type": "damla_link",
"version": 1,
"title": "Per 13 Kas · 14:30 kesim",
"starts_at": 1794569400,
"ends_at": 1794571800,
"location": "Saç Stüdyosu, Moda",
"buttons": [
"add_to_calendar",
"remind"
]
}
Şema: [damla_link.schema.json](/gelistiriciler/semalar/damla_link.schema.json)
Davet / paylaş — invite#
Davet / paylaş. Paylaşım kullanıcının sohbetlerine istemciden gider (bota gitmez).
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | evet | en az 1 karakter; en çok 120 karakter |
text | metin | en çok 300 karakter | |
link | metin | evet | desen ^https://[^\s\x00-\x1f\x7f]{1,2040}$ |
share_label | metin | en çok 40 karakter |
Örnek JSON
json{
"type": "invite",
"version": 1,
"brand_color": "pembe",
"title": "Arkadaşını getir, ikiniz de kazanın",
"text": "Davet ettiğin her kişi ilk kesimde ₺100 indirim alır, sen de 50 Ink.",
"link": "https://app.inkiveta.com/b/sacstudyosu?d=deniz",
"share_label": "Sohbetlerimden gönder"
}
Şema: [invite.schema.json](/gelistiriciler/semalar/invite.schema.json)
Çekiliş — giveaway#
Etkileşimli: inki_component_action üretir
Çekiliş / katılım.
Kullanıcı etkileşince sana gelen: submit → values = {"action_id": "actions[].action_id"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | evet | en az 1 karakter; en çok 120 karakter |
ends_at | tam sayı | ≥ 0; ≤ 4102444800; Unix saniye (UTC) | |
participant_count | tam sayı | ≥ 0; ≤ 100000000 | |
participants_preview | nesne dizisi | en az 0 öğe; en çok 5 öğe | |
participants_preview[].initial | metin | evet | en az 1 karakter; en çok 2 karakter |
participants_preview[].brand_color | metin | şunlardan biri: mavi, turuncu, mor, pembe, altin, yesil, turkuaz | |
joined | evet/hayır | ||
actions | nesne dizisi | evet | en az 1 öğe; en çok 1 öğe |
actions[].action_id | metin | evet | desen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir |
actions[].label | metin | evet | en az 1 karakter; en çok 40 karakter |
actions[].style | metin | şunlardan biri: primary, secondary, danger | |
actions[].disabled | evet/hayır |
Örnek JSON
json{
"type": "giveaway",
"version": 1,
"tone": "brand",
"title": "1 yıllık ücretsiz kesim",
"ends_at": 1794657600,
"participant_count": 2381,
"participants_preview": [
{
"initial": "A",
"brand_color": "mavi"
},
{
"initial": "E",
"brand_color": "pembe"
},
{
"initial": "Z",
"brand_color": "yesil"
}
],
"actions": [
{
"action_id": "katil",
"label": "Katıl",
"style": "primary"
}
]
}
Şema: [giveaway.schema.json](/gelistiriciler/semalar/giveaway.schema.json)
Sıralama tablosu — leaderboard#
Sıralama tablosu.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
title | metin | en çok 80 karakter | |
unit | metin | en çok 16 karakter | |
entries | nesne dizisi | evet | en az 1 öğe; en çok 50 öğe |
entries[].rank | tam sayı | evet | ≥ 1; ≤ 100000000 |
entries[].name | metin | evet | en az 1 karakter; en çok 60 karakter |
entries[].score | sayı | evet | ≥ -1000000000000.0; ≤ 1000000000000.0 |
entries[].is_you | evet/hayır | ||
entries[].avatar | metin | desen ^(https://[^\s\x00-\x1f\x7f]{1,2040}|[A-Za-z0-9_.:-]{8,256})$; medya (photo): botunun aldığı file_id ya da https:// adresi; Telegram sözleşmesi: file_id ya da https URL (sunucu egress ile indirip yeniden barındırır) | |
entries[].brand_color | metin | şunlardan biri: mavi, turuncu, mor, pembe, altin, yesil, turkuaz |
Örnek JSON
json{
"type": "leaderboard",
"version": 1,
"title": "Haftalık sıralama",
"unit": "puan",
"entries": [
{
"rank": 1,
"name": "Ece",
"score": 2940
},
{
"rank": 2,
"name": "Kaan",
"score": 2610
},
{
"rank": 3,
"name": "Selin",
"score": 2115
},
{
"rank": 14,
"name": "Sen",
"score": 1240,
"is_you": true
}
]
}
Şema: [leaderboard.schema.json](/gelistiriciler/semalar/leaderboard.schema.json)
Oda çerçevesi#
Uygulama ana sayfası — home_page#
inkiSetHomePage ile gönderilirEtkileşimli: inki_component_action üretir
Bot ana sayfası (inkiSetHomePage): karşılama, hızlı karolar, bölümler.
Kullanıcı etkileşince sana gelen: select → values = {"value": "greeting.suggestions[].value | tiles[].value | sections[].cards[].value"}. 10 saniye içinde [inkiAnswerComponentAction](/gelistiriciler/bilesenler#etkilesime-yanit-vermek) ile yanıtla.
| Alan | Tür | Zorunlu | Kurallar / açıklama |
|---|---|---|---|
greeting | nesne | evet | |
greeting.title | metin | evet | en az 1 karakter; en çok 80 karakter |
greeting.text | metin | en çok 200 karakter | |
greeting.suggestions | nesne dizisi | en az 0 öğe; en çok 8 öğe | |
greeting.suggestions[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
greeting.suggestions[].label | metin | evet | en az 1 karakter; en çok 20 karakter |
tiles | nesne dizisi | en az 0 öğe; en çok 6 öğe | |
tiles[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
tiles[].title | metin | evet | en az 1 karakter; en çok 40 karakter |
tiles[].subtitle | metin | en çok 60 karakter | |
tiles[].icon | metin | şunlardan biri: calendar, tag, clock, location, cart, chat, phone, info, star, gift, ticket, document, heart, user, settings, search | |
tiles[].brand_color | metin | şunlardan biri: mavi, turuncu, mor, pembe, altin, yesil, turkuaz | |
sections | nesne dizisi | en az 0 öğe; en çok 4 öğe | |
sections[].title | metin | evet | en az 1 karakter; en çok 60 karakter |
sections[].cards | nesne dizisi | evet | en az 1 öğe; en çok 5 öğe |
sections[].cards[].value | metin | evet | desen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir |
sections[].cards[].title | metin | evet | en az 1 karakter; en çok 80 karakter |
sections[].cards[].subtitle | metin | en çok 120 karakter | |
sections[].cards[].date | metin | desen ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$; YYYY-MM-DD | |
sections[].cards[].action_label | metin | en çok 30 karakter |
Örnek JSON
json{
"type": "home_page",
"version": 1,
"brand_color": "turuncu",
"greeting": {
"title": "Merhaba Deniz",
"text": "Bugün 3 boş saatimiz var. Sıra şu an kısa.",
"suggestions": [
{
"value": "s1130",
"label": "11:30"
},
{
"value": "s1430",
"label": "14:30"
},
{
"value": "s1700",
"label": "17:00"
}
]
},
"tiles": [
{
"value": "randevu",
"title": "Randevu al",
"subtitle": "Boş saatleri gör",
"icon": "calendar",
"brand_color": "turuncu"
},
{
"value": "hizmetler",
"title": "Hizmetler",
"subtitle": "Kesim ₺450’den",
"icon": "tag",
"brand_color": "pembe"
},
{
"value": "sira",
"title": "Sıra durumu",
"subtitle": "Önünde 2 kişi",
"icon": "clock",
"brand_color": "mavi"
},
{
"value": "yol",
"title": "Yol tarifi",
"subtitle": "1,2 km · 15 dk",
"icon": "location",
"brand_color": "turkuaz"
}
],
"sections": [
{
"title": "Yaklaşan randevun",
"cards": [
{
"value": "rdv_1",
"title": "14:30 · Kesim + fön",
"subtitle": "Usta: Mert · 40 dakika",
"date": "2026-11-13",
"action_label": "Değiştir"
}
]
}
]
}
Şema: [home_page.schema.json](/gelistiriciler/semalar/home_page.schema.json)