Topics API (v1)¶

Veraltete API-Version

Topics API v1 ist veraltet und ihre Unterstützung wird in Kürze eingestellt. Verwenden Sie diese Version nicht für neue Integrationen.

Wechseln Sie zu Public API v2. Der aktuelle Methodenumfang, Datenmodelle und Anfragebeispiele sind in der interaktiven Hotline API-Dokumentation verfügbar.

REST-API für die programmgesteuerte Integration von Hotline CRM mit externen Systemen.

Erhalten Sie Informationen über Dialoge und senden Sie Nachrichten an Backend-Gruppenthemen.

Kostenpflichtige Funktion

Die Nutzung von Webhooks und REST-API ist nur für Hotline Premium-Nutzer verfügbar. Um die kostenpflichtige Version des Systems zu erwerben, kontaktieren Sie unseren Supportdienst.

API-Funktionen¶

Themeninformationen abrufen — Dialogdaten, Status, Benutzer- oder Chat-Informationen
Nachrichten an Themen senden — Nachrichten an Themen für Operatoren nach angegebener user_id senden

Endpunkt¶

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

Anforderungen:

	Beschreibung
Anfragemethode	`POST`
HTTP-Header	`X-API-KEY` mit Zugriffstoken des Verbindungsbesitzers (vom Supportdienst ausgestellt)
Body:	JSON mit `instance`- und `api_key`-Feldern der spezifischen Verbindung (im Setup-Bot erhalten)

Methode: Themeninformationen abrufen¶

Die Methode info_by_topic gibt vollständige Informationen über einen Dialog anhand von Themenidentifikatoren zurück.

Beispiel POST-Anfrage

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

ID aus Link extrahieren

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

Beispiel-Antwort für Benutzerthema

{
  "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"
}

Beispiel-Antwort für Chat-Thema

{
  "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"
}

Mehrere Verbindungen

Falls mehrere Frontends mit dem System verknüpft sind, können Sie jedes von ihnen verwenden, um Informationen zu erhalten
Die Antwort zeigt an, zu welcher Verbindung das spezifische Thema gehört

Methode: Nachricht an Thema senden¶

Die Methode incoming_in_topic erstellt eine Nachricht für Operatoren im Thema mit dem Dialog des angegebenen Benutzers.

Beispielanfrage

{
  "action": "incoming_in_topic",
  "user_id": 987654321,
  "message": "User status is changed: DEAL CONFIRMED",
  "instance": "13209946874612345",
  "api_key": "pQTngMZLh0NmAh"
}

Beispiel-Antwort

{
  "result": "message_sent",
  "topic_link": "https://t.me/c/2101424779/5343",
  "message": "User status is changed: DEAL CONFIRMED",
  "chat_id": "-1002101424779",
  "thread_id": 5602541568
}

Empfehlungen¶

Speichern Sie x-api-key und api_key an einem sicheren Ort (Umgebungsvariablen, Secrets)
Verwenden Sie HTTPS für alle API-Anfragen
Protokollieren Sie alle API-Anfragen für Auditing
Implementieren Sie Retry-Logik mit Exponential Backoff
Setzen Sie das Anforderungs-Timeout auf mindestens 10 Sekunden
Berücksichtigen Sie Rate Limiting bei Massenoperationen
Maximale Nachrichtengröße — 4096 Zeichen (Telegram-Einschränkung)

Zugriff erhalten¶

Um das x-api-key-Token zu erhalten und die Topics API anzubinden:

Schreiben Sie an den Supportdienst
Beschreiben Sie kurz Ihr API-Nutzungsszenario
Erhalten Sie Zugriffstoken x-api-key und technische Beratung