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ış#
- 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. - Kategoriler: Atölye → uygulaman → Bildirimler'de bildirim kategorilerini tanımlarsın (Kategoriler).
- Gönderim:
inkiSendNotificationile bildirimi gönderirsin; yanıt{"notification_id": "bn_…"}(Bildirim göndermek). - 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.
- Dokunuş: telefondaki bildirime ya da merkezdeki satıra dokunulunca Mini App açılır;
start_paraminitData.start_paramiçindedir. Mini App zaten açıksa sayfa yeniden yüklenmez,inki_notification_openedolayı gelir (Mini App tarafı). Satır okundu olur. - Kullanıcının kontrolü: kullanıcı genel Bildirimler anahtarını ve her kategoriyi açıp kapatır; değişince sana
inki_notification_settingsupdate'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ü):
| Alan | Kural |
|---|---|
| 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ür | islem · hatirlatma · tanitim |
| Tür | Ne için | Varsayılan |
|---|---|---|
islem | Alıcının taraf olduğu tek bir somut kayıtta bir şey oldu: sipariş, ödeme, randevu, üyelik kaydı | açık |
hatirlatma | Hatırlatma ve periyodik özet: randevu yarın, aidat yaklaşıyor, haftalık özet | açık |
tanitim | Kampanya, indirim, yeni ürün — ticari elektronik ileti | kapalı |
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.
| Bildirim | Doğru tür | Neden |
|---|---|---|
| "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.
islemvehatirlatmakategorileri varsayılan olarak açıktır.tanitimkategorileri 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:
| Parametre | Kural |
|---|---|
user_id | zorunlu — update'teki ya da initData'daki kullanıcı kimliği (from.id) |
category | zorunlu — Atölye'deki kategori anahtarı |
title | zorunlu — 1–40 karakter, tek satır |
body | zorunlu — 1–140 karakter |
start_param | ≤ 64 karakter, A-Z a-z 0-9 _ - — Mini App'e gelir |
importance | normal (varsayılan) ya da high — **yalnız islem** |
idempotency_key | zorunlu — 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_idplatformun bildirim kimliğidir. Bildirim bir sohbet mesajı değildir;Messagedönmez, düzenlenemez, silinemez.- Aynı
idempotency_keyve aynı içerikle tekrar çağırırsan aynınotification_iddöner, kullanıcıya ikinci bildirim gitmez. Aynı anahtarı farklı içerikle kullanırsan400 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.highkullanı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'ıinitDatadoğrulamasından sonra kullan; kullanıcıya ait olmayan bir kaydı yalnızstart_param'a bakarak açma.- Web sürümünde
inkiveta-web-app.jsyüklüyse aynı olay gelir; yalnız resmîtelegram-web-app.jsileTelegram.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
islembildirimi 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.
islemvehatirlatmabildirimlerinde tanıtım dili (indirim, kampanya, fırsat, yüzde…),islembildiriminde özet/hatırlatma dili kullanılamaz. Aykırılık400 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#
| Kapsam | Sınır (kayan 24 saat) |
|---|---|
Aynı kullanıcıya islem | 20 |
Aynı kullanıcıya hatirlatma | 3 |
Aynı kullanıcıya tanitim | 1 |
| Uygulama geneli | 10.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ı#
| Hata | Anlamı |
|---|---|
400 Bad Request: NOTIFICATION_CATEGORY_INVALID | category Atölye'de tanımlı değil |
400 Bad Request: NOTIFICATION_TITLE_TOO_LONG · NOTIFICATION_BODY_TOO_LONG · title is empty · body is empty | Baş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_INVALID | high yalnız islem kategorisinde |
400 Bad Request: START_PARAM_INVALID | start_param biçimi ya da uzunluğu |
400 Bad Request: NOTIFICATION_WEB_APP_REQUIRED | Menü düğmesi https Mini App değil ya da origin bu ortamda doğrulanmamış |
400 Bad Request: IDEMPOTENCY_KEY_REUSED | Aynı anahtar farklı içerikle |
400 Bad Request: USER_ID_INVALID | user_id bu uygulamanın kullanıcısı değil |
403 Forbidden: bot can't initiate conversation with a user | Kullanıcı başlatmamış ya da yazma tercihi bu an izin vermiyor — kullanıcıyı listenden silme |
403 Forbidden: bot was blocked by the user | Kullanıcı uygulamayı engelledi |
403 Forbidden: NOTIFICATIONS_DISABLED | Kullanı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 N | Sınır aşıldı; parameters.retry_after saniye bekle |
Uçtan uca örnek: kulüp siparişi#
| Olay | Kategori (tür) | importance | start_param |
|---|---|---|---|
| Sipariş hazır | siparis (islem) | high | siparis_<id> |
| Ödeme onaylandı | odeme (islem) | normal | odeme_<id> |
| Aidat yaklaşıyor | aidat (hatirlatma) | normal | aidat |
| Yeni sipariş geldi (kulüp sahibine) | yeni_siparis (islem) | high | yonetim_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.