Geliştirici paneli inkiveta.com

Mini App bildirimleri

Uygulaman, kullanıcıya kendi bildirimini gönderebilir. Bildirim kullanıcının bildirim merkezine (Sohbetler ekranının üstündeki zil) düşer ve telefona bildirim olarak gelir. Kullanıcı bildirime dokununca sohbet değil doğrudan Mini App'in açılır ve gönderdiğin start_param Mini App'e gelir: "Siparişin hazır" bildirimi siparişin sayfasını, "Aidatın 3 gün sonra" bildirimi ödeme sayfasını açar.

Sohbet botun olması gerekmez. Bildirim uygulamanın sohbetine yazılmaz; yalnız Mini App'i olan bir uygulama da bildirim gönderir ve bildirim yüzünden Sohbetler listesine girmez.

Bütün uygulamalara açık, genel bir yetenektir; inkiveta'nın kendi uygulamaları da aynı yöntemi aynı kurallarla kullanır.

Örnek kullanımlar:

  • Bir kulüp, sipariş hazır olunca üyesine haber verir; dokununca Mini App'te o sipariş açılır.
  • Bir kuaför, yarınki randevuyu hatırlatır; dokununca randevu sayfası açılır.
  • Bir mağaza, tanıtım bildirimlerini açan kullanıcılarına yeni sezonu duyurur.

Uçtan uca akış#

  1. Hedef: uygulamanın menü düğmesi https Mini App (web_app) olmalı ve adresin origin'i o ortamda doğrulanmış olmalı (Mini App). Bildirimin açacağı adres budur.
  2. Kategoriler: Atölye → uygulaman → Bildirimler'de bildirim kategorilerini tanımlarsın (Kategoriler).
  3. Gönderim: inkiSendNotification ile bildirimi gönderirsin; yanıt {"notification_id": "bn_…"} (Bildirim göndermek).
  4. Kullanıcı ne görür? Bildirim merkezinde uygulamanın adı ve simgesiyle bir satır belirir (zilde okunmamış sayısı artar). Kullanıcının ayarı izin veriyorsa telefona da bildirim gelir: başlık uygulamanın adı (tanıtımda "Uygulama · Tanıtım"), gövde senin başlığın ve metnin.
  5. Dokunuş: telefondaki bildirime ya da merkezdeki satıra dokunulunca Mini App açılır; start_param initData.start_param içindedir. Mini App zaten açıksa sayfa yeniden yüklenmez, inki_notification_opened olayı gelir (Mini App tarafı). Satır okundu olur.
  6. Kullanıcının kontrolü: kullanıcı genel Bildirimler anahtarını ve her kategoriyi açıp kapatır; değişince sana inki_notification_settings update'i gelir (Tercihler).

Kategoriler#

Her bildirim bir kategoriyle gönderilir. Atölye → Bildirimler'de en çok 8 kategori tanımlarsın (Sahip ve Geliştirici rolü):

AlanKural
Anahtar^[a-z0-9_]{1,32}$ — inkiSendNotification'daki category; uygulamada tek
Ad≤ 40 karakter; kullanıcı ayarlarda bunu görür
Açıklama≤ 140 karakter; ne zaman bildirim geleceğini anlat
Türislem · hatirlatma · tanitim
TürNe içinVarsayılan
islemAlıcının taraf olduğu tek bir somut kayıtta bir şey oldu: sipariş, ödeme, randevu, üyelik kaydıaçık
hatirlatmaHatırlatma ve periyodik özet: randevu yarın, aidat yaklaşıyor, haftalık özetaçık
tanitimKampanya, indirim, yeni ürün — ticari elektronik iletikapalı

islem mi, hatirlatma mı?#

islem, kullanıcının taraf olduğu tek bir kayıtta bir durumun değiştiğini bildirir. Periyodik özet, toplu duyuru ve hatırlatma asla islem değildir — hatirlatmadır. Sunucu islem metnindeki özet/hatırlatma dilini (özet, hatırlatma, unutma…) 400 NOTIFICATION_CONTENT_REJECTED ile reddeder.

BildirimDoğru türNeden
"1048 numaralı siparişin hazır"islem ✓tek sipariş, durum değişti
"Ödemen alındı: Kasım aidatı"islem ✓tek ödeme kaydı
"Randevun iptal edildi"islem ✓tek randevu, durum değişti
"Üyeliğin onaylandı"islem ✓tek üyelik kaydı
"Yarın 14:00 randevun var"hatirlatma (islem ✗)durum değişmedi, hatırlatma
"Aidatın 3 gün sonra"hatirlatma (islem ✗)hatırlatma
"Bu haftanın özeti: 3 sipariş"hatirlatma (islem ✗)periyodik özet, tek kayıt değil
"Yeni sezon ürünleri geldi"tanitim (islem ✗, hatirlatma ✗)ticari ileti

Dikkat: Tür sonradan değiştirilemez. Değiştirmen gerekiyorsa kategoriyi silip yeni bir anahtarla eklersin; kullanıcıların eski kategorideki seçimleri yeni kategoriye taşınmaz.

Atölye'de her kategorinin yanında son 30 günün toplu sayıları görünür: gönderilen, telefona anında giden, yalnız bildirim merkezinde kalan ve açılan. Son 30 günde 20'den az gönderim yapılan kategoride sayılar gösterilmez.

Kullanıcı tercihleri ve tanıtım onayı#

Kullanıcı genel Bildirimler anahtarını ve her kategoriyi ayrı ayrı açıp kapatır: uygulamanın ayarlarında, bildirim merkezindeki satırın uzun basma menüsünde ya da Mini App'in ••• menüsünde. Sohbet gerekmez.

  • islem ve hatirlatma kategorileri varsayılan olarak açıktır.
  • tanitim kategorileri kullanıcı açıkça açmadıkça kapalıdır. Kullanıcı açarken platformun onay metnini görür; onay inkiveta'da kaydedilir. Uygulamanın sahibi değişirse ya da aydınlatma metnin güncellenirse onay düşer, kullanıcı yeniden açmalıdır.
  • Tanıtım bildiriminin başlığına platform "Tanıtım" etiketini ekler.
  • Ticari İletişim kuralı: tanıtım bildirimi ticari elektronik iletidir. İYS kaydı ve kullanıcının retlerinin İYS'ye işlenmesi senin yükümlülüğündür; kullanıcı kategoriyi kapattığında (enabled: false) bunu ret olarak işlersin (Uygulama Geliştirici Şartları, "Mini App bildirimleri" bölümü).
  • Kullanıcı uygulamanı engellerse ya da genel anahtarı kapatırsa, daha önce gönderdiğin bildirimler de bildirim merkezinde görünmez olur.

Kullanıcı bir kategoriyi ya da genel anahtarı değiştirince sana inki_notification_settings update'i gelir (yalnız allowed_updates'e eklediysen):

json{"update_id": 9132, "inki_notification_settings": {
  "from": {"id": 4185489292941965, "is_bot": false, "first_name": "Kullanıcı"},
  "category": "aidat", "enabled": false, "date": 1765000000}}

category: null genel anahtarı gösterir. Kapalı kategoriye göndermeyi bırak; kullanıcı tekrar açınca yine bu update gelir. Kullanıcı engellediyse update gelmez.

Kategorileri koddan okumak#

API 1.5.0'dan itibaren inkiGetNotificationCategories (parametresiz) Atölye'deki kategorileri sıraya göre döner; kategori yoksa []:

json{"ok":true,"result":[{"key":"siparis","name":"Sipariş durumu","description":"Siparişin hazır olunca","type":"islem","position":0}]}

Kategoriler uygulamana bağlıdır; test ve gerçek ortamda aynıdır. Kodundaki anahtarları açılışta ya da günde bir bununla karşılaştır: Atölye'de olmayan anahtar 400 NOTIFICATION_CATEGORY_INVALID verir, yanlış tür içerik kuralına takılır. Kategori yalnız Atölye'den eklenir ve değiştirilir.

Bildirim göndermek#

inkiSendNotification:

ParametreKural
user_idzorunlu — update'teki ya da initData'daki kullanıcı kimliği (from.id)
categoryzorunlu — Atölye'deki kategori anahtarı
titlezorunlu — 1–40 karakter, tek satır
bodyzorunlu — 1–140 karakter
start_param≤ 64 karakter, A-Z a-z 0-9 _ - — Mini App'e gelir
importancenormal (varsayılan) ya da high — **yalnız islem**
idempotency_keyzorunlu — 1–64 karakter, A-Z a-z 0-9 _ -

İstek:

bashcurl -s "https://app.inkiveta.com/bot$BOT_TOKEN/inkiSendNotification" -H 'Content-Type: application/json' -d '{
  "user_id": 4185489292941965,
  "category": "siparis",
  "title": "Siparişin hazır",
  "body": "Kulüpten teslim alabilirsin.",
  "start_param": "siparis_1048",
  "importance": "high",
  "idempotency_key": "siparis-1048-hazir"
}'

Yanıt:

json{"ok": true, "result": {"notification_id": "bn_01JD4Z7K8Q2M3N4P5R6S7T8V9W"}}
  • notification_id platformun bildirim kimliğidir. Bildirim bir sohbet mesajı değildir; Message dönmez, düzenlenemez, silinemez.
  • Aynı idempotency_key ve aynı içerikle tekrar çağırırsan aynı notification_id döner, kullanıcıya ikinci bildirim gitmez. Aynı anahtarı farklı içerikle kullanırsan 400 IDEMPOTENCY_KEY_REUSED.
  • Bildirim her zaman bildirim merkezine yazılır. Telefona anında gitmesi kullanıcının ayarına bağlıdır: bildirim sıklığı "her an" ise gider; "önemliler" ise yalnız importance: "high" gider; "günde 1 özet" seçtiyse ya da uygulamanı sessize aldıysa telefona gitmez, yalnız merkezde (zil rozetinde) görünür. high kullanıcının sessiz saatlerini aşmaz (o saatlerde bildirim sessiz gelir).
  • Bildirim merkezindeki satır 30 gün saklanır.

Mini App tarafı#

js// Soğuk açılış: start_param initData'da
const sp = Telegram.WebApp.initDataUnsafe.start_param;   // "siparis_1048"
if (sp) goTo(sp);

// Mini App zaten açıkken bildirime dokunulursa sayfa yeniden yüklenmez, olay gelir
Telegram.WebApp.onEvent("inki_notification_opened", (e) => goTo(e.start_param)); // {start_param, category}
  • start_param'ı initData doğrulamasından sonra kullan; kullanıcıya ait olmayan bir kaydı yalnız start_param'a bakarak açma.
  • Web sürümünde inkiveta-web-app.js yüklüyse aynı olay gelir; yalnız resmî telegram-web-app.js ile Telegram.WebView.onEvent('inki_notification_opened', …) dinle (Köprü).

Kurallar#

  • Bildirim, kendiliğinden yazmadır. Kullanıcı uygulamanı başlatmış olmalı (Mini App'i açan herkes başlatmıştır). Kullanıcı "İlk mesajı atabilir" tercihini kapattıysa, Başlat'tan sonra bir şey yapmış ya da Mini App'ini açmış olmalı. **"Sen yazmadan yazabilir" kapalıysa yalnız islem bildirimi ve son etkileşimden (sohbet ya da Mini App açılışı) 7 gün** içinde gönderilebilir (Kullanıcıya yazma kuralları).
  • İçerik yasakları: bağlantı (http, www, alan adı), telefon numarası (7 haneden uzun sayı dizisi), şifre, kod, IBAN, kart numarası gibi değerler ve bunları isteyen metin yasaktır; başlık tek satırdır. islem ve hatirlatma bildirimlerinde tanıtım dili (indirim, kampanya, fırsat, yüzde…), islem bildiriminde özet/hatırlatma dili kullanılamaz. Aykırılık 400 NOTIFICATION_CONTENT_REJECTED.
  • Şikâyet: kullanıcı bildirimi bildirim merkezinden ya da Mini App'in ••• menüsünden bildirebilir. 30 günde en az 5 farklı kişi ve alıcıların en az %1'i bildirirse uygulamanın bildirimleri askıya alınır (403 NOTIFICATIONS_SUSPENDED); kaldırmak için Atölye → Destek.

Sınırlar#

KapsamSınır (kayan 24 saat)
Aynı kullanıcıya islem20
Aynı kullanıcıya hatirlatma3
Aynı kullanıcıya tanitim1
Uygulama geneli10.000 (doğrulanmış uygulama 100.000, test ortamı 200)

Aşımda 429 Too Many Requests: retry after N. Genel gönderim sınırları da geçerlidir: saniyede 30, aynı kullanıcıya 3 saniyede 3 (Limitler).

Gizlilik ve istatistik#

Bir kullanıcının bildirimi açıp açmadığı sana hiçbir zaman iletilmez. Atölye'de yalnız kategori başına toplu sayılar görünür (Kategoriler).

Hata kodları#

HataAnlamı
400 Bad Request: NOTIFICATION_CATEGORY_INVALIDcategory Atölye'de tanımlı değil
400 Bad Request: NOTIFICATION_TITLE_TOO_LONG · NOTIFICATION_BODY_TOO_LONG · title is empty · body is emptyBaşlık ya da gövde uzunluğu
400 Bad Request: NOTIFICATION_CONTENT_REJECTEDİçerik kuralı (bağlantı, telefon, gizli değer, hizmet kategorisinde tanıtım dili, islem'de özet/hatırlatma dili, başlıkta satır sonu)
400 Bad Request: NOTIFICATION_IMPORTANCE_INVALIDhigh yalnız islem kategorisinde
400 Bad Request: START_PARAM_INVALIDstart_param biçimi ya da uzunluğu
400 Bad Request: NOTIFICATION_WEB_APP_REQUIREDMenü düğmesi https Mini App değil ya da origin bu ortamda doğrulanmamış
400 Bad Request: IDEMPOTENCY_KEY_REUSEDAynı anahtar farklı içerikle
400 Bad Request: USER_ID_INVALIDuser_id bu uygulamanın kullanıcısı değil
403 Forbidden: bot can't initiate conversation with a userKullanıcı başlatmamış ya da yazma tercihi bu an izin vermiyor — kullanıcıyı listenden silme
403 Forbidden: bot was blocked by the userKullanıcı uygulamayı engelledi
403 Forbidden: NOTIFICATIONS_DISABLEDKullanıcı bildirimleri ya da bu kategoriyi kapattı; tanıtımda açık onay yok
403 Forbidden: NOTIFICATIONS_SUSPENDEDŞikâyetler nedeniyle askıda
429 Too Many Requests: retry after NSınır aşıldı; parameters.retry_after saniye bekle

Uçtan uca örnek: kulüp siparişi#

OlayKategori (tür)importancestart_param
Sipariş hazırsiparis (islem)highsiparis_<id>
Ödeme onaylandıodeme (islem)normalodeme_<id>
Aidat yaklaşıyoraidat (hatirlatma)normalaidat
Yeni sipariş geldi (kulüp sahibine)yeni_siparis (islem)highyonetim_siparis_<id>

Kulüp sahibi de uygulamayı başlatmış bir kullanıcıdır; ona da aynı yöntemle bildirim gönderirsin.

SSS#

Sohbet botum yok, yalnız Mini App'im var. Bildirim nereye düşer? Kullanıcının bildirim merkezine (Sohbetler ekranındaki zil) ve kullanıcının ayarı izin veriyorsa telefona. Uygulamanın sohbetine hiçbir şey yazılmaz; uygulaman Sohbetler listesine girmez.

Sohbet botum var. Bildirim sohbette de görünür mü? Hayır. Bildirim her uygulamada yalnız bildirim merkezindedir. Sohbette bir şey göstermek istiyorsan normal mesaj gönder (sendMessage); o, sohbet mesajlarının kurallarına tabidir.

Kullanıcı telefonda bildirimi görmedi, neden? Sıklığı "günde 1 özet" ya da "önemliler" (ve importance normal) olabilir, uygulamanı sessize almış olabilir ya da sessiz saatlerindedir. Bildirim yine de bildirim merkezindedir.

Kimin açtığını öğrenebilir miyim? Hayır. Atölye'de yalnız kategori başına toplu sayılar görünür.

Bildirimi geri çekebilir ya da düzenleyebilir miyim? Hayır. Yanlış bildirim gönderdiysen düzeltmeyi yeni bir islem bildirimiyle gönder.