Skip to content
Kodakodadocs
Integrations

Telegram

Wire up a Telegram agent and control access.

Telegram is Koda's production pilot channel. It pairs cleanly with the runtime and the channel gateway: approved identities DM or mention an agent bot, the gateway evaluates the sender before enqueue, the handler normalises the message into a runtime request, the task executes, and the reply returns in the same chat.

What you get

  • A one-to-one or group-mentioned chat interface per agent. Users DM the bot or mention it in an approved group; the bot replies.
  • Channel gateway identity enforced before runtime work starts. Unknown senders are queued for review; blocked or revoked identities fail closed.
  • Full runtime trace for every Telegram message. The dashboard shows the same transcript an operator sees, plus the tool calls and memory writes underneath.
  • The /skill command works natively in Telegram — same names, same auto-selection rules, same token budgets.

Setting up a Telegram agent

  1. Create a bot with BotFather

    Open Telegram, find @BotFather, and run /newbot. Pick a display name, pick a username ending in bot, and copy the token BotFather hands back. Koda never sees your BotFather account — only the token.

  2. Open the Telegram wizard in the dashboard

    On the home dashboard the setup checklist offers a Connect Telegram step. The drawer that opens asks for the bot token and the agent you want to bind it to.

  3. Paste the bot token

    Koda verifies the token against Telegram's getMe endpoint before saving it. A bad token fails here, not at message-delivery time.

  4. Pick the agent

    One agent per bot. Multiple agents can coexist — each bot binds to exactly one — but the first setup is one bot, one agent.

  5. Decide who can reach it

    Create a pairing code or approve identities from the channel gateway. Legacy allowed Telegram IDs remain compatible, but an empty allowlist is fail-closed and blocked/revoked gateway identities override legacy allow.

Access policy

Telegram access is controlled by channel_gateway.v1 before the runtime queue. The runtime never sees messages from identities that are unknown, blocked, revoked, or outside the legacy allowlist.

  • Identity scope — Koda keys channel identity by agent, channel type, channel id, and user id, not by display name.
  • Pairing codes — a short-lived code can approve a sender, but the code message itself is discarded and not enqueued as a task.
  • Unknown sender queue — denied senders create pending review records with redacted previews so operators can approve or block deliberately.
Rejected attempts are denied before enqueue
Rejected messages write channel gateway audit/metric events and do not create runtime tasks. If the feed fills up with one sender, block that identity in Koda and consider revoking access at the Telegram bot level.

Message flow

  1. User sends a DM to the bot or mentions it in a group.
  2. The channel gateway resolves identity, applies pairing/allow/block rules, and denies unknown or revoked senders before enqueue.
  3. The Telegram handler normalises the allowed message into the canonical runtime request shape.
  4. The queue manager picks up the request, assembles context (memory recall, knowledge retrieval), and dispatches to the bound agent.
  5. Provider execution and the tool loop run exactly like any other runtime task. Streaming responses are edited into a single Telegram message in place.
  6. The final reply is sent. The transcript — with every tool call, memory hit, and retrieval result — is visible in the dashboard's runtime view.

Commands in chat

  • /skill — list available skills.
  • /skill <name> [question] — invoke a specific skill explicitly.
  • Any other message — routed through the normal queue and picks up skills automatically if triggers match.

Where credentials live

The bot token is stored as a secret in Postgres, encrypted at rest using the same master key as the rest of the control plane. It's never echoed back through the API — once saved, the dashboard shows only a fingerprint. Rotate by re-running the Telegram wizard with a new token; the old one is overwritten atomically.

Common issues

  • Bot replies nothing. Check the channel gateway first — a rejected or unknown identity produces no runtime task by design.
  • Bot token keeps failing verification. BotFather tokens can be regenerated; an old token stops working immediately.
  • Message doesn't match a skill. Expected. The selector falls through to the agent's default prompt contract — look at the runtime trace to see which skill, if any, was scored.

Next steps

  • Runtime — the execution lifecycle that runs under every Telegram message.
  • Security — the identity gateway, audit events, and rate-limit posture.