data.telegram.chat.upsert

Idempotently insert or restore a TelegramChat row, keyed on (bot_uuid, chat_ref)

Idempotently insert or restore a TelegramChat row.

Accepts bot_uuid and resolves it to the internal integer FK before any DB operation, following the platform UUID-only surface rule. organization_id is derived from the resolved bot row — no input required.

Keyed on (telegram_bot_id, chat_id). Three cases:

• not found → INSERT, persisted=True restored=False
• found, active → no-op row, refresh chat_type/title/username, persisted=False restored=False
• found, deleted → restore + refresh, persisted=False restored=True

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 owning TelegramBot (not the integer bot_id)
chat_ref	integer	Yes	—	Telegram integer chat reference (e.g. -100123456 for a channel, 12345 for private)
chat_type	string	Yes	—	One of: private, group, supergroup, channel
title	string	No	—	Display title of the chat (optional; absent for private chats)
username	string	No	—	Chat @username without leading @ (optional; channels/supergroups only)
workflow_run_id	string	No	—	Engine-stamped parent run id (DAG step target)

Output Schema

Field	Type	Required	Default	Description
chat_uuid	string	Yes	—	UUID of the persisted TelegramChat row
persisted	boolean	Yes	—	True when a brand-new row was inserted
restored	boolean	Yes	—	True when a soft-deleted row was undeleted
workflow_run_id	string	No	—	Engine-stamped parent run id (carried forward from input)
bot_uuid	uuid	No	—	bot_uuid echoed from input
chat_ref	integer	No	—	chat_ref echoed from input
failure_reason	string	No	—	Human-readable failure reason
failure_type	string	No	—	Failure category (e.g. not_found)
failed_action	string	No	—	Name of the action method that raised
error	string	No	—	Engine-stamped exception message (set on unhandled exceptions)
error_type	string	No	—	Engine-stamped exception type name
failed_at_state	string	No	—	Engine-stamped state name where the failure occurred
failed_layer	string	No	—	Engine-stamped DAG layer name (None for non-DAG workflows)
failed_step	string	No	—	Engine-stamped DAG step name (None for non-DAG workflows)

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	complete	Upsert TelegramChat row
completed	No	Yes	Yes	—	Chat row upserted
failed	No	Yes	No	—	Upsert 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.chat.upsert",
  "initial_data": {
    "bot_uuid": "value",
    "chat_ref": 123,
    "chat_type": "value"
  }
}