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:
| Yol | Ne 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şilemiyorsa | Aynı anda tek bir yoklayıcı |
| Akış editörü | Sunucun yoksa; sohbet botu inkiveta'da çalışır | Akış yayındayken diğer ikisi 409 döner (Akış editörü) |
Dikkat: Gerçek ortamda webhook ya da
getUpdateskullanabilmek 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.idher zamanfrom.id'ye eşittir vechat.typeher zaman"private"'dır.from.iduygulamaya ö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 kelimelast_name; tek kelimeyselast_nameyok), vermediysefirst_name= "Kullanıcı".usernameyalnı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ı
httpsolmalı; 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_addressverirsen o da aynı kurallarla denetlenir. - Kendinden imzalı sertifika kullanıyorsan
certificateile 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
getWebhookInfoyanıtındakilast_error_date/last_error_messagealanları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: truebekleyen 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"
timeouten çok 50 sn: bu süre boyunca yeni update gelirse hemen döner, gelmezse boş liste döner.offset= son aldığınupdate_id + 1. Bu, öncekileri onaylar ve siler. Onaylanmayan update 24 saat sonra düşer.limit1–100. Negatifoffsetsondan sayar.allowed_updatesbir 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 runningile 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. ÖncedeleteWebhookçağır.
Update türleri#
| Alan | Ne zaman gelir |
|---|---|
message | Kullanıcı mesaj, medya, konum, kişi gönderdi; ödeme tamamlandı (successful_payment); Mini App veri gönderdi (web_app_data) |
edited_message | Kullanıcı mesajını düzenledi |
callback_query | Satır içi düğmeye basıldı (Düğmeler) |
message_reaction | Kullanıcı bir mesaja tepki verdi (**yalnız allowed_updates'te istersen**) |
my_chat_member | Kullanıcı uygulamanı engelledi / engeli kaldırdı / hesabını sildi; bildirim sıklığını değiştirdi |
poll, poll_answer | Anket durumu değişti / kullanıcı oy verdi |
pre_checkout_query | Ödeme onayı bekleniyor — 10 sn içinde yanıtla (Ödemeler) |
shipping_query | Fiziksel ürün kargo sorgusu |
purchased_paid_media | Ücretli içerik satın alındı |
subscription | Abonelik durumu değişti |
managed_bot | Yönettiğin bir alt bot açıldı |
stopped_message_generation | Kullanıcı akışlı yanıtı "Durdur"la kesti |
widget_query | Widget 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):
| Alan | Ne zaman gelir |
|---|---|
inki_component_action | Kullanıcı bir yerel bileşenle etkileşti (Bileşenler) |
inki_feedback | Kullanıcı uygulamanın bir mesajına 👍 / 👎 verdi (rating = begendi ya da begenmedi, isteğe bağlı text ≤ 500, message_id) |
inki_data_deletion_request | Kullanıcı verilerinin silinmesini istedi — istemesen de her zaman gelir (Veri silme) |
inki_damla_call_result | Damla araması bitti: sonuç, ücret, alan cevapları, onaylı notlar (Damla aramaları) |
inki_notification_settings | Kullanıcı uygulamanın bildirimlerini ya da bir bildirim kategorisini açtı/kapattı (Mini App bildirimleri) |
inki_call_access | Kullanıcı Damla arama iznini verdi ya da kapattı (Damla aramaları) |
inki_game_room | Bir oyun odası kapandı: sebep, koltuklar ve kimin oynadığı; oyun içeriği taşımaz (Oyun odaları) |
inki_marketing_optout | Kullanı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.