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.

Einrichtung

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. 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.

Beispiel-Agent

name: telegram-assistant
model: connic/gpt-5.6-terra
system: |
  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

name: telegram-support
model: connic/gpt-5.6-terra
system: |
  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