telegram.message.send-photo

Send a Telegram photo end-to-end: call Telegram sendPhoto, upsert the chat row, and persist the outbound message record. Returns message_uuid, chat_uuid, telegram_message_ref, and photo_file_ref.

End-to-end send a Telegram photo: call Telegram API, upsert chat row, persist outbound message record.

Public callers supply bot_uuid + chat_ref + photo (URL or file_id); the DAG resolves the bot token internally (via send-photo-api) and returns message_uuid + chat_uuid as the platform-side identifiers.

The photo caption is stored in the TelegramMessage text column (v1 trade-off — no media columns yet). The photo URL is not persisted; photo_file_ref is returned so callers can re-send without re-uploading.

Overview

Property	Value
Workflow type	Dag
Library	App-telegram
Version	1.0

Input Schema

Field	Type	Required	Default	Description
bot_uuid	uuid	Yes	—	UUID of the TelegramBot row. The bot token is resolved internally by the send-photo-api step.
chat_ref	integer	Yes	—	Telegram integer chat id. Negative for groups/channels (e.g. -100123456), positive for private chats.
photo	string	Yes	—	Photo to send: HTTPS URL of the image or a Telegram file_id from a previously uploaded photo.
caption	string	No	—	Optional caption text (up to 1024 characters). Stored as the TelegramMessage text in v1 (no dedicated media columns).
parse_mode	string	No	—	Optional Telegram parse mode for the caption. 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'}]]}. Threaded through to telegram.message.send-photo-api.
workflow_run_uuid	string	No	—	Engine-stamped parent run uuid (DAG step target).

Output Schema

Field	Type	Required	Default	Description
message_uuid	uuid	No	—	UUID of the persisted TelegramMessage row (from Layer 3).
telegram_message_ref	integer	No	—	Telegram's integer message id (from Layer 1).
chat_uuid	uuid	No	—	UUID of the upserted TelegramChat row (from Layer 2).
photo_file_ref	string	No	—	Telegram file_id of the uploaded photo (from Layer 1). Callers can use this to re-send the same photo without re-uploading.
persisted_chat	boolean	No	—	True when the chat row was newly inserted (alias of Layer 2 'persisted').
send_photo	json	No	—	Result dict from the send_photo step (Layer 1).
upsert_chat	json	No	—	Result dict from the upsert_chat step (Layer 2).
persist_message	json	No	—	Result dict from the persist_message step (Layer 3).
bot_uuid	uuid	No	—	Echoed from input.
chat_ref	integer	No	—	Echoed from input.
photo	string	No	—	Echoed from input.
caption	string	No	—	Echoed from input.
parse_mode	string	No	—	Echoed from input.
reply_markup	json	No	—	Echoed from input.
workflow_run_uuid	string	No	—	DAG run uuid; stamped by the engine's auto-generated 'start' transition.
completed_at	string	No	—	—
failed_at	string	No	—	—
failure_reason	string	No	—	Engine-stamped human-readable failure reason
failed_at_state	string	No	—	Engine-stamped state when the workflow failed
failed_step	string	No	—	Engine-stamped step name (DAG path)
failed_layer	integer	No	—	Engine-stamped layer index (DAG path)
error	string	No	—	Engine-stamped exception message
error_type	string	No	—	Engine-stamped exception class name

DAG Layers

#	Layer	Steps	Compensation
1	send	telegram.message.send-photo-api	—
2	upsert_chat	data.telegram.chat.upsert	—
3	persist_message	data.telegram.message.persist	—

Execution Flow

Sub-workflows

Sub-workflow	Step name
telegram.message.send-photo-api	send_photo
data.telegram.chat.upsert	upsert_chat
data.telegram.message.persist	persist_message

API Usage

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

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