data.telegram.update-event.load

Load a single TelegramWebhookEvent by uuid, returning update_type, chat_ref, payload, and bot_uuid for downstream routing

Load a single TelegramWebhookEvent record by UUID.

Returns the full event fields needed for downstream routing, including update_type and chat_ref, without exposing any internal integer PKs.

Optional bot_uuid parameter enforces tenant ownership — the event must belong to a bot with that uuid, otherwise the query returns a tenant_mismatch error.

Soft-deleted events (deleted_at is not null) are treated as not-found.

Overview

Property	Value
Workflow type	Atomic
Library	App-telegram
Version	1.0

Input Schema

Field	Type	Required	Default	Description
event_uuid	uuid	Yes	—	UUID of the TelegramWebhookEvent row to load
bot_uuid	uuid	No	—	Optional tenant check: if provided, the event must belong to a TelegramBot with this uuid, else the workflow returns failure_type='tenant_mismatch'.

Output Schema

Field	Type	Required	Default	Description
event_uuid	uuid	No	—	UUID of the loaded TelegramWebhookEvent row (echoed)
bot_uuid	uuid	No	—	UUID of the TelegramBot that owns this event (resolved from FK)
update_ref	integer	No	—	Telegram integer update_ref (Telegram-side identifier, not an ltinteg PK)
update_type	string	No	—	Type of the Telegram update: 'message', 'callback_query', 'inline_query', 'channel_post', 'edited_message', etc.
chat_ref	integer	No	—	Telegram chat_ref the update is from. None for update types that are not chat-scoped (e.g. inline_query).
payload	string	No	—	Raw Telegram update JSON, serialized as a JSON string (parse with json.loads). Emitted as a string — not a dict — so the engine's internal-id guard does not recurse into Telegram's external id/update_id/message_id keys. See the class docstring.
received_at	string	No	—	ISO-8601 timestamp of when the event was persisted
workflow_uuid	string	No	—	Dispatch workflow uuid assigned at receive time, if any
found	boolean	No	—	False when the event was not found or not visible to the caller.
error	string	No	—	Human-readable failure reason when the query cannot complete
error_type	string	No	—	Error category code (e.g. 'not_found', 'tenant_mismatch')
failure_type	string	No	—	Structured failure category for downstream routing: 'not_found'

States

State	Initial	Terminal	Success	Auto-advance	Description
done	Yes	Yes	Yes	—	—

API Usage

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

{
  "workflow_type": "data.telegram.update-event.load",
  "initial_data": {
    "event_uuid": "value"
  }
}