chloejs/channels/telegram

Talking to an agent from Telegram. An agent's channel file is one call:

// agents/<name>/channels/telegram.ts
import { telegramChannel } from "chloejs/channels/telegram";
export default telegramChannel({ allowFrom: [111111111] });

The bot's token is TELEGRAM_BOT_TOKEN, or credentials: { botToken }. To make a bot, message @BotFather in Telegram, send /newbot, and pick a name and a username. It replies with the token.

allowFrom is who may talk to the agent, by Telegram user id, in any chat, including a group made later. Anyone can find a bot and message it, so leave it empty only the first time: until it has an entry, the bot answers a private message with the sender's user id, which is what goes here. The first id is also who the agent's jobs ask when they name nobody.

Two ways for messages to arrive, and mode picks:

"polling"  chloe asks Telegram for them. Nothing is exposed, and a message
           sent while chloe is down is picked up when it comes back. The
           default.
"webhook"  Telegram sends each one to publicUrl + /chloe/v1/<agent>/telegram,
           which has to be reachable past the login, and checks
           TELEGRAM_WEBHOOK_SECRET_TOKEN (or credentials.webhookSecretToken)
           on every call. chloe registers the address itself on start.

In a group, the agent answers a command (/ask), a message that mentions the bot, or a reply to one of the bot's own messages, and nothing else.

export function listen(options: TelegramOptions & { name: string; token: string; agent: () => Agent | undefined }): Running

export function telegramChannel(options: TelegramOptions = {}): Channel

export interface TelegramOptions {
  /** For spotting a mention in a group. Asked of Telegram when left out. */
  botUsername?: string;
  /** Instead of TELEGRAM_BOT_TOKEN and TELEGRAM_WEBHOOK_SECRET_TOKEN. */
  credentials?: { botToken?: string; webhookSecretToken?: string };
  /** Telegram user ids that may reach the agent. */
  allowFrom?: number[];
  mode?: "polling" | "webhook";
  /** Where this server is reachable from outside, for mode "webhook", like "https://agents.example.com". */
  publicUrl?: string;
  /** Which files are taken, and how big. Anything else is named to the agent but not handed over. */
  uploadPolicy?: { allowedMediaTypes?: string[]; maxBytes?: number };
  /** Where Telegram is. Only the tests change it. */
  api?: string;
}