#+TITLE: Channel Telegram (channel-telegram.org)
#+AUTHOR: Agent
#+FILETAGS: :channel:telegram:
#+PROPERTY: header-args:lisp :tangle ../lisp/channel-telegram.lisp

* Channel Telegram

Extracted from gateway-messaging in v0.5.0. Isolated platform — Telegram-specific poll and send logic.

* Overview

The Telegram channel provides bidirectional communication via the Telegram Bot
API. Messages from Telegram chats are injected into the cognitive pipeline as
~:user-input~ signals with ~:source :telegram~. Outbound messages route through
the actuator registry when the pipeline targets ~:telegram~.

The channel uses two functions: ~telegram-poll~ (inbound sensor, getUpdates
with offset tracking) and ~telegram-send~ (outbound actuator, sendMessage).
Both retrieve the bot token from the credentials vault. The polling offset
(~:last-update-id~ in ~*gateway-configs*~) prevents duplicate processing across
poll cycles. HITL commands are intercepted before injection so approval flows
work identically across all channels.

** Contract

1. (telegram-get-token): returns the Telegram bot token from the vault
   (via ~vault-get-secret :telegram~), or nil if not configured.
2. (telegram-poll): polls getUpdates with offset tracking (prevents
   duplicate processing), injects each message as a ~:user-input~ stimulus
   with ~:source :telegram~. Updates ~:last-update-id~ per cycle. Handles
   API and JSON parse errors gracefully. HITL commands are intercepted
   before injection.
3. (telegram-send action context): sends a message via sendMessage.
   Extracts ~:chat-id~ and ~:text~ from the action plist. Logs send
   failures without crashing the pipeline.

* Implementation

#+begin_src lisp
(in-package :passepartout)
(defun telegram-get-token ()
  (vault-get-secret :telegram))

(defun telegram-poll ()
  "Polls Telegram for new messages and injects them into the harness."
  (let* ((token (telegram-get-token)))
    (when token
      (let* ((last-id (getf (gethash "telegram" *gateway-configs*) :last-update-id 0))
             (url (format nil "https://api.telegram.org/bot~a/getUpdates?offset=~a"
                          token (1+ last-id))))
        (handler-case
            (let* ((response (dex:get url))
                   (json (cl-json:decode-json-from-string response))
                   (updates (cdr (assoc :result json))))
              (dolist (update updates)
                (let* ((update-id (cdr (assoc :update--id update)))
                       (message (cdr (assoc :message update)))
                       (chat (cdr (assoc :chat message)))
                       (chat-id (cdr (assoc :id chat)))
                       (text (cdr (assoc :text message))))
                  (setf (getf (gethash "telegram" *gateway-configs*) :last-update-id) update-id)
                  (when (and text chat-id)
                    (log-message "TELEGRAM: Received message from ~a" chat-id)
                    (unless (ignore-errors (hitl-handle-message text :telegram))
                      (stimulus-inject
                       (list :type :EVENT
                             :meta (list :source :telegram :chat-id (format nil "~a" chat-id))
                             :payload (list :sensor :user-input :text text))))))))
          (error (c) (log-message "TELEGRAM POLL ERROR: ~a" c)))))))

(defun telegram-send (action context)
  "Sends a message via Telegram."
  (declare (ignore context))
  (let* ((payload (getf action :payload))
         (meta (getf action :meta))
         (chat-id (or (getf meta :chat-id) (getf payload :chat-id) (getf action :chat-id)))
         (text (or (getf payload :text) (getf action :text)))
         (token (telegram-get-token)))
    (when (and token chat-id text)
      (handler-case
          (let ((url (format nil "https://api.telegram.org/bot~a/sendMessage" token)))
            (dex:post url
                      :headers '(("Content-Type" . "application/json"))
                      :content (cl-json:encode-json-to-string
                                `((chat_id . ,chat-id) (text . ,text)))))
        (error (c) (log-message "TELEGRAM ERROR: ~a" c))))))
#+end_src


#+end_src