Geliştirici paneli inkiveta.com

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"
}'
ParametreZorunluAçıklama
chat_idevetKullanıcının sohbet kimliği
componentevetBileşen nesnesi: type, version (şimdilik hep 1) ve türe özel alanlar
fallback_textevetBileşeni tanımayan eski uygulama sürümlerinde gösterilen düz metin (≤ 4.096)
reply_markupAltına satır içi düğmeler
inki_importancenormal 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_contentNormal 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üphaneHam çağrı
python-telegram-botawait context.bot.do_api_request("inkiSendComponent", api_kwargs={...})
aiogramkendi TelegramMethod alt sınıfını yaz ya da aiohttp ile doğrudan POST et
Telegrafawait ctx.telegram.callApi("inkiSendComponent", {...})
grammYawait bot.api.raw.inkiSendComponent({...}) (TypeScript'te as any)
DiğerPOST 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 · brand
  • brand_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_id ya da https:// 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ı — values boş, yanıt beklenmez).
  • Her bileşenin hangi values gönderdiği aşağıdaki katalogda "Kullanıcı etkileşince sana gelen" satırında yazılı.
  • 10 saniye içinde ve bir kez inkiAnswerComponentAction ile yanıtla:
ParametreAçıklama
component_action_idUpdate'teki id (zorunlu)
toastKısa bildirim (≤ 200 karakter)
close_sheettrue ise açık form/sayfayı kapatır
replace_componentMesajdaki bileşeni bununla değiştirir (ör. seçilen günün dolu saatlerini göster)
fallback_textreplace_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 *.example adresleri ve file_id değerleri yer tutucudur. Göndermeden önce kendi görselinin https:// adresini ya da uygulamanın aldığı bir file_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.

AlanTürZorunluKurallar / açıklama
titlemetinen çok 120 karakter
blocksnesne dizisieveten az 1 öğe; en çok 100 öğe
blocks[].kindmetinevetşunlardan biri: heading, paragraph, list, quote, code, math, divider, footer
blocks[].textmetinen çok 4096 karakter; heading/quote/code/math/footer düz metni (math: LaTeX kaynağı)
blocks[].runsnesne dizisien 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[].textmetineveten az 1 karakter; en çok 1000 karakter
blocks[].runs[].marksstring dizisien az 0 öğe; en çok 9 öğe
blocks[].runs[].urlmetindesen ^https://[^\s\x00-\x1f\x7f]{1,2040}$
blocks[].runs[].footnotemetinen çok 500 karakter; dipnot metni (Telegram RichTextReference eşlemesi)
blocks[].itemsnesne dizisien az 1 öğe; en çok 50 öğe
blocks[].items[].runsnesne dizisieveten az 1 öğe; en çok 50 öğe
blocks[].items[].runs[].textmetineveten az 1 karakter; en çok 1000 karakter
blocks[].items[].runs[].marksstring dizisien az 0 öğe; en çok 9 öğe
blocks[].items[].runs[].urlmetindesen ^https://[^\s\x00-\x1f\x7f]{1,2040}$
blocks[].items[].runs[].footnotemetinen çok 500 karakter; dipnot metni (Telegram RichTextReference eşlemesi)
blocks[].orderedevet/hayır
blocks[].leveltam sayı≥ 1; ≤ 3; heading düzeyi
blocks[].languagemetinen çok 32 karakter; code bloğu dili
blocks[].anchormetindesen ^[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ı.

AlanTürZorunluKurallar / açıklama
titlemetinen çok 80 karakter
textmetineveten 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.

AlanTürZorunluKurallar / açıklama
titlemetinen çok 80 karakter
rowsnesne dizisieveten az 1 öğe; en çok 50 öğe
rows[].labelmetineveten az 1 karakter; en çok 60 karakter
rows[].valuemetineveten az 1 karakter; en çok 200 karakter
rows[].tonemetinşunlardan biri: neutral, success, warning, danger, brand
actionsnesne dizisien az 1 öğe; en çok 3 öğe
actions[].action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
actions[].labelmetineveten az 1 karakter; en çok 40 karakter
actions[].stylemetinşunlardan biri: primary, secondary, danger
actions[].disabledevet/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).

AlanTürZorunluKurallar / açıklama
titlemetinen çok 80 karakter
columnsnesne dizisieveten az 1 öğe; en çok 8 öğe
columns[].labelmetineveten çok 60 karakter
columns[].alignmetinşunlardan biri: start, center, end
columns[].highlightevet/hayırsütun vurgulu (ör. önerilen plan)
rowsarray dizisieveten az 1 öğe; en çok 50 öğe
captionmetinen ç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.

AlanTürZorunluKurallar / açıklama
titlemetinen çok 80 karakter
itemsnesne dizisieveten az 1 öğe; en çok 30 öğe
items[].idmetinevetdesen ^[a-z][a-z0-9_]{0,31}$; form alanı/grup kimliği; values anahtarı
items[].questionmetineveten az 1 karakter; en çok 200 karakter
items[].answermetineveten az 1 karakter; en çok 2000 karakter
items[].openevet/hayırbaşlangıçta açık
allow_multipleevet/hayırbirden 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.).

AlanTürZorunluKurallar / açıklama
titlemetinen çok 80 karakter
eventsnesne dizisieveten az 1 öğe; en çok 40 öğe
events[].timemetinen çok 20 karakter
events[].textmetineveten az 1 karakter; en çok 300 karakter
events[].statemetinevetş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.

AlanTürZorunluKurallar / açıklama
titlemetinen çok 80 karakter
subtitlemetinen çok 200 karakter
modemetinşunlardan biri: instructions, progress
stepsnesne dizisieveten az 1 öğe; en çok 20 öğe
steps[].textmetineveten az 1 karakter; en çok 300 karakter
steps[].detailmetinen çok 300 karakter
currenttam sayı≥ 0; ≤ 19; progress modunda geçerli adım (0'dan)
liveevet/hayırcanlı rozeti; güncellemeler inkiEditMessageComponent ile
actionsnesne dizisien az 1 öğe; en çok 3 öğe
actions[].action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
actions[].labelmetineveten az 1 karakter; en çok 40 karakter
actions[].stylemetinşunlardan biri: primary, secondary, danger
actions[].disabledevet/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.

AlanTürZorunluKurallar / açıklama
titlemetineveten az 1 karakter; en çok 120 karakter
textmetineveten az 1 karakter; en çok 500 karakter
riskmetinevetşunlardan biri: code_request, password_request, card_request, payment_request, unverified_bot
actionsnesne dizisieveten az 1 öğe; en çok 3 öğe
actions[].action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
actions[].labelmetineveten az 1 karakter; en çok 40 karakter
actions[].stylemetinşunlardan biri: primary, secondary, danger
actions[].disabledevet/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.

AlanTürZorunluKurallar / açıklama
imagemetinevetdesen ^(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)
altmetinen çok 200 karakter
titlemetinen çok 120 karakter
textmetinen çok 500 karakter
actionsnesne dizisien az 1 öğe; en çok 3 öğe
actions[].action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
actions[].labelmetineveten az 1 karakter; en çok 40 karakter
actions[].stylemetinşunlardan biri: primary, secondary, danger
actions[].disabledevet/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 (kolaj). total_count > görüntü sayısı ise son karoda “+N” gösterilir; dokunma tam ekran görüntüleyiciyi açar (yerel).

AlanTürZorunluKurallar / açıklama
imagesstring dizisieveten az 1 öğe; en çok 10 öğe
total_counttam sayı≥ 1; ≤ 9999
captionmetinen ç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).

AlanTürZorunluKurallar / açıklama
sourcemetinevetdesen ^(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)
postermetindesen ^(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_secondstam sayı≥ 0; ≤ 86400
titlemetinen çok 120 karakter
animationevet/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.

AlanTürZorunluKurallar / açıklama
sourcemetinevetdesen ^(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)
titlemetineveten az 1 karakter; en çok 120 karakter
duration_secondstam sayıevet≥ 0; ≤ 86400
position_secondstam sayı≥ 0; ≤ 86400
waveforminteger dizisien az 1 öğe; en çok 128 öğe
kindmetinş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).

AlanTürZorunluKurallar / açıklama
latitudesayıevet≥ -90; ≤ 90
longitudesayıevet≥ -180; ≤ 180
titlemetinen çok 120 karakter
addressmetinen ç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.

AlanTürZorunluKurallar / açıklama
codemetineveten az 1 karakter; en çok 1024 karakter
titlemetineveten az 1 karakter; en çok 120 karakter
badgemetinen çok 40 karakter
detailsstring dizisien az 0 öğe; en çok 4 öğe
hintmetinen ç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).

AlanTürZorunluKurallar / açıklama
filemetinevetdesen ^(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_namemetineveten az 1 karakter; en çok 200 karakter
size_bytestam sayı≥ 0; ≤ 52428800
pagestam sayı≥ 1; ≤ 100000
mime_typemetindesen ^[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).

AlanTürZorunluKurallar / açıklama
namemetineveten az 1 karakter; en çok 80 karakter
subtitlemetinen çok 120 karakter
avatarmetindesen ^(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)
phonemetindesen ^\+?[0-9 ()-]{5,20}$
emailmetindesen ^[^@\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.

AlanTürZorunluKurallar / açıklama
layoutmetinşunlardan biri: grid, carousel
itemsnesne dizisieveten az 1 öğe; en çok 30 öğe
items[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
items[].namemetineveten az 1 karakter; en çok 80 karakter
items[].pricenesnetutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar
items[].price.amountsayıevet≥ 0; ≤ 1000000000
items[].price.currencymetinevetşunlardan biri: TRY, INK, USD, EUR
items[].subtitlemetinen çok 120 karakter
items[].metametinen çok 40 karakter
items[].imagemetindesen ^(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_colormetinşunlardan biri: mavi, turuncu, mor, pembe, altin, yesil, turkuaz
items[].quantitytam sayı≥ 0; ≤ 99; sepetteki adet
items[].badgemetinen çok 30 karakter
items[].unavailableevet/hayır
items[].cta_labelmetinen ç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.

AlanTürZorunluKurallar / açıklama
linesnesne dizisieveten az 1 öğe; en çok 50 öğe
lines[].idmetinevetdesen ^[a-z][a-z0-9_]{0,31}$; form alanı/grup kimliği; values anahtarı
lines[].namemetineveten az 1 karakter; en çok 80 karakter
lines[].unit_pricenesneevettutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar
lines[].unit_price.amountsayıevet≥ 0; ≤ 1000000000
lines[].unit_price.currencymetinevetşunlardan biri: TRY, INK, USD, EUR
lines[].quantitytam sayıevet≥ 0; ≤ 99
lines[].max_quantitytam sayı≥ 1; ≤ 99
totalnesneevettutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar
total.amountsayıevet≥ 0; ≤ 1000000000
total.currencymetinevetşunlardan biri: TRY, INK, USD, EUR
actionsnesne dizisien az 1 öğe; en çok 3 öğe
actions[].action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
actions[].labelmetineveten az 1 karakter; en çok 40 karakter
actions[].stylemetinşunlardan biri: primary, secondary, danger
actions[].disabledevet/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.

AlanTürZorunluKurallar / açıklama
titlemetinen çok 80 karakter
groupsnesne dizisieveten az 1 öğe; en çok 6 öğe
groups[].idmetinevetdesen ^[a-z][a-z0-9_]{0,31}$; form alanı/grup kimliği; values anahtarı
groups[].labelmetineveten az 1 karakter; en çok 60 karakter
groups[].kindmetinşunlardan biri: chips, swatches, checklist
groups[].multipleevet/hayır
groups[].optionsnesne dizisieveten az 1 öğe; en çok 30 öğe
groups[].options[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
groups[].options[].labelmetineveten az 1 karakter; en çok 40 karakter
groups[].options[].swatchmetindesen ^#[0-9A-Fa-f]{6}$; ürün rengi (#RRGGBB)
groups[].options[].detailmetinen çok 60 karakter; ör. +₺150
groups[].options[].unavailableevet/hayır
groups[].selectedstring dizisien az 0 öğe; en çok 30 öğe
actionsnesne dizisien az 1 öğe; en çok 3 öğe
actions[].action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
actions[].labelmetineveten az 1 karakter; en çok 40 karakter
actions[].stylemetinşunlardan biri: primary, secondary, danger
actions[].disabledevet/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.

AlanTürZorunluKurallar / açıklama
plansnesne dizisieveten az 1 öğe; en çok 6 öğe
plans[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
plans[].namemetineveten az 1 karakter; en çok 40 karakter
plans[].pricenesneevettutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar
plans[].price.amountsayıevet≥ 0; ≤ 1000000000
plans[].price.currencymetinevetşunlardan biri: TRY, INK, USD, EUR
plans[].periodmetinşunlardan biri: week, month, year
plans[].featuresstring dizisien az 0 öğe; en çok 8 öğe
plans[].recommendedevet/hayır
plans[].cta_labelmetinen ç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.

AlanTürZorunluKurallar / açıklama
codemetineveten az 1 karakter; en çok 32 karakter
discountnesneevet
discount.kindmetinevetşunlardan biri: percent, amount
discount.valuesayıevet≥ 0; ≤ 1000000000
discount.currencymetinşunlardan biri: TRY, INK, USD, EUR
titlemetinen çok 80 karakter
min_spendnesnetutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar
min_spend.amountsayıevet≥ 0; ≤ 1000000000
min_spend.currencymetinevetşunlardan biri: TRY, INK, USD, EUR
valid_untilmetindesen ^\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.

AlanTürZorunluKurallar / açıklama
titlemetineveten az 1 karakter; en çok 80 karakter
optionsnesne dizisieveten az 1 öğe; en çok 6 öğe
options[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
options[].amountnesneevettutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar
options[].amount.amountsayıevet≥ 0; ≤ 1000000000
options[].amount.currencymetinevetşunlardan biri: TRY, INK, USD, EUR
allow_customevet/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.
selectedmetindesen ^[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.

AlanTürZorunluKurallar / açıklama
titlemetineveten az 1 karakter; en çok 80 karakter
descriptionmetinen çok 200 karakter
invoicemetinevetdesen ^[A-Za-z0-9_-]{1,64}$; createInvoiceLink/sendInvoice fatura kodu
amounttam sayıevet≥ 1; ≤ 100000000; Ink, tam sayı
invoice_payloadmetinen çok 128 karakter
urun_sinifimetinevetşunlardan biri: dijital; Ink yalnız dijital ürün için; fiziksel ürün sağlayıcı akışıdır
button_labelmetinen ç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.

AlanTürZorunluKurallar / açıklama
statusmetinevetşunlardan biri: paid, pending, failed, refunded, partially_refunded
amountnesneevettutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar
amount.amountsayıevet≥ 0; ≤ 1000000000
amount.currencymetinevetşunlardan biri: TRY, INK, USD, EUR
descriptionmetinen çok 160 karakter
paid_attam sayı≥ 0; ≤ 4102444800; Unix saniye (UTC)
methodmetinşunlardan biri: ink, provider
payment_idmetindesen ^bc_[0-9A-Za-z]{10,40}$
actionsnesne dizisien az 1 öğe; en çok 2 öğe
actions[].action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
actions[].labelmetineveten az 1 karakter; en çok 40 karakter
actions[].stylemetinşunlardan biri: primary, secondary, danger
actions[].disabledevet/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.

AlanTürZorunluKurallar / açıklama
monthmetinevetdesen ^\d{4}-(0[1-9]|1[0-2])$; YYYY-MM
selectedmetindesen ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$; YYYY-MM-DD
min_datemetindesen ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$; YYYY-MM-DD
max_datemetindesen ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$; YYYY-MM-DD
disabled_datesstring dizisien az 0 öğe; en çok 31 öğe; seçilemez (dolu/kapalı) günler
marked_datesstring dizisien 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.

AlanTürZorunluKurallar / açıklama
slotsnesne dizisieveten az 1 öğe; en çok 48 öğe
slots[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
slots[].timemetinevetdesen ^([01]\d|2[0-3]):[0-5]\d$; HH:MM
slots[].detailmetinen çok 20 karakter; ör. 40 dk
slots[].unavailableevet/hayır
selectedmetindesen ^[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.

AlanTürZorunluKurallar / açıklama
titlemetinen çok 120 karakter
optionsnesne dizisieveten az 2 öğe; en çok 10 öğe
options[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
options[].labelmetineveten az 1 karakter; en çok 80 karakter
options[].detailmetinen çok 120 karakter
selectedmetindesen ^[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)

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.

AlanTürZorunluKurallar / açıklama
placeholdermetineveten az 1 karakter; en çok 60 karakter
optionsnesne dizisieveten az 1 öğe; en çok 100 öğe
options[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
options[].labelmetineveten az 1 karakter; en çok 80 karakter
selectedmetindesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
searchableevet/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.

AlanTürZorunluKurallar / açıklama
titlemetineveten az 1 karakter; en çok 80 karakter
minsayıevet≥ -1000000000.0; ≤ 1000000000.0
maxsayıevet≥ -1000000000.0; ≤ 1000000000.0
stepsayı≥ 1e-06; ≤ 1000000000.0
fromsayıevet≥ -1000000000.0; ≤ 1000000000.0
tosayıevet≥ -1000000000.0; ≤ 1000000000.0
unitmetinen çok 8 karakter
open_ended_maxevet/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.

AlanTürZorunluKurallar / açıklama
steppersnesne dizisien az 0 öğe; en çok 6 öğe
steppers[].idmetinevetdesen ^[a-z][a-z0-9_]{0,31}$; form alanı/grup kimliği; values anahtarı
steppers[].labelmetineveten az 1 karakter; en çok 60 karakter
steppers[].valuetam sayıevet≥ -1000000; ≤ 1000000
steppers[].mintam sayı≥ -1000000; ≤ 1000000
steppers[].maxtam sayı≥ -1000000; ≤ 1000000
togglesnesne dizisien az 0 öğe; en çok 10 öğe
toggles[].idmetinevetdesen ^[a-z][a-z0-9_]{0,31}$; form alanı/grup kimliği; values anahtarı
toggles[].labelmetineveten az 1 karakter; en çok 60 karakter
toggles[].valueevet/hayırevet
actionsnesne dizisien az 1 öğe; en çok 2 öğe
actions[].action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
actions[].labelmetineveten az 1 karakter; en çok 40 karakter
actions[].stylemetinşunlardan biri: primary, secondary, danger
actions[].disabledevet/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.

AlanTürZorunluKurallar / açıklama
placeholdermetinen çok 60 karakter
querymetinen çok 100 karakter
resultsnesne dizisieveten az 0 öğe; en çok 20 öğe
results[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
results[].labelmetineveten az 1 karakter; en çok 120 karakter
results[].detailmetinen çok 160 karakter
selectedmetindesen ^[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.

AlanTürZorunluKurallar / açıklama
latitudesayıevet≥ -90; ≤ 90
longitudesayıevet≥ -180; ≤ 180
hintmetinen çok 120 karakter
button_labelmetinen çok 40 karakter
one_timeevet/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.

AlanTürZorunluKurallar / açıklama
titlemetinen çok 80 karakter
presentationmetinşunlardan biri: inline, page
stepsnesne dizisieveten az 1 öğe; en çok 10 öğe
steps[].idmetinevetdesen ^[a-z][a-z0-9_]{0,31}$; form alanı/grup kimliği; values anahtarı
steps[].titlemetineveten az 1 karakter; en çok 80 karakter
steps[].fieldsnesne dizisieveten az 1 öğe; en çok 20 öğe
steps[].fields[].idmetinevetdesen ^[a-z][a-z0-9_]{0,31}$; form alanı/grup kimliği; values anahtarı
steps[].fields[].typemetinevetş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[].labelmetineveten az 1 karakter; en çok 60 karakter
steps[].fields[].requiredevet/hayır
steps[].fields[].placeholdermetinen çok 80 karakter
steps[].fields[].hintmetinen çok 120 karakter
steps[].fields[].valuemetinen çok 2000 karakter; geçerli değer (metin/sayı/tarih/saat dizgesi; toggle için "true"/"false")
steps[].fields[].valuesstring dizisien az 0 öğe; en çok 20 öğe; multi_choice seçili değerler
steps[].fields[].optionsnesne dizisien az 1 öğe; en çok 30 öğe
steps[].fields[].options[].valuemetinevetdesen ^[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[].labelmetineveten az 1 karakter; en çok 80 karakter
steps[].fields[].minsayı≥ -1000000000.0; ≤ 1000000000.0
steps[].fields[].maxsayı≥ -1000000000.0; ≤ 1000000000.0
steps[].fields[].stepsayı≥ 1e-06; ≤ 1000000000.0
steps[].fields[].min_lengthtam sayı≥ 0; ≤ 4000
steps[].fields[].max_lengthtam sayı≥ 1; ≤ 4000
steps[].fields[].errormetinen çok 200 karakter; geçerli doğrulama hatası (bot yeniden gönderince gösterilir)
currenttam sayı≥ 0; ≤ 9
back_labelmetinen çok 30 karakter
next_labelmetinen çok 30 karakter
submit_labelmetinen ç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.

AlanTürZorunluKurallar / açıklama
labelmetinen çok 60 karakter
valuemetinen çok 4000 karakter
placeholdermetinen çok 80 karakter
min_lengthtam sayı≥ 0; ≤ 4000
max_lengthtam sayıevet≥ 1; ≤ 4000
actionsnesne dizisien az 1 öğe; en çok 2 öğe
actions[].action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
actions[].labelmetineveten az 1 karakter; en çok 40 karakter
actions[].stylemetinşunlardan biri: primary, secondary, danger
actions[].disabledevet/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.

AlanTürZorunluKurallar / açıklama
titlemetineveten az 1 karakter; en çok 80 karakter
acceptstring dizisieveten az 1 öğe; en çok 3 öğe
max_filestam sayıevet≥ 1; ≤ 10
max_size_bytestam sayı≥ 1; ≤ 52428800
hintmetinen çok 120 karakter
filesnesne dizisien az 0 öğe; en çok 10 öğe
files[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
files[].namemetinen çok 120 karakter
files[].progresstam sayı≥ 0; ≤ 100
files[].previewmetindesen ^(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.

AlanTürZorunluKurallar / açıklama
questionmetineveten az 1 karakter; en çok 200 karakter
low_labelmetinen çok 30 karakter
high_labelmetinen çok 30 karakter
selectedtam 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.

AlanTürZorunluKurallar / açıklama
questionmetineveten az 1 karakter; en çok 200 karakter
stylemetinşunlardan biri: faces, stars
scaletam sayıevet≥ 3; ≤ 7
labelsstring dizisien az 0 öğe; en çok 7 öğe
selectedtam 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.

AlanTürZorunluKurallar / açıklama
titlemetineveten az 1 karakter; en çok 160 karakter
textmetinen çok 300 karakter
confirmnesneevetbasılınca inki_component_action{action:"submit", values:{action_id}}
confirm.action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
confirm.labelmetineveten az 1 karakter; en çok 40 karakter
confirm.stylemetinşunlardan biri: primary, secondary, danger
confirm.disabledevet/hayır
cancelnesneevetbasılınca inki_component_action{action:"submit", values:{action_id}}
cancel.action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
cancel.labelmetineveten az 1 karakter; en çok 40 karakter
cancel.stylemetinşunlardan biri: primary, secondary, danger
cancel.disabledevet/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.

AlanTürZorunluKurallar / açıklama
textmetineveten az 1 karakter; en çok 160 karakter
undonesneevetbasılınca inki_component_action{action:"submit", values:{action_id}}
undo.action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
undo.labelmetineveten az 1 karakter; en çok 40 karakter
undo.stylemetinşunlardan biri: primary, secondary, danger
undo.disabledevet/hayır
expires_in_secondstam 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.

AlanTürZorunluKurallar / açıklama
titlemetineveten az 1 karakter; en çok 80 karakter
rowsnesne dizisieveten az 1 öğe; en çok 30 öğe
rows[].labelmetineveten az 1 karakter; en çok 60 karakter
rows[].valuemetineveten az 1 karakter; en çok 200 karakter
actionsnesne dizisien az 1 öğe; en çok 2 öğe
actions[].action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
actions[].labelmetineveten az 1 karakter; en çok 40 karakter
actions[].stylemetinşunlardan biri: primary, secondary, danger
actions[].disabledevet/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).

AlanTürZorunluKurallar / açıklama
couriernesneevet
courier.latitudesayıevet≥ -90; ≤ 90
courier.longitudesayıevet≥ -180; ≤ 180
courier.namemetinen çok 60 karakter
destinationnesneevet
destination.latitudesayıevet≥ -90; ≤ 90
destination.longitudesayıevet≥ -180; ≤ 180
routenesne dizisien az 2 öğe; en çok 200 öğe
route[].latitudesayıevet≥ -90; ≤ 90
route[].longitudesayıevet≥ -180; ≤ 180
eta_minutestam sayıevet≥ 0; ≤ 1440
status_textmetinen çok 120 karakter
phonemetindesen ^\+?[0-9 ()-]{5,20}$
liveevet/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.

AlanTürZorunluKurallar / açıklama
titlemetinen çok 120 karakter
ends_attam sayıevet≥ 0; ≤ 4102444800; Unix saniye (UTC)
finished_textmetinen ç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.

AlanTürZorunluKurallar / açıklama
titlemetineveten az 1 karakter; en çok 120 karakter
currentnesneevettutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar
current.amountsayıevet≥ 0; ≤ 1000000000
current.currencymetinevetşunlardan biri: TRY, INK, USD, EUR
targetnesneevettutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar
target.amountsayıevet≥ 0; ≤ 1000000000
target.currencymetinevetşunlardan biri: TRY, INK, USD, EUR
backerstam sayı≥ 0; ≤ 100000000
ends_attam sayı≥ 0; ≤ 4102444800; Unix saniye (UTC)
actionsnesne dizisien az 1 öğe; en çok 2 öğe
actions[].action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
actions[].labelmetineveten az 1 karakter; en çok 40 karakter
actions[].stylemetinşunlardan biri: primary, secondary, danger
actions[].disabledevet/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.

AlanTürZorunluKurallar / açıklama
questionmetineveten az 1 karakter; en çok 200 karakter
optionsnesne dizisieveten az 2 öğe; en çok 10 öğe
options[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
options[].labelmetineveten az 1 karakter; en çok 80 karakter
options[].votestam sayıevet≥ 0; ≤ 100000000
total_votestam sayıevet≥ 0; ≤ 100000000
selectedmetindesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
closedevet/hayır
liveevet/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.

AlanTürZorunluKurallar / açıklama
titlemetinen çok 80 karakter
currentnesnetutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar
current.amountsayıevet≥ 0; ≤ 1000000000
current.currencymetinevetşunlardan biri: TRY, INK, USD, EUR
change_percentsayı≥ -100000; ≤ 100000
pointsnumber dizisieveten az 2 öğe; en çok 366 öğe
x_labelsstring dizisien 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ı.

AlanTürZorunluKurallar / açıklama
tilesnesne dizisieveten az 1 öğe; en çok 6 öğe
tiles[].valuemetineveten az 1 karakter; en çok 16 karakter
tiles[].labelmetineveten az 1 karakter; en çok 30 karakter
tiles[].brand_colormetinş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.

AlanTürZorunluKurallar / açıklama
competitionmetinen çok 60 karakter
statemetinevetşunlardan biri: scheduled, live, finished
minutetam sayı≥ 0; ≤ 150
homenesneevet
home.namemetineveten az 1 karakter; en çok 40 karakter
home.scoretam sayıevet≥ 0; ≤ 999
home.logometindesen ^(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_colormetinşunlardan biri: mavi, turuncu, mor, pembe, altin, yesil, turkuaz
awaynesneevet
away.namemetineveten az 1 karakter; en çok 40 karakter
away.scoretam sayıevet≥ 0; ≤ 999
away.logometindesen ^(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_colormetinşunlardan biri: mavi, turuncu, mor, pembe, altin, yesil, turkuaz
eventsnesne dizisien az 0 öğe; en çok 10 öğe
events[].minutetam sayı≥ 0; ≤ 150
events[].textmetineveten 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.

AlanTürZorunluKurallar / açıklama
locationmetineveten az 1 karakter; en çok 80 karakter
temperaturetam sayı≥ -90; ≤ 70
unitmetinşunlardan biri: celsius, fahrenheit
summarymetinen çok 80 karakter
hoursnesne dizisieveten az 1 öğe; en çok 24 öğe
hours[].labelmetineveten az 1 karakter; en çok 12 karakter
hours[].temperaturetam sayıevet≥ -90; ≤ 70
hours[].conditionmetinevetş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.

AlanTürZorunluKurallar / açıklama
indextam sayı≥ 1; ≤ 999
totaltam sayı≥ 1; ≤ 999
questionmetineveten az 1 karakter; en çok 300 karakter
optionsnesne dizisieveten az 2 öğe; en çok 6 öğe
options[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
options[].labelmetineveten az 1 karakter; en çok 120 karakter
time_limit_secondstam sayı≥ 1; ≤ 3600
remaining_secondstam sayı≥ 0; ≤ 3600
selectedmetindesen ^[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.

AlanTürZorunluKurallar / açıklama
optionsnesne dizisieveten az 1 öğe; en çok 6 öğe
options[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
options[].labelmetineveten az 1 karakter; en çok 120 karakter
options[].statemetinevetşunlardan biri: correct, wrong, neutral
correct_counttam sayıevet≥ 0; ≤ 999
totaltam sayıevet≥ 1; ≤ 999
pointstam sayı≥ 0; ≤ 100000000
ranktam sayı≥ 1; ≤ 100000000
rank_periodmetinş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.

AlanTürZorunluKurallar / açıklama
promptmetinen çok 300 karakter
repliesnesne dizisieveten az 1 öğe; en çok 12 öğe
replies[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
replies[].labelmetineveten 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.

AlanTürZorunluKurallar / açıklama
tabsnesne dizisieveten az 1 öğe; en çok 8 öğe
tabs[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
tabs[].labelmetineveten az 1 karakter; en çok 30 karakter
tabs[].itemsnesne dizisieveten az 0 öğe; en çok 30 öğe
tabs[].items[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
tabs[].items[].namemetineveten az 1 karakter; en çok 80 karakter
tabs[].items[].descriptionmetinen çok 160 karakter
tabs[].items[].pricenesnetutar; biçimlendirmeyi (₺, ondalık ayracı) istemci yapar
tabs[].items[].price.amountsayıevet≥ 0; ≤ 1000000000
tabs[].items[].price.currencymetinevetşunlardan biri: TRY, INK, USD, EUR
tabs[].items[].imagemetindesen ^(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_colormetinşunlardan biri: mavi, turuncu, mor, pembe, altin, yesil, turkuaz
active_tabmetindesen ^[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)

Damla’ya bağla: etkinlik takvime eklenir / Damla hatırlatır (istemci yerel; kullanıcı izniyle, bota veri gitmez).

AlanTürZorunluKurallar / açıklama
titlemetineveten az 1 karakter; en çok 120 karakter
starts_attam sayıevet≥ 0; ≤ 4102444800; Unix saniye (UTC)
ends_attam sayı≥ 0; ≤ 4102444800; Unix saniye (UTC)
locationmetinen çok 120 karakter
buttonsstring dizisieveten 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).

AlanTürZorunluKurallar / açıklama
titlemetineveten az 1 karakter; en çok 120 karakter
textmetinen çok 300 karakter
linkmetinevetdesen ^https://[^\s\x00-\x1f\x7f]{1,2040}$
share_labelmetinen ç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.

AlanTürZorunluKurallar / açıklama
titlemetineveten az 1 karakter; en çok 120 karakter
ends_attam sayı≥ 0; ≤ 4102444800; Unix saniye (UTC)
participant_counttam sayı≥ 0; ≤ 100000000
participants_previewnesne dizisien az 0 öğe; en çok 5 öğe
participants_preview[].initialmetineveten az 1 karakter; en çok 2 karakter
participants_preview[].brand_colormetinşunlardan biri: mavi, turuncu, mor, pembe, altin, yesil, turkuaz
joinedevet/hayır
actionsnesne dizisieveten az 1 öğe; en çok 1 öğe
actions[].action_idmetinevetdesen ^[a-z0-9_-]{1,64}$; düğme eylem kimliği; values.action_id olarak geri gelir
actions[].labelmetineveten az 1 karakter; en çok 40 karakter
actions[].stylemetinşunlardan biri: primary, secondary, danger
actions[].disabledevet/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.

AlanTürZorunluKurallar / açıklama
titlemetinen çok 80 karakter
unitmetinen çok 16 karakter
entriesnesne dizisieveten az 1 öğe; en çok 50 öğe
entries[].ranktam sayıevet≥ 1; ≤ 100000000
entries[].namemetineveten az 1 karakter; en çok 60 karakter
entries[].scoresayıevet≥ -1000000000000.0; ≤ 1000000000000.0
entries[].is_youevet/hayır
entries[].avatarmetindesen ^(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_colormetinş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.

AlanTürZorunluKurallar / açıklama
greetingnesneevet
greeting.titlemetineveten az 1 karakter; en çok 80 karakter
greeting.textmetinen çok 200 karakter
greeting.suggestionsnesne dizisien az 0 öğe; en çok 8 öğe
greeting.suggestions[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
greeting.suggestions[].labelmetineveten az 1 karakter; en çok 20 karakter
tilesnesne dizisien az 0 öğe; en çok 6 öğe
tiles[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
tiles[].titlemetineveten az 1 karakter; en çok 40 karakter
tiles[].subtitlemetinen çok 60 karakter
tiles[].iconmetinşunlardan biri: calendar, tag, clock, location, cart, chat, phone, info, star, gift, ticket, document, heart, user, settings, search
tiles[].brand_colormetinşunlardan biri: mavi, turuncu, mor, pembe, altin, yesil, turkuaz
sectionsnesne dizisien az 0 öğe; en çok 4 öğe
sections[].titlemetineveten az 1 karakter; en çok 60 karakter
sections[].cardsnesne dizisieveten az 1 öğe; en çok 5 öğe
sections[].cards[].valuemetinevetdesen ^[A-Za-z0-9_.:-]{1,64}$; seçenek/öğe değeri; istemci bunu inki_component_action.values içinde geri gönderir
sections[].cards[].titlemetineveten az 1 karakter; en çok 80 karakter
sections[].cards[].subtitlemetinen çok 120 karakter
sections[].cards[].datemetindesen ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$; YYYY-MM-DD
sections[].cards[].action_labelmetinen ç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)