narX'i kendi sistemine bağla

Başlarken

narX'te @botfather ile sohbet aç ve /newbot yaz. Botun adını ve sonu bot ile biten kullanıcı adını (ör. nobet_bot) ver; sana bir token gönderir. Token botun parolasıdır, kimseyle paylaşma; sızarsa /token ile yenile. Aynı işlemleri web'de menü → Botlarım ekranından da yapabilirsin.

# Token doğru mu?
curl https://web.narx.tr/bot/v1/$TOKEN/getMe
# → {"ok":true,"result":{"id":"318","username":"nobet_bot","name":"Nöbet Botu","is_bot":true}}

Botu bir gruba yalnızca grup yöneticisi ekleyebilir. Birebir sohbet için kullanıcı botun kullanıcı adını aratıp yazar.

İstek ve yanıt

Adres: https://web.narx.tr/bot/v1/<TOKEN>/<yöntem>. GET (sorgu parametreleri) ya da POST (JSON gövde) kullanabilirsin. Başarılı yanıt {"ok": true, "result": …}, hata {"ok": false, "error_code": 400, "description": "…"} biçimindedir. Kimlikler metin olarak döner.

Yöntemler

Güncellemeler

Bot iki tür güncelleme alır: message (metin; varsa files listesi) ve callback_query (düğme basımı). getUpdates ile aldıktan sonra bir sonraki çağrıda offset = son update_id + 1 vererek onayla.

curl "https://web.narx.tr/bot/v1/$TOKEN/getUpdates?timeout=25&offset=813"
{ "ok": true, "result": [{
  "update_id": 813,
  "message": {
    "message_id": "90211", "text": "rapor",
    "chat": { "id": "2492", "type": "private" },
    "from": { "id": "57", "username": "ayse", "is_bot": false },
    "files": [{ "file_id": "7731", "file_name": "tablo.xlsx", "file_size": 48211 }]
  } }] }

Düğmeler

reply_markup.inline_keyboard en çok 8 satır × 4 düğmedir. Her düğme ya callback_data (≤64 bayt, bota geri döner) ya da url (yalnızca https, bağlantıyı açar) taşır.

# Düğmeye basılınca gelen güncelleme
{ "update_id": 814, "callback_query": { "id": "Xk2…", "data": "ok", "from": { … }, "message": { "message_id": "90230" } } }

# Basan kişiye bildirim göster, mesajı güncelle
curl -X POST https://web.narx.tr/bot/v1/$TOKEN/answerCallbackQuery -H 'content-type: application/json' \
  -d '{"callback_query_id":"Xk2…","text":"Onaylandı ✓"}'
curl -X POST https://web.narx.tr/bot/v1/$TOKEN/editMessageText -H 'content-type: application/json' \
  -d '{"message_id":"90230","text":"Nöbet onaylandı: Dr. Mert K.","reply_markup":{"inline_keyboard":[]}}'

Dosyalar

Dosyayı ya genel bir https adresiyle (sunucumuz indirir; yerel ve özel ağ adresleri reddedilir) ya da ham gövde olarak gönder. İçerik türü sunucuda tespit edilir; sendPhoto resim olmayanı reddeder.

# Ham gövde ile
curl -X POST "https://web.narx.tr/bot/v1/$TOKEN/sendDocument?chat_id=2492&filename=rapor.pdf&caption=Günlük%20rapor" \
  -H 'content-type: application/pdf' --data-binary @rapor.pdf

# Adres ile
curl -X POST https://web.narx.tr/bot/v1/$TOKEN/sendPhoto -H 'content-type: application/json' \
  -d '{"chat_id":"2492","photo":"https://ornek.com/grafik.png","caption":"Haftalık grafik"}'

Webhook

setWebhook ile bir https adres ver; her güncelleme o adrese JSON olarak POST edilir. İstek X-Iletx-Signature: sha256=<hex> başlığı taşır: gövdenin, verdiğin secret ile HMAC-SHA256 özeti. Sunucun 5 sn içinde 2xx dönmezse güncelleme kuyrukta kalır ve 24 saat boyunca getUpdates ile alınabilir. Yerel ve özel ağ adresleri güvenlik nedeniyle kabul edilmez.

curl -X POST https://web.narx.tr/bot/v1/$TOKEN/setWebhook -H 'content-type: application/json' \
  -d '{"url":"https://ornek.com/iletx","secret":"uzun-rastgele-bir-deger"}'

// Node.js: imzayı doğrula
import { createHmac, timingSafeEqual } from 'node:crypto';
const dogru = (govde, baslik, secret) => {
  const beklenen = Buffer.from('sha256=' + createHmac('sha256', secret).update(govde).digest('hex'));
  const gelen = Buffer.from(baslik ?? '');
  return gelen.length === beklenen.length && timingSafeEqual(gelen, beklenen);
};

Gizlilik modu

Varsayılan olarak açıktır: botlar gruplarda yalnızca /komut ile başlayan mesajları, kendilerinin anıldığı (@nobet_bot) mesajları ve kendi mesajlarına verilen yanıtları görür. Birebir sohbette her mesajı alır. Botlar birbirlerinin mesajlarıyla tetiklenmez.

Sınırlar

• Bot başına, sohbet başına dakikada en çok 30 mesaj (aşılırsa 429 ve retry-after).
• Kullanıcı başına en çok 10 bot; grup başına en çok 10 entegrasyon.
• Metin en çok 4000 karakter; dosya boyutu hesap sınırlarına tabidir.

Kodsuz entegrasyon

Bot yazmak istemiyorsan: grup bilgisi → Entegrasyonlar → ad yaz → Oluştur. Sana yalnızca bir kez gösterilen gizli bir adres verilir. İzleme sistemin, form aracın ya da otomasyonun bu adrese yazdığında mesaj, entegrasyonun adıyla (BOT rozetli) gruba düşer. Bu mesajlar grubun mesai saatlerinden etkilenmez.

curl -X POST https://web.narx.tr/hook/$KOD -H 'content-type: application/json' \
  -d '{"title":"Yeni sipariş","text":"#4821 · 3 ürün · ₺1.240"}'

Aynı bölümdeki Zamanlanmış mesajlar ile bir kez, her gün, hafta içi ya da haftanın seçili günlerinde (Türkiye saati) otomatik duyuru gönderebilirsin.