Konular API (v1)¶

Hotline CRM'i harici sistemlerle programatik entegrasyonu için REST API.

Diyaloglar hakkında bilgi alın ve backend grup konularına mesajlar gönderin.

Ücretli özellik

Webhooks ve REST API kullanımı yalnızca Hotline premium kullanıcıları için mevcuttur. Sistemin ücretli sürümünü satın almak için destek servisimize başvurun.

API Yetenekleri¶

Konu bilgisi alma — diyalog verisi, durum, kullanıcı veya sohbet bilgisi
Konulara mesaj gönderme — belirtilen user_id için operatörler için konulara mesaj gönderme

Endpoint¶

https://n8n.production.hotline.tg/webhook/topic_action

Gereksinimler:

	Açıklama
İstek metodu	`POST`
HTTP-Header	Bağlantı sahibinin erişim token'ı ile `X-API-KEY` (destek servisi tarafından verilir)
Body:	Belirli bağlantının `instance` ve `api_key` alanlarıyla JSON (kurulum botundan alınır)

Metod: Konu Bilgisi Alma¶

info_by_topic metodu konu tanımlayıcılarına göre diyalog hakkında tam bilgi döndürür.

Örnek POST isteği

{
  "action": "info_by_topic",
  "group_id": "2101424779",
  "topic_id": 5343,
  "instance": "13209946874612345",
  "api_key": "pQTngMZLh0NmAh"
}

Linkten ID çıkarma

Konu linki: https://t.me/c/2101424779/5343
→ group_id: 2101424779
→ topic_id: 5343

Kullanıcı konusu için örnek yanıt

{
  "result": "topic_info",

  "group_id": "2101424779",
  "topic_id": 5343,

  "frontend_type": "private",
  "instance_name": "support_bot",
  "instance_frontend_user_id": 123456789,
  "instance_id": "132099468746812345",

  "chat_id": -1002101424779,
  "thread_id": 5602541568,

  "topic_last_date": "2025-10-09 00:24:55",
  "topic_status": "user_answered",
  "topic_title": "John Doe",

  "user_id": 987654321,
  "user_name": "John Doe",
  "user_first_name": "John",
  "user_last_name": "Doe",
  "user_username": "john1991",
  "user_lang": "en",
  "user_phone": "+12125550123"
}

Sohbet konusu için örnek yanıt

{
  "result": "topic_info",

  "group_id": "2101424779",
  "topic_id": 5344,

  "frontend_type": "group",
  "instance_name": "support_bot",
  "instance_frontend_user_id": 123456789,
  "instance_id": "132099468746812345",

  "frontend_chat_id": -1001234567890,

  "topic_last_date": "2025-10-09 00:30:00",
  "topic_status": "support_answered",
  "topic_title": "Somebiz Proposal Chat"
}

Çoklu bağlantılar

Sisteme birden fazla frontend bağlıysa, bilgi almak için herhangi birini kullanabilirsiniz
Yanıt belirli konunun hangi bağlantıya ait olduğunu gösterecektir

Metod: Konuya Mesaj Gönderme¶

incoming_in_topic metodu belirtilen kullanıcının diyaloğu ile konuda operatörler için mesaj oluşturur.

Örnek istek

{
  "action": "incoming_in_topic",
  "user_id": 987654321,
  "message": "Kullanıcı durumu değişti: ANLAŞMA ONAYLANDI",
  "instance": "13209946874612345",
  "api_key": "pQTngMZLh0NmAh"
}

Örnek yanıt

{
  "result": "message_sent",
  "topic_link": "https://t.me/c/2101424779/5343",
  "message": "Kullanıcı durumu değişti: ANLAŞMA ONAYLANDI",
  "chat_id": "-1002101424779",
  "thread_id": 5602541568
}

Öneriler¶

x-api-key ve api_key'i güvenli yerde saklayın (ortam değişkenleri, secrets)
Tüm API istekleri için HTTPS kullanın
Denetim için tüm API isteklerini kaydedin
Exponential backoff ile retry logic uygulayın
İstek zaman aşımını en az 10 saniye olarak ayarlayın
Toplu işlemler yaparken rate limiting frekansını düşünün
Maksimum mesaj boyutu — 4096 karakter (Telegram sınırlaması)

Erişim Alma¶

x-api-key token'ını almak ve Konular API'sini bağlamak için:

Destek servisine yazın
API kullanım senaryonuzu kısaca açıklayın
Erişim token'ı x-api-key ve teknik danışmanlık alın