telegram.update.dispatch

Process one inbound Telegram Update payload received via webhook. Persists the event idempotently via data.telegram.update-event.persist and inline-acknowledges any callback_query so the user's Telegram client stops showing the loading spinner. Ack failure does not fail the workflow — callback_acked=False is returned instead.

Handle one inbound Telegram Update payload from the webhook route.

PENDING (auto_advance=execute) → COMPLETED with event_uuid + ack result ↘ FAILED on bot-not-found, malformed payload, or persist failure

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 that received this update.
payload	json	Yes	—	Raw Telegram Update JSON dict as POSTed by the webhook. Must contain at least update_id (required by the Telegram protocol).

Output Schema

Field	Type	Required	Default	Description
event_uuid	uuid	Yes	—	UUID of the persisted TelegramWebhookEvent row.
already_exists	boolean	Yes	—	True if the (bot, update_id) pair was already in the database (idempotency hit).
update_type	string	Yes	—	Derived update type, e.g. 'message', 'callback_query', 'channel_post'. 'unknown' if none of the known keys are present in the payload.
update_ref	integer	Yes	—	Telegram's integer update reference from the payload.
chat_ref	integer	No	—	Chat ID derived from the payload; None for inline_query, chosen_inline_result, and any type where a chat context is absent.
callback_acked	boolean	Yes	—	True if this update was a callback_query AND the answerCallbackQuery call succeeded. False if not a callback_query, or if the ack failed (failure is soft — does not fail the dispatch).
callback_dispatched	boolean	No	—	True when compact callback_data routed to a workflow callback.
callback_workflow	string	No	—	Workflow type selected from compact callback_data.
callback_action	string	No	—	Compact callback action key selected from callback_data.
callback_error	string	No	—	Soft callback dispatch error, if any.
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	Parse, persist, and optionally ack the inbound Telegram update
completed	No	Yes	Yes	—	Update persisted; callback_query ack'd if applicable
failed	No	Yes	No	—	Dispatch failed due to bot not found, malformed payload, or persist error

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.dispatch",
  "initial_data": {
    "bot_uuid": "value",
    "payload": "value"
  }
}