Webhook'lar¶

Sisteminizle entegrasyon için Hotline diyaloglarından gelen olayları JSON formatında POST istekleri olarak alın.

Yetenekler¶

Webhooks modülü şunları sağlar:

• Sistem olaylarını izleme — diyalog oluşturma, kapatma ve yeniden açma, mesaj alma ve gönderme.
• Özel komutları işleme — hem standart /mark, /info hem de kendi /invoice, /user ve diğer komutlarınız.
• Konulara yanıt döndürme — komut yürütme sonuçları doğrudan müşteri konularında gösterilebilir.

Yapılandırma¶

Webhook'lar @hotlinetg_bot kurulum botu aracılığıyla WEBHOOKS bağlantı parametresinde yapılandırılır.

Yapılandırma formatı: Anahtarların script'lerinizin URL'leri ve değerlerin izlenecek olay dizileri olduğu JSON objesi:

Örnek JSON Yapılandırması¶

{
  "https://someapiserver.com/webhooks/test-hook1": [
    "dialog_created",
    "dialog_reopened", 
    "dialog_closed",
    "message_received",
    "message_sent",
    "message_intercepted"
  ],
  "https://someapiserver.com/webhooks/test-hook2": [
    "/mark", "/info",
    "/invoice", "/client"
  ]
}

Sistem Olayları¶

Diyalog olayları hakkında otomatik bildirimler. Sunucunuzdan yanıt beklemeden gönderilir.

Mevcut Diyalog Olayları¶

Mevcut Mesaj Olayları¶

Kullanım Senaryoları¶

• Diyalog başlangıcından sonra zaman aşımıyla otomatik mesaj gönderme
• İsteklere operatör yanıt süresini izleme
• Şirket politikasına uygunluk için mesajları kontrol etme
• Harici analitik için veri toplama
• Yapay zeka model eğitimi için diyalogları kaydetme
• Mesajları kurumsal veritabanına yedekleme

Örnek İstek: Diyalog Yeniden Açma¶

{
  "event_type": "dialog_reopened",
  "timestamp": "2025-10-09 00:24:55",
  "instance_id": "13209946874612345",
  "data": {
    "chat_id": -1002146012345,
    "thread_id": 5602541568,
    "topic_id": 5343,
    "topic_link": "https://t.me/c/2146012345/5343",
    "user_id": 5339212345,
    "frontend_chat_id": 5339212345,
    "frontend_topic_id": null,
    "frontend_topic_link": null,
    "frontend_user_id": 6406751371,
    "chat_type": "private",
    "title": "Some User Name",
    "department": "default"
  },
  "api_key": "pQTngMZLh0NmAh"
}

Örnek İstek: Gönderilen Mesaj¶

{
  "event_type": "message_sent",
  "timestamp": "2025-10-09 00:21:57",
  "instance_id": "132099468746812345",
  "data": {
    "backend_chat_id": -1002146012345,
    "backend_thread_id": 5602541568,
    "backend_message_id": 6171918336,
    "sender_user_id": 5339212345,
    "frontend_user_id": 640675123,
    "frontend_message_id": 3260022784,
    "text": "test mesajı",
    "content_type": "messageText",
    "department": "default",
    "backend_reply_message_id": 0
  },
  "api_key": "pQTngMZLh0NmAh"
}

Özel Komutlar¶

Operatör komut çağrıları hakkında olaylar. Sunucunuz ilgili olayı kaydedebilir ve diyalog konusunda gösterilecek yanıt döndürebilir.

• JSON yapılandırmasında standart sistem komutlarını belirtin: /info, /mark, /close
• Kendi komutlarınızı ayarlayın: /invoice, /client, /order
• Gerekirse yürütme sonucunu metin veya JSON olarak döndürün

Kullanım Senaryoları¶

• Başka bir CRM'den ek müşteri bilgisiyle /info'yu genişletme
• Analitik için /mark ile durum değişikliklerini kaydetme
• Link dönüşü ile /invoice komutuyla fatura oluşturma
• /user ile veritabanından müşteri verisi alma
• Komut tetikleyici ile iş süreci otomasyonu

Örnek İstek: /mark Komutu¶

{
  "event_type": "/mark",
  "timestamp": "2025-10-08 20:41:20",
  "instance_id": "132099468746812345",
  "data": {
    "command_data": "deal",
    "chat_id": -1002146012345,
    "topic_id": 5,
    "topic_link": "https://t.me/c/2146012345/5",
    "message_id": 5850,
    "reply_message_id": null,
    "sender_user_id": 123456,
    "user_id": 7890123,
    "frontend_chat_id": 7890123,
    "frontend_thread_id": null
  },
  "api_key": "pQTngMZLh0NmAh"
}

Yanıt Formatı¶

Sunucunuz sonucu düz metin veya message veya error düğümleri ile JSON olarak döndürebilir.

Başarılı yürütme:

{
  "message": "Anlaşma oluşturuldu: http://internal.domain.com/crm/deals/76238",
  "status": "ok"
}

Yürütme hatası:

{
  "error": "Kullanıcı 12345678 veritabanımızda bulunamadı"
}

Metin yanıtı:

Markdown v2 desteğiyle sadece metin döndürebilirsiniz:

✅ Fatura №12345 oluşturuldu
Toplam: 1500
Link: https://intranet.example.com/invoice/12345

Güvenlik¶

Hotline'dan gelen tüm istekler gönderen doğrulaması için ilgili bağlantının api_key alanını içerir.

• api_key'i kendi tarafınızda doğrulayın
• Hotline proxy sunucusu IP'sine göre filtreleme yapılandırın
• Webhooks URL'si için HTTPS kullanın

Pratik Senaryolar¶

Hata Ayıklama İpuçları¶

1. Webhook'ları test etmek için servisler kullanın: postman.com, requestbin.com
2. Sunucunuzdaki tüm gelen istekleri kaydedin
3. Doğru HTTP yanıt durumu döndürün (200 OK olmalıdır)
4. Zaman aşımını izleyin — yanıt hızlıca gelmeli (3 saniyeye kadar önerilir)
5. Hataları zarif bir şekilde işleyin ve anlaşılır mesajlar döndürün

Sınırlamalar¶

• Komut yanıt zaman aşımı — önerilen 3 saniyeden fazla olmamalı
• Yanıt boyutu — 4096 karaktere kadar (Telegram sınırlaması)
• Yeniden deneme girişimleri — sunucunuz kullanılamıyorsa, istek yeniden denenebilir
• Hız sınırları — büyük olay akışı ile sunucu kapasitelerinizi düşünün

Destek¶

Webhook kurulumu, ücretli abonelik bağlantısı hakkında sorularınız için destek servisine @hotlinetg_support başvurun