Geliştirici paneli inkiveta.com

Güncellemeleri almak

Kullanıcı uygulamana bir şey yaptığında (mesaj yazdı, düğmeye bastı, ödeme yaptı…) inkiveta bunu bir update nesnesi olarak sana iletir. Bir uygulama update'leri aynı anda yalnız bir yoldan alır:

YolNe zaman seçNot
Webhook (setWebhook)İnternetten erişilebilir bir HTTPS sunucun varsa (önerilen)Kuruluyken getUpdates 409 döner
Uzun yoklama (getUpdates)Geliştirme sırasında, ya da sunucun dışarıdan erişilemiyorsaAynı anda tek bir yoklayıcı
Akış editörüSunucun yoksa; sohbet botu inkiveta'da çalışırAkış yayındayken diğer ikisi 409 döner (Akış editörü)

Dikkat: Gerçek ortamda webhook ya da getUpdates kullanabilmek için Atölye → Profil'de barındırma ülkesini beyan etmiş olmalısın. Beyan yoksa: 400 Bad Request: bad webhook: hosting country must be declared in Atölye before enabling (KVKK md.9). Ayrıntı: Gizlilik.

Update neye benzer?#

Her update'in artan bir update_id'si ve tek bir içerik alanı vardır:

json{
  "update_id": 5521,
  "message": {
    "message_id": 42,
    "from": {"id": 4185489292941965, "is_bot": false, "first_name": "Kullanıcı", "language_code": "tr"},
    "chat": {"id": 4185489292941965, "type": "private"},
    "date": 1794355200,
    "text": "Yarın 14:00 boş mu?"
  }
}
  • chat.id her zaman from.id'ye eşittir ve chat.type her zaman "private"'dır.
  • from.id uygulamaya özel takma kimliktir: aynı kişi başka bir uygulamada farklı kimlikle görünür. Kendi veritabanında kullanıcıyı bununla tanı.
  • first_name / last_name: kullanıcı görünen ad izni verdiyse adı (son kelime last_name; tek kelimeyse last_name yok), vermediyse first_name = "Kullanıcı". username yalnız izinle gelir. İzinleri kullanıcı uygulamayı başlatırken seçer, sonradan uygulama ayarlarından değiştirir; Mini App'te profil resmi (photo_url) ve izin isteme için Mini App → Profil bilgisi. Telefon numarası hiç gelmez (kullanıcı kişi paylaşmadıkça).

Webhook#

bashcurl -s "https://app.inkiveta.com/bot$BOT_TOKEN/setWebhook" \
  -H 'Content-Type: application/json' \
  -d '{"url":"https://bot.ornek.com/hook",
       "secret_token":"uzun-rastgele-bir-dize",
       "allowed_updates":["message","callback_query","inki_component_action"]}'

Adres kuralları

  • https olmalı; port 443, 80, 88 ya da 8443; en çok 512 karakter; içinde kullanıcı adı/parola olmamalı.
  • Adres özel ya da iç ağ IP'sine çözülüyorsa reddedilir. ip_address verirsen o da aynı kurallarla denetlenir.
  • Kendinden imzalı sertifika kullanıyorsan certificate ile yükle.
  • Yönlendirmeler takip edilmez: 3xx yanıtı hata sayılır.

Güvenlik: secret_token (1–256 karakter, [A-Za-z0-9_-]) verirsen her istekte X-Telegram-Bot-Api-Secret-Token başlığıyla gelir. Başlık tutmuyorsa isteği reddet; böylece adresini bulan biri sana sahte update gönderemez.

Teslim

  • İstek: POST, Content-Type: application/json, gövde = update.
  • Sunucunun bağlantıyı 3 sn içinde kabul etmesi, toplamda 30 sn içinde yanıt vermesi gerekir. Yanıt gövdesi en çok 1 MB.
  • 2xx dışındaki her yanıt yeniden denenir. Bekleme süresi: min(3600, 2^(deneme−1)) × [0,5–1] saniye. 24 saat içinde teslim edilemeyen update düşer.
  • Son hata getWebhookInfo yanıtındaki last_error_date / last_error_message alanlarında görünür (Wrong response from the webhook: 500 Internal Server Error, Connection timed out, Failed to resolve host…).
  • Aynı kullanıcının update'leri sırayla gelir; farklı kullanıcılarınki paralel gelebilir (en çok max_connections, 1–100, varsayılan 40).
  • drop_pending_updates: true bekleyen update'leri siler.

Python (Flask) ile en küçük webhook:

pythonimport os, requests
from flask import Flask, request, abort

TOKEN = os.environ["BOT_TOKEN"]
GIZLI = os.environ["WEBHOOK_SECRET"]
API = f"https://app.inkiveta.com/bot{TOKEN}"
app = Flask(__name__)

@app.post("/hook")
def hook():
    if request.headers.get("X-Telegram-Bot-Api-Secret-Token") != GIZLI:
        abort(403)
    u = request.get_json()
    if "message" in u and "text" in u["message"]:
        requests.post(f"{API}/sendMessage", json={
            "chat_id": u["message"]["chat"]["id"],
            "text": "Aldım: " + u["message"]["text"],
        }, timeout=10)
    return "", 200   # hızlı 200 dön; uzun işleri kuyruğa at

İpucu: Webhook işleyicin hızlı 200 dönmeli. Uzun süren işleri (ödeme kontrolü, dış API) bir kuyruğa at; aksi hâlde 30 sn sınırına takılır ve update yeniden gönderilir.

Webhook yanıtında yöntem çağırmak#

Webhook isteğine verdiğin 200 yanıtının gövdesine bir yöntem yazarsan inkiveta onu uygulamanın adına çalıştırır — ayrı bir HTTP isteği atmana gerek kalmaz:

json{"method":"sendMessage","chat_id":4185489292941965,"text":"Tamam, not ettim."}
  • JSON, form-urlencoded ya da multipart olabilir; her yöntem kabul edilir ve normal hız sınırlarından geçer.
  • Sonuç sana dönmez; hata olursa webhook günlüğüne yazılır.
  • Yürütme süresi 5 sn'dir. URL'den medya indirme ya da dosya yükleme içeren yanıtlar kuyruğa alınır ve en çok bir kez çalıştırılır.

getUpdates (uzun yoklama)#

bashcurl -s "https://app.inkiveta.com/bot$BOT_TOKEN/getUpdates?timeout=50&offset=5522"
  • timeout en çok 50 sn: bu süre boyunca yeni update gelirse hemen döner, gelmezse boş liste döner.
  • offset = son aldığın update_id + 1. Bu, öncekileri onaylar ve siler. Onaylanmayan update 24 saat sonra düşer.
  • limit 1–100. Negatif offset sondan sayar.
  • allowed_updates bir kez verilince sonraki çağrılarda da geçerli kalır.
  • Uygulama (ve ortam) başına aynı anda tek yoklama: ikinci bir yoklama başlarsa eskisi 409 Conflict: terminated by other getUpdates request; make sure that only one bot instance is running ile biter. Botunu iki yerde birden çalıştırmadığından emin ol.
  • Webhook kuruluyken getUpdates → 409 Conflict: can't use getUpdates method while webhook is active; use deleteWebhook to delete the webhook first. Önce deleteWebhook çağır.

Update türleri#

AlanNe zaman gelir
messageKullanıcı mesaj, medya, konum, kişi gönderdi; ödeme tamamlandı (successful_payment); Mini App veri gönderdi (web_app_data)
edited_messageKullanıcı mesajını düzenledi
callback_querySatır içi düğmeye basıldı (Düğmeler)
message_reactionKullanıcı bir mesaja tepki verdi (**yalnız allowed_updates'te istersen**)
my_chat_memberKullanıcı uygulamanı engelledi / engeli kaldırdı / hesabını sildi; bildirim sıklığını değiştirdi
poll, poll_answerAnket durumu değişti / kullanıcı oy verdi
pre_checkout_queryÖdeme onayı bekleniyor — 10 sn içinde yanıtla (Ödemeler)
shipping_queryFiziksel ürün kargo sorgusu
purchased_paid_mediaÜcretli içerik satın alındı
subscriptionAbonelik durumu değişti
managed_botYönettiğin bir alt bot açıldı
stopped_message_generationKullanıcı akışlı yanıtı "Durdur"la kesti
widget_queryWidget veri istedi

inkiveta'ya özel update'ler — yalnız allowed_updates listesine açıkça yazarsan gelir (tipli kütüphaneler tanımadığı alanla karşılaşmasın diye):

AlanNe zaman gelir
inki_component_actionKullanıcı bir yerel bileşenle etkileşti (Bileşenler)
inki_feedbackKullanıcı uygulamanın bir mesajına 👍 / 👎 verdi (rating = begendi ya da begenmedi, isteğe bağlı text ≤ 500, message_id)
inki_data_deletion_requestKullanıcı verilerinin silinmesini istedi — istemesen de her zaman gelir (Veri silme)
inki_damla_call_resultDamla araması bitti: sonuç, ücret, alan cevapları, onaylı notlar (Damla aramaları)
inki_notification_settingsKullanıcı uygulamanın bildirimlerini ya da bir bildirim kategorisini açtı/kapattı (Mini App bildirimleri)
inki_call_accessKullanıcı Damla arama iznini verdi ya da kapattı (Damla aramaları)
inki_game_roomBir oyun odası kapandı: sebep, koltuklar ve kimin oynadığı; oyun içeriği taşımaz (Oyun odaları)
inki_marketing_optoutKullanıcı pazarlama aramasını reddetti; 3 iş günü içinde İYS'ye işle — istemesen de her zaman gelir (Damla aramaları)

allowed_updates boşsa ya da hiç verilmediyse message_reaction ve inkiveta uzantıları dışındaki tüm türler gelir.

python-telegram-bot'ta uzantı alanını okumak: kütüphane tanımadığı alanları update.api_kwargs içine koyar:

pythonfrom telegram.ext import TypeHandler

async def her_update(update, context):
    eylem = update.api_kwargs.get("inki_component_action")
    silme = update.api_kwargs.get("inki_data_deletion_request")
    ...

app.add_handler(TypeHandler(Update, her_update), group=-1)
app.run_polling(allowed_updates=["message", "callback_query", "inki_component_action", "inki_feedback"])

grammY ve Telegraf'ta ham update ctx.update içindedir (ctx.update.inki_component_action).

Dosya indirmek#

Kullanıcı fotoğraf ya da belge gönderdiğinde mesajda bir file_id gelir. İndirmek için:

bashcurl -s "https://app.inkiveta.com/bot$BOT_TOKEN/getFile?file_id=AgACAgQAAxk..."
# → {"ok":true,"result":{"file_id":"…","file_unique_id":"…","file_size":48211,"file_path":"photos/file_12.jpg"}}
curl -s -o foto.jpg "https://app.inkiveta.com/file/bot$BOT_TOKEN/photos/file_12.jpg"

file_path göreli döner; en çok 20 MB indirebilirsin. file_id'yi aynı uygulama ve ortamda tekrar göndermek için kullanabilirsin; file_unique_id uygulamalar arasında da sabittir.