telegram.update.poll

Pull a batch of pending Telegram updates via getUpdates and idempotently persist each one as a TelegramWebhookEvent row via data.telegram.update-event.persist. Returns persisted event_uuids, batch counts, and the next_offset to pass on the following call.

Pull a batch of pending Telegram updates via getUpdates and persist each one.

PENDING (auto_advance=execute) → COMPLETED with event_uuids / counts / next_offset ↘ FAILED on any error

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 to poll for updates
offset	integer	No	—	Telegram update offset to fetch from. Pass last_update_id+1 to acknowledge the previous batch. Null or 0 fetches the next pending updates.
limit	integer	No	—	Number of updates to fetch (Telegram-allowed range 1..100, default 100)
timeout	integer	No	—	Long-poll timeout in seconds (default 0 = short-poll). Pass e.g. 25 for long-polling. v1 default is 0.

Output Schema

Field	Type	Required	Default	Description
event_uuids	json	Yes	—	UUIDs of persisted TelegramWebhookEvent rows, in Telegram order (oldest first)
count	integer	Yes	—	Number of updates returned by Telegram in this batch
new_count	integer	Yes	—	Number of newly inserted rows (count minus already_exists hits)
next_offset	integer	No	—	max(update_id)+1 for the batch; null if no updates were returned. Pass this back as offset on the next call to acknowledge.
error	string	No	—	Engine-captured exception message
error_type	string	No	—	Exception class name
failed_at_state	string	No	—	State name where the failure was recorded
failed_layer	string	No	—	DAG layer name (N/A for linear workflows)
failed_step	string	No	—	DAG step name (N/A for linear workflows)
failure_reason	string	No	—	Human-readable reason the workflow failed
failure_type	string	No	—	Failure category
failed_action	string	No	—	Name of the action method that raised
bot_uuid	uuid	No	—	bot_uuid echoed from input on failure

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	Fetch updates from Telegram and persist each one
completed	No	Yes	Yes	—	All updates fetched and persisted; next_offset ready
failed	No	Yes	No	—	Poll or persist 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.update.poll",
  "initial_data": {
    "bot_uuid": "value"
  }
}