Webhooks¶

Empfangen Sie Ereignisse aus Hotline-Dialogen als POST-Anfragen im JSON-Format für die Integration mit Ihren Systemen.

Funktionen¶

Das Webhooks-Modul ermöglicht:

• Systemereignisse verfolgen — Dialogerstellung, Schließung und Wiedereröffnung, Nachrichtenempfang und -versand.
• Benutzerdefinierte Befehle verarbeiten — sowohl Standard /mark, /info als auch Ihre eigenen /invoice, /user und beliebige andere.
• Antworten an Themen zurückgeben — Ergebnisse der Befehlsausführung können direkt in Kundenthemen angezeigt werden.

Konfiguration¶

Webhooks werden über den Setup-Bot @hotlinetg_bot im Verbindungsparameter WEBHOOKS konfiguriert.

Konfigurationsformat: JSON-Objekt, bei dem Schlüssel URLs Ihrer Skripte sind und Werte Arrays von zu verfolgenden Ereignissen:

Beispiel JSON-Konfiguration¶

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

Systemereignisse¶

Automatische Benachrichtigungen über Dialogereignisse. Werden gesendet, ohne auf eine Antwort von Ihrem Server zu warten.

Verfügbare Dialogereignisse¶

Verfügbare Nachrichtenereignisse¶

Nutzungsszenarien¶

• Senden automatischer Nachrichten nach Timeout nach Dialogstart
• Überwachung der Reaktionszeit der Operatoren auf Anfragen
• Überprüfung von Nachrichten auf Übereinstimmung mit Unternehmensrichtlinien
• Sammlung von Daten für externe Analysen
• Aufzeichnung von Dialogen für KI-Modell-Training
• Duplizierung von Nachrichten in Unternehmensdatenbank

Beispielanfrage: Dialogwiedereröffnung¶

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

Beispielanfrage: Gesendete Nachricht¶

{
  "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 message",
    "content_type": "messageText",
    "department": "default",
    "backend_reply_message_id": 0
  },
  "api_key": "pQTngMZLh0NmAh"
}

Benutzerdefinierte Befehle¶

Ereignisse über Befehlsaufrufe von Operatoren. Ihr Server kann das entsprechende Ereignis protokollieren und eine Antwort zurückgeben, die im Dialogthema angezeigt wird.

• Geben Sie Standard-Systembefehle in der JSON-Konfiguration an: /info, /mark, /close
• Setzen Sie Ihre eigenen Befehle: /invoice, /client, /order
• Geben Sie das Ausführungsergebnis als Text oder JSON zurück, falls erforderlich

Nutzungsszenarien¶

• Erweitern von /info mit zusätzlichen Kundeninformationen aus einem anderen CRM
• Protokollierung von Statusänderungen über /mark für Analysen
• Erstellen einer Rechnung mit dem Befehl /invoice mit Linkrückgabe
• Abrufen von Kundendaten aus Datenbank mit /user
• Automatisierung von Geschäftsprozessen durch Befehlsauslöser

Beispielanfrage: Befehl /mark¶

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

Antwortformat¶

Ihr Server kann das Ergebnis als Klartext oder JSON mit message- oder error-Knoten zurückgeben.

Erfolgreiche Ausführung:

{
  "message": "Deal created: http://internal.domain.com/crm/deals/76238",
  "status": "ok"
}

Ausführungsfehler:

{
  "error": "User 12345678 not found in our database"
}

Textantwort:

Sie können einfach Text mit Markdown v2-Unterstützung zurückgeben:

✅ Invoice №12345 created
Total: 1500
Link: https://intranet.example.com/invoice/12345

Sicherheit¶

Alle Anfragen von Hotline enthalten das Feld api_key der entsprechenden Verbindung zur Absenderverifizierung.

• Überprüfen Sie api_key auf Ihrer Seite
• Konfigurieren Sie Filterung nach Hotline-Proxy-Server-IP
• Verwenden Sie HTTPS für Webhooks-URL

Praktische Szenarien¶

Debugging-Tipps¶

1. Verwenden Sie Dienste zum Testen von Webhooks: postman.com, requestbin.com
2. Protokollieren Sie alle eingehenden Anfragen auf Ihrem Server
3. Geben Sie korrekten HTTP-Antwortstatus zurück (sollte 200 OK sein)
4. Überwachen Sie das Timeout — die Antwort sollte schnell kommen (empfohlen bis zu 3 Sekunden)
5. Behandeln Sie Fehler ordnungsgemäß und geben Sie verständliche Meldungen zurück

Einschränkungen¶

• Timeout für Befehlsantwort — empfohlen nicht mehr als 3 Sekunden
• Antwortgröße — bis zu 4096 Zeichen (Telegram-Einschränkung)
• Wiederholungsversuche — wenn Ihr Server nicht verfügbar ist, kann die Anfrage wiederholt werden
• Rate Limits — bei großem Ereignisfluss berücksichtigen Sie die Kapazitäten Ihres Servers

Support¶

Für Fragen zur Webhook-Einrichtung, Verbindung kostenpflichtiger Abonnements, kontaktieren Sie den Supportdienst @hotlinetg_support