#telegram API reference

A Telegram Bot API client over the http client + json. Hold a Bot (token + API base URL), send messages with sendMessage / sendPhoto / sendChatAction, identify the bot with getMe, and poll for incoming updates with getUpdates (long-poll). Larger than the one-shot notifiers (slack / discord / gotify): getUpdates drives a stateful receive loop where the caller advances the offset past each processed update.

Needs the default jennifer binary (uses net via http). An API error ({"ok": false, ...}) throws Error{kind: "telegram"}. The bot token is a secret belonging to the caller - read it from the environment; never commit it.

Import with import "telegram.j" as telegram;. See the telegram guide for prose and examples.

#Functions

#telegram.answerCallbackQuery(b as Bot, callbackId as string, text as string)

Acknowledge a button press (answerCallbackQuery). Stops the client's loading spinner; the optional text shows a brief notification to the user.

Parameters

• b {Bot} - the bot
• callbackId {string} - the CallbackQuery.id to answer
• text {string} - a short notification ("" for none)

Returns {bool} - true on success

Throws

• {Error} - kind "telegram" on an API error

#telegram.bot(token as string)

Create a bot against the public Telegram API.

Parameters

• token {string} - the bot token

Returns {Bot} - a ready bot

#telegram.botWith(token as string, baseUrl as string)

Create a bot against a specific API base URL (a self-hosted Bot API server, or a test endpoint).

Parameters

• token {string} - the bot token
• baseUrl {string} - the API base URL (no trailing slash)

Returns {Bot} - a ready bot

#telegram.buildUpload(field as string, chatId as int, filename as string, contentType as string, data as bytes)

Assemble the multipart/form-data parts for a file upload: a chat_id field plus the file itself under field ("photo" for sendPhoto, "document" for sendDocument). Pure - takes the file bytes, so it is testable with no disk or network. Feed the result's contentType / body to the API POST.

Parameters

• field {string} - the file's form-field name ("photo" or "document")
• chatId {int} - the target chat id
• filename {string} - the file name reported to Telegram
• contentType {string} - the file's MIME type ("" lets Telegram sniff)
• data {bytes} - the file content

Returns {multipart.Built} - the built form (Content-Type header + body)

#telegram.getMe(b as Bot)

Fetch the bot's own identity (a good connectivity / token check).

Parameters

• b {Bot} - the bot

Returns {User} - the bot user

Throws

• {Error} - kind "telegram" on an API error

#telegram.getUpdates(b as Bot, offset as int, timeout as int)

Long-poll for updates. Pass offset as the last processed updateId + 1 (0 for the first call) and timeout as the long-poll wait in seconds; the HTTP read is bounded a few seconds beyond that.

Parameters

• b {Bot} - the bot
• offset {int} - the first update id to fetch (last processed + 1)
• timeout {int} - the long-poll timeout in seconds

Returns {list of Update} - the pending updates (empty when none arrived)

Throws

• {Error} - kind "telegram" on an API error

#telegram.inlineButton(text as string, callbackData as string)

A callback button: pressing it sends a callback_query carrying callbackData back to the bot (observe it via getUpdates + parseCallbackQuery, ack it with answerCallbackQuery).

Parameters

• text {string} - the button label
• callbackData {string} - the callback payload (<= 64 bytes)

Returns {Button} - the button

#telegram.parseCallbackQuery(update as json.Value)

Parse an incoming update's callback_query into a CallbackQuery. The update is the raw decoded JSON of one update object (a json.Value). Pure: no network. Reads /callback_query/{id,from,data,message/message_id}; a field that is absent lands as its zero value, and a field present but of the wrong JSON type raises a telegram error (rather than a raw json one), so callers catch malformed updates by the module's own error kind.

Parameters

• update {json.Value} - the decoded update object

Returns {CallbackQuery} - the parsed callback query (zero-valued fields when absent)

Throws

• {Error} - kind "telegram" when a present sub-field has the wrong type

#telegram.redactToken(s as string, token as string)

Redact a bot token from a string (an error message, a log line). The token is a secret that rides in the request URL path (/bot<TOKEN>/<method>), so an error carrying the URL would otherwise leak it. Replaces the bot<TOKEN> path segment with bot<redacted> and any bare token occurrence with <redacted>. Applied to every error message this module rethrows from the HTTP layer.

Parameters

• s {string} - the string to scrub
• token {string} - the bot token to remove

Returns {string} - the string with the token removed

#telegram.renderInlineKeyboard(rows as list of list of Button)

Render an inline-keyboard reply_markup to its JSON string. rows is a list of rows, each row a list of Buttons. Pure - the exact JSON sendMessageWith variants attach as the reply_markup form parameter. A URL button emits {"text":...,"url":...}; a callback button {"text":...,"callback_data":...}.

Parameters

• rows {list of list of Button} - the keyboard rows

Returns {string} - the reply_markup JSON (a {"inline_keyboard":[...]} object)

#telegram.sendChatAction(b as Bot, chatId as int, action as string)

Send a chat action (e.g. "typing", "upload_photo") to show activity.

Parameters

• b {Bot} - the bot
• chatId {int} - the target chat id
• action {string} - the action

Returns {bool} - true on success

Throws

• {Error} - kind "telegram" on an API error

#telegram.sendDocumentFile(b as Bot, chatId as int, filePath as string, contentType as string)

Upload a document from a local file path via multipart/form-data. Like sendPhotoFile but under the document field (any file type).

Parameters

• b {Bot} - the bot
• chatId {int} - the target chat id
• filePath {string} - the local file path
• contentType {string} - the file's MIME type ("" to let Telegram sniff)

Returns {Message} - the sent message

Throws

• {Error} - kind "telegram" on an API error (token-redacted)

#telegram.sendMessage(b as Bot, chatId as int, text as string)

Send a text message to a chat.

Parameters

• b {Bot} - the bot
• chatId {int} - the target chat id
• text {string} - the message text

Returns {Message} - the sent message

Throws

• {Error} - kind "telegram" on an API error

#telegram.sendMessageWith(b as Bot, chatId as int, text as string, parseMode as string)

Send a text message with a parse mode ("Markdown", "MarkdownV2", "HTML", or "" for plain).

Parameters

• b {Bot} - the bot
• chatId {int} - the target chat id
• text {string} - the message text
• parseMode {string} - the parse mode

Returns {Message} - the sent message

Throws

• {Error} - kind "telegram" on an API error

#telegram.sendMessageWithKeyboard(b as Bot, chatId as int, text as string, rows as list of list of Button)

Send a text message with an inline keyboard attached. rows is a list of button rows (see urlButton / inlineButton); it is rendered to the reply_markup form parameter via renderInlineKeyboard.

Parameters

• b {Bot} - the bot
• chatId {int} - the target chat id
• text {string} - the message text
• rows {list of list of Button} - the inline-keyboard rows

Returns {Message} - the sent message

Throws

• {Error} - kind "telegram" on an API error

#telegram.sendPhoto(b as Bot, chatId as int, photo as string, caption as string)

Send a photo by URL (or file id) with an optional caption.

Parameters

• b {Bot} - the bot
• chatId {int} - the target chat id
• photo {string} - a photo URL or a Telegram file id
• caption {string} - the caption ("" for none)

Returns {Message} - the sent message

Throws

• {Error} - kind "telegram" on an API error

#telegram.sendPhotoFile(b as Bot, chatId as int, filePath as string, contentType as string)

Upload a photo from a local file path via multipart/form-data. Reads the file with fs.readBytes, names the part from the path's basename, and POSTs it as sendPhoto. The complement to sendPhoto, which takes a URL or file id. contentType may be "" to let Telegram sniff the format.

Parameters

• b {Bot} - the bot
• chatId {int} - the target chat id
• filePath {string} - the local file path
• contentType {string} - the file's MIME type ("" to let Telegram sniff)

Returns {Message} - the sent message

Throws

• {Error} - kind "telegram" on an API error (token-redacted)

#telegram.urlButton(text as string, url as string)

A URL button: pressing it opens url in the client.

Parameters

• text {string} - the button label
• url {string} - the URL to open

Returns {Button} - the button

#Structs

#telegram.Bot

A bot: an API token and the API base URL.

#telegram.Button

One inline-keyboard button. Exactly one action is set: a url (opens a link) or a callbackData (fires a callback_query back to the bot). Build with urlButton / inlineButton rather than the raw literal.

#telegram.CallbackQuery

An incoming button press (a Telegram callback_query). Acknowledge it with answerCallbackQuery so the client stops its loading spinner.

#telegram.Message

A message (the text-relevant fields).

#telegram.Update

One polled update.

#telegram.User

A Telegram user (or bot).