Telegram

Funktionsweise

Beim Erstellen einer Inbound-Telegram-Verbindung registriert connic mit dem Bot Token einen Webhook bei Telegram. Telegram sendet Updates zu Nachrichten, bearbeiteten Nachrichten und Callback Queries an die Verbindung. connic prüft jede Anfrage, extrahiert die Update-Details und startet verknüpfte Agenten.

Hat der Bot bereits einen Webhook eines anderen Dienstes, ersetzt connic ihn und schreibt die vorherige URL in die Verbindungs-Logs. Ein Bot, den bereits eine andere connic-Verbindung verwendet, lässt sich nicht erneut verbinden.

Einrichtung

1. 1

   Bot mit @BotFather erstellen

   Öffne Telegram und schreibe an @BotFather. Sende /newbot, folge den Anweisungen und kopiere das Bot Token (Format: 123456:ABC-DEF...).

2. 2

   Verbindung erstellen

   Erstelle in connic eine neue Telegram-Verbindung im Inbound Mode und füge das Bot Token ein. Optional lässt sich außerdem eine Liste erlaubter Telegram-Nutzer-IDs hinzufügen. Bleibt sie leer, akzeptiert die Verbindung Nachrichten von allen Personen, die den Bot erreichen können.

3. 3

   Agenten verknüpfen

   Verknüpfe die Verbindung mit einem Agenten. Akzeptierte Telegram-Updates starten diesen Agenten mit der Update-Payload als Input.

Agent-Input-Payload

Der Agent erhält eine strukturierte Payload mit den wichtigsten Feldern auf oberster Ebene sowie das vollständige ursprüngliche Telegram-Update-Objekt:

{
  "update_id": 123456789,
  "text": "Wie ist der Status meiner Bestellung?",
  "chat_id": 987654321,
  "message": {
    "message_id": 42,
    "text": "Wie ist der Status meiner Bestellung?",
    "date": 1700000000,
    "chat_id": 987654321,
    "chat_type": "private",
    "from_id": 987654321,
    "from_username": "johndoe",
    "from_first_name": "John",
    "from_last_name": "Doe"
  },
  "raw": {
    "update_id": 123456789,
    "message": { ... }
  }
}

Mediennachrichten

Fotos, Sprachnachrichten, Audio, Videos, Videonachrichten, Dokumente und Animationen werden heruntergeladen, sofern verfügbar. Pro Nachricht oder Album nimmt connic bis zu 10 vollständige Dateien an. Es gelten 10 MiB pro Datei und ein gemeinsames Downloadbudget von 10 MiB. Bei Fotos wird die größte Variante verwendet. Jedes heruntergeladene Element erscheint in files mit name, mime_type, Base64-kodierten Inhalten unter data und der Größe in Byte unter size.

Album-Updates werden gesammelt, bis zwei Sekunden lang kein neues Element eingetroffen ist. Danach werden sie in Nachrichtenreihenfolge zu einem Run pro verknüpftem Agenten zusammengefasst. Bildunterschriften bleiben in text erhalten; messages und raw_updates enthalten die einzelnen Nachrichten. Wiederholte Zustellungen erzeugen keinen weiteren Run. Neue Elemente, die nach dem Ende der Sammlung eintreffen, werden ausgelassen. Die Webhook-Antwort und das Verbindungsprotokoll weisen dies mit album_closed aus.

Ungültige oder nicht verfügbare optionale Dateien lässt connic einzeln aus. Sobald eine Datei die Anzahl- oder Größenbegrenzung überschreitet, bleiben die bereits angenommenen Dateien erhalten; diese Datei und alle folgenden werden ausgelassen. Im Input enthält file_issues die Auslassungen mit einem stabilen code, einer Meldung und den jeweiligen Grenzwerten. Die Nachricht oder das Album wird auch ohne angenommene Dateien als Agenten-Run eingereiht, sofern Anhänge für diese Agentenverknüpfung optional sind.

Beispiel-Agent

version: "1.0"
name: telegram-assistant
description: "Beantwortet eingehende Telegram-Nachrichten"
model: connic/gpt-5.6-terra
system_prompt: |
  Du bist ein Telegram-Assistent. Beantworte Fragen klar und präzise.

# Die eingehende Telegram-Nachricht wird als Input an den Agenten übergeben.
# input["text"]        - Nachrichtentext des Nutzers
# input["chat_id"]     - Telegram-Chat-ID (für die Outbound-Antwort beibehalten)
# input["message"]     - vollständiges Nachrichtenobjekt mit Absenderdetails

Funktionsweise

Automatische Outbound-Verbindungen senden die finale Ausgabe eines abgeschlossenen Runs und können auf ausgewählte Inputs begrenzt werden. Agent-Tool- und Middleware-Outbound-Verbindungen senden nur bei einem Aufruf. connic ermittelt das Ziel und formatiert die Telegram-API-Anfrage, ohne Bot Token oder gespeicherte Chat ID offenzulegen.

Agent-Tool- und Middleware-Outbound-Verbindungen

Eine Agent-Tool-Outbound-Verbindung stellt einen bearbeitbaren Tool-Namen bereit, standardmäßig send_to_<connector_name>. Rufe eine Middleware-Outbound-Verbindung über send_connector mit ihrem konfigurierten Namen auf. Beide verwenden das folgende Payload-Schema. text ist erforderlich; chat_id akzeptiert einen String oder Integer und ist optional, wenn eine andere Route verfügbar ist.

{
  "text": "Deine Bestellung #12345 ist unterwegs!",
  "chat_id": 987654321
}

Automatisches Ausgabeformat

Bestehende automatische Outbound-Verbindungen behalten das bisherige Verhalten bei und bleiben für alle Runs aktiviert. Der Agent kann JSON mit einem text-Feld zurückgeben (akzeptiert werden auch message oder body) sowie optional eine chat_id. Ein einfacher String wird ebenfalls als Nachrichtentext gesendet. Für beide Formate wird der Ziel-Chat in der folgenden Reihenfolge ermittelt. Nachrichten werden immer mit parse_mode: HTML gesendet, sodass HTML-Formatierung dargestellt wird.

{
  "chat_id": 987654321,
  "text": "Deine Bestellung #12345 ist unterwegs! Voraussichtliche Lieferung: morgen bis 6 Uhr abends."
}

Agentenbeispiel für eine automatische Outbound-Verknüpfung

version: "1.0"
name: telegram-support
description: "Beantwortet Support-Nachrichten aus Telegram"
model: connic/gpt-5.6-terra
system_prompt: |
  Du bist ein hilfreicher Agent für den Kundensupport.
  Antworte immer mit JSON, das Folgendes enthält:
    - "chat_id": die chat_id aus dem Input
    - "text": deine Antwortnachricht

# Auf eingehende Nachricht zugreifen:
# input["text"]        - Nachrichtentext
# input["chat_id"]     - Chat-ID des Absenders (für Antwort erforderlich)
# input["message"]     - vollständige Nachrichtendetails