data.telegram.bot.persist

Create or restore a TelegramBot row, keyed on (organization_uuid, bot_ref)

Idempotently insert or restore a TelegramBot row.

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

Keyed on (organization_id, bot_id). Three cases:

• not found → INSERT, persisted=True restored=False
• found, active → no-op row, refresh token/username/first_name, 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
organization_uuid	uuid	Yes	—	UUID of the organization that owns the bot
bot_token	string	Yes	—	Telegram Bot API token issued by BotFather
bot_ref	integer	Yes	—	Telegram integer bot reference returned by getMe
username	string	Yes	—	Bot @username (without @), returned by getMe
first_name	string	No	—	Display name of the bot, returned by getMe
workflow_run_id	string	No	—	Engine-stamped parent run id (DAG step target)

Output Schema

Field	Type	Required	Default	Description
bot_uuid	string	Yes	—	UUID of the persisted TelegramBot row
persisted	boolean	Yes	—	True when a brand-new row was inserted
restored	boolean	Yes	—	True when a soft-deleted row was undeleted
failure_reason	string	No	—	Engine-stamped human-readable failure reason
failure_type	string	No	—	Engine-stamped failure category
failed_action	string	No	—	Engine-stamped action that raised
failed_at_state	string	No	—	Engine-stamped state when the workflow failed
failed_step	string	No	—	Engine-stamped step name (DAG path)
failed_layer	string	No	—	Engine-stamped layer index (DAG path)
error	string	No	—	Engine-stamped exception message
error_type	string	No	—	Engine-stamped exception class name

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	complete	Persist Telegram bot row
completed	No	Yes	Yes	—	Bot row persisted
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.bot.persist",
  "initial_data": {
    "organization_uuid": "value",
    "bot_token": "value",
    "bot_ref": 123,
    "username": "value"
  }
}