Self-improving AI Employees for everyone
Telegram Send (telegramSend)
| Field | Value |
|---|---|
| Category | social |
| Backend handler | server/nodes/telegram/telegram_send.py (TelegramSendNode); dispatch via BaseNode.execute() -> @Operation("send") -> _send.py (resolve_chat_id + perform_send) |
| Tests | server/tests/nodes/test_telegram_social.py (node level), test_telegram_service.py (service level: split / caption spill) |
| Skill (if any) | none |
| Dual-purpose tool | yes - usable_as_tool = True, tool name telegram_send; its ApprovalSpec holds each send for the owner's OK while they ask first |
Purpose
Send text, photo, document, location, or contact messages through a connected
Telegram bot (python-telegram-bot v22.x). The node leans on the TelegramService
singleton for the actual Bot API calls; the send operation only resolves the
recipient and packages the envelope.
Validation and message-type dispatch live in _send.py,
not in the operation body. The direct WebSocket command
(_handlers.py::handle_telegram_send) routes through the same perform_send,
so the two entry points cannot diverge. They previously carried independent
copies and had already drifted — the socket path never forwarded silent or
reply_to_message_id. Dispatch is a table keyed by message type, so adding a
type is one entry plus one Literal member rather than a branch in two files.
Inputs (handles)
| Handle | Connection type | Required | Purpose |
|---|---|---|---|
input-main |
main | no | Upstream data - not read directly by the handler; parent nodes typically resolve templates into text / caption via ParameterResolver before the call. |
Parameters
| Name | Type | Default | Required | displayOptions.show | Description |
|---|---|---|---|---|---|
recipient_type |
options | self |
no | - | One of self / user / group |
chat_id |
string | "" |
yes when recipient_type != self |
recipient_type: ['user','group'] |
Numeric chat id or @username |
message_type |
options | text |
no | - | text / photo / document / location / contact |
text |
string | "" |
yes when message_type=text |
message_type: ['text'] |
Message text |
media_url |
string | "" |
yes when message_type in photo/document |
message_type: ['photo','document'] |
Remote URL or file_id |
caption |
string | "" |
no | message_type: ['photo','document'] |
Optional caption |
latitude |
number (Optional[float], default None) |
None |
yes when message_type=location |
message_type: ['location'] |
Latitude. None (not 0) so deliberate 0.0 (Null Island) is distinguishable from "unset" |
longitude |
number (Optional[float], default None) |
None |
yes when message_type=location |
message_type: ['location'] |
Longitude |
phone_number |
string | "" |
yes when message_type=contact |
message_type: ['contact'] |
Contact phone |
first_name |
string | "" |
yes when message_type=contact |
message_type: ['contact'] |
Contact first name |
last_name |
string | "" |
no | message_type: ['contact'] |
Contact last name |
parse_mode |
options | Auto |
no | message_type: ['text','photo','document'] |
Auto / "" / HTML / Markdown / MarkdownV2 |
silent |
boolean | false |
no | - | Sends without notification (disable_notification=True) |
reply_to_message_id |
number | 0 |
no | - | If truthy, coerced to int and passed as reply_to_message_id |
Outputs (handles)
| Handle | Shape | Description |
|---|---|---|
output-main |
object | Standard envelope containing Bot API message metadata |
Output payload
The operation returns this dict (validated against TelegramSendOutput,
extra="allow"):
{
message_id: number; // first message when the send became several
chat_id: number;
message_type: 'text' | 'photo' | 'document' | 'location' | 'contact';
date: string; // ISO timestamp from Telegram
sent: true;
// Present only when one logical send became several Telegram messages.
parts?: number; // text over 4096 -> chunk count
message_ids?: number[]; // every id in the chunk chain
caption_truncated?: boolean; // caption over 1024 spilled
follow_up_message_ids?: number[];// ids of the threaded caption remainder
}
sent was declared on the model from the start but never populated, and
_serialize_result dumps with exclude_unset=True, so until it was emitted
the data picker advertised a field that never materialised. message_type and
date were always returned but undeclared, surviving only through
extra="allow"; declaring them changed nothing at runtime and made them
visible in the picker.
BaseNode.execute() wraps it as { success: true, result: <payload>, execution_time, timestamp, node_id, node_type }.
Logic Flow
flowchart TD
A[TelegramSendNode.send op] --> B{TelegramService<br/>connected?}
B -- no --> Efail[raise RuntimeError<br/>BaseNode wraps as success=false]
B -- yes --> C{recipient_type?}
C -- self --> D[chat_id = service.owner_chat_id]
D --> D2{owner set?}
D2 -- no --> D3[Fetch 'telegram_owner_chat_id'<br/>via auth_service.get_api_key]
D3 -- ok --> D4[service.set_owner + use]
D3 -- missing --> Efail
C -- user/group --> E{chat_id truthy?}
E -- no --> Efail
E -- yes --> F[_send.perform_send<br/>table lookup on message_type]
F --> G{known type?}
G -- no --> Efail
G -- yes --> H[Per-type validation<br/>NodeUserError when unmet]
H --> I{captioned media?}
I -- no --> Tsend[service.send_message / location / contact]
I -- yes --> Msend[service.send_photo / send_document<br/>-> _send_captioned_media]
Msend --> J{caption over 1024<br/>UTF-16 units?}
J -- no --> Ok
J -- yes --> K[Truncate at boundary<br/>send remainder as threaded reply]
K --> Ok
Tsend --> Ok
Ok[Return success=true<br/>message_id, chat_id, message_type, date, sent]
Decision Logic
- Connection gate: If
service.connectedis False the op raisesRuntimeError("Telegram bot not connected. Add bot token in Credentials.")(wrapped byBaseNode.execute()into asuccess=falseenvelope). No retry. - Self recipient: Uses
service.owner_chat_id(auto-captured on the first private message). If not set, the op triesget_auth_service().get_api_key("telegram_owner_chat_id")and restores the owner by callingservice.set_owner(int(saved)). Any exception during restore is logged at WARNING and swallowed - the op continues and ultimately raises the "Bot owner not detected"RuntimeErrorwhen the chat_id is still falsy. - Parse mode: Passed through to the service. The service itself implements
Auto(GFM -> Telegram HTML viamarkdown_formatter.to_telegram_html) plus theBadRequest "can't parse entities"fallback that retries withparse_mode=Noneand the original unescaped text. - Message type dispatch:
_send.perform_sendlooks the type up in a module-level table. An unknown value raisesNodeUserError("Unsupported message type: <x>"). Per-type validation (textpresent,media_urlpresent, both coordinates set, phone plus first name) also raisesNodeUserError, so the operator log gets one WARN line with no traceback — these are user-correctable inputs, not server bugs. - Caption spill: Telegram caps captions at 1024 units and rejects the whole
send past that.
_send_captioned_mediatruncates at the cap and sends the remainder as a reply threaded under the media message, reusing the chunkingsend_messagealready performs. The split runs on the raw caption before_resolve_bodyconverts markdown to HTML — splitting after conversion could separate a<b>from its closing tag, which Telegram rejects with "can't find end of the entity". Telegram measures the cap against entity-parsed text, so truncating raw markdown is conservative. - Reply-to coercion:
reply_to_message_idis cast viaint(...)only when truthy. A non-numeric string here raisesValueError, whichBaseNode.execute()catches and surfaces as an error envelope.
Side Effects
- Database writes: none from the op directly. The owner is persisted via
auth_service.store_api_key("telegram_owner_chat_id", ...)only insideTelegramService._on_message_received, not from the send path. - Broadcasts: none from the send op. The service broadcasts the typed
telegram.statusCloudEvents envelope (wire keytelegram_status) on connect / disconnect only - seeserver/nodes/telegram/_events.py. - External API calls: Telegram Bot API via
python-telegram-bot(bot.send_message,bot.send_photo,bot.send_document,bot.send_location,bot.send_contact). - File I/O: none.
- Subprocess: none.
External Dependencies
- Credentials:
auth_service.get_api_key("telegram_owner_chat_id")when restoring the self-owner. Bot token comes fromauth_service.store_api_key("telegram", ...)and is consumed byTelegramService.connect()elsewhere, not by this op. Declared on the plugin viacredentials = (TelegramCredential,). - Services:
TelegramServicesingleton (server/nodes/telegram/_service.py::get_telegram_service). - Python packages:
python-telegram-bot(v22.x),markdown-it-py(viamarkdown_formatter). - Environment variables:
TELEGRAM_OWNER_CHAT_ID(read by the service as a fallback forowner_chat_id).
Edge cases & known limits
- Swallowed owner-restore exceptions: Any error looking up
telegram_owner_chat_idis logged at WARNING and continues; the user only sees the downstream "Bot owner not detected" error. - Silent ValueError on
reply_to_message_id: A non-numeric value raisesValueError, surfaced byBaseNode.execute()as the error message. - Long captions arrive as two messages: A caption over 1024 units produces
the media message plus one or more threaded follow-ups. The follow-up carries
disable_notification=Trueso a single logical send still pings once.caption_truncatedandfollow_up_message_idsreport it. - Length is counted in UTF-16 units, not characters: an emoji costs 2. A
1024-character caption of emoji is 2048 units and will spill. This matches
how the Bot API measures its own limits;
len()under-counts. recipient_typeis aLiteral["self","user","group"]: Pydantic rejects any other value at param validation. Foruser/groupan emptychat_idraisesRuntimeError("chat_id is required").- Markdown fallback leaks unescaped text: If
send_messageraisesBadRequest("can't parse entities ..."), the service retries with the ORIGINAL (unescaped) text atparse_mode=None, not the escaped copy. If the original contains markup, it is visible to the recipient as literal characters. reply_to_message_id=0: Falsy, so the handler does NOT pass it through - the node silently drops the reply reference.parse_mode='None'(string): Not treated as "no parse mode"; passed through to Telegram, which will reject it. The frontend uses empty string""for "None" so this is a misconfiguration hazard only for manual JSON imports.
Related
- Sibling nodes:
telegramReceive,socialSend - Service:
server/nodes/telegram/_service.py - Markdown formatter:
server/services/markdown_formatter.py - Architecture docs: Credentials Encryption, Status Broadcaster