data.telegram.update-event.persist

Idempotently insert a TelegramWebhookEvent row keyed on (bot_uuid, update_ref); returns the event_uuid and an already_exists flag

Idempotently insert a TelegramWebhookEvent row for a single Telegram update.

Keyed on (telegram_bot_id, update_id). Two cases:

• not found → INSERT new row, already_exists=False
• found → return existing event_uuid, already_exists=True (no mutation)

Accepts bot_uuid and resolves it to the internal integer FK before any DB operation, following the platform UUID-only surface rule.

The organization_id for the new row is sourced from the resolved bot's own organization_id so the caller does not need to supply it.

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 that received the update
update_ref	integer	Yes	—	Telegram integer update_ref (monotonically increasing per bot)
update_type	string	Yes	—	Type of the update: 'message', 'callback_query', 'inline_query', 'channel_post', 'edited_message', etc.
chat_ref	integer	No	—	Telegram chat_ref the update is from, when applicable. Null for update types that are not chat-scoped (e.g. inline_query).
payload	json	Yes	—	Raw Telegram update payload as a JSON dict

Output Schema

Field	Type	Required	Default	Description
event_uuid	string	Yes	—	UUID of the persisted TelegramWebhookEvent row
already_exists	boolean	Yes	—	True when the (bot, update_id) pair was already persisted. Callers should treat this as an idempotent no-op — the original row is returned unchanged.
failure_reason	string	No	—	Human-readable reason the workflow failed
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)
failed_action	string	No	—	Name of the action method that raised
failure_type	string	No	—	Failure category (e.g. 'not_found')

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	complete	Persist Telegram webhook event row
completed	No	Yes	Yes	—	Event row persisted or already existed
failed	No	Yes	No	—	Persist failed

State Diagram

Transitions

From	Action	To	Description
pending	complete	completed	—
pending	fail	failed	—

API Usage

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

{
  "workflow_type": "data.telegram.update-event.persist",
  "initial_data": {
    "bot_uuid": "value",
    "update_ref": 123,
    "update_type": "value",
    "payload": "value"
  }
}