telegram.message.send-api

Send a message via Telegram Bot API (sendMessage) and return message metadata. Input takes bot_uuid; the token is resolved from the TelegramBot row internally.

Call Telegram sendMessage for a bot identified by bot_uuid.

PENDING (auto_advance=execute) → COMPLETED with message metadata ↘ FAILED on any error

Single-responsibility: one API call, no DB writes. The wrapping DAG (telegram.message.send) is responsible for resolving the chat, persisting the message, and composing the result.

Overview

Property	Value
Workflow type	Atomic
Library	App-telegram
Version	1.0

Input Schema

Field	Type	Required	Default	Description
bot_uuid	uuid	Yes	—	UUID of the TelegramBot row whose token will be used to send the message. The workflow resolves bot_uuid → bot_token internally.
chat_ref	integer	Yes	—	Telegram integer chat reference. Negative for groups/channels (e.g. -100123456), positive for private chats.
text	string	Yes	—	Message text to send.
parse_mode	string	No	—	Optional Telegram parse mode passed through to sendMessage. Accepted values: 'MarkdownV2', 'HTML', 'Markdown'.
reply_markup	json	No	—	Optional Telegram reply_markup as a raw dict, e.g. {'inline_keyboard': [[{'text': 'OK', 'callback_data': 'ok'}]]}. Each inner button dict is passed as kwargs to InlineKeyboardButton.
workflow_run_id	string	No	—	Engine-stamped parent run id (DAG step target)

Output Schema

Field	Type	Required	Default	Description
telegram_message_ref	integer	Yes	—	Telegram's integer message reference from the sendMessage response.
chat_ref	integer	Yes	—	Telegram integer chat reference the message was sent to (echo of input).
chat_type	string	Yes	—	Chat type from the response ('private', 'group', 'supergroup', 'channel').
chat_title	string	No	—	Chat title from the response; None for private chats.
chat_username	string	No	—	Chat @username from the response; None when not set.
date	integer	Yes	—	Telegram unix timestamp (int) for when the message was sent.
failure_reason	string	No	—	Engine-stamped human-readable failure reason
failure_type	string	No	—	Engine-stamped failure category
failed_action	string	No	—	Engine-stamped action that raised
failed_at_state	string	No	—	Engine-stamped state when the workflow failed
failed_step	string	No	—	Engine-stamped step name (DAG path)
failed_layer	string	No	—	Engine-stamped layer index (DAG path)
error	string	No	—	Engine-stamped exception message
error_type	string	No	—	Engine-stamped exception class name

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	Send message via Telegram Bot API
completed	No	Yes	Yes	—	Message sent; metadata captured
failed	No	Yes	No	—	Message send failed

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "telegram.message.send-api",
  "initial_data": {
    "bot_uuid": "value",
    "chat_ref": 123,
    "text": "value"
  }
}