{ "id": "telegram", "activation": { "onStartup": false }, "channels": [ "telegram" ], "channelEnvVars": { "telegram": [ "TELEGRAM_BOT_TOKEN" ] }, "configSchema": { "type": "object", "additionalProperties": false, "properties": {} }, "channelConfigs": { "telegram": { "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "type": "object", "properties": { "name": { "type": "string" }, "capabilities": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "inlineButtons": { "type": "string", "enum": [ "off", "dm", "group", "all", "allowlist" ] } }, "additionalProperties": false } ] }, "execApprovals": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "approvers": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "agentFilter": { "type": "array", "items": { "type": "string" } }, "sessionFilter": { "type": "array", "items": { "type": "string" } }, "target": { "type": "string", "enum": [ "dm", "channel", "both" ] } }, "additionalProperties": false }, "markdown": { "type": "object", "properties": { "tables": { "type": "string", "enum": [ "off", "bullets", "code", "block" ] } }, "additionalProperties": false }, "enabled": { "type": "boolean" }, "commands": { "type": "object", "properties": { "native": { "anyOf": [ { "type": "boolean" }, { "type": "string", "const": "auto" } ] }, "nativeSkills": { "anyOf": [ { "type": "boolean" }, { "type": "string", "const": "auto" } ] } }, "additionalProperties": false }, "customCommands": { "type": "array", "items": { "type": "object", "properties": { "command": { "type": "string" }, "description": { "type": "string" } }, "required": [ "command", "description" ], "additionalProperties": false } }, "configWrites": { "type": "boolean" }, "dmPolicy": { "default": "pairing", "type": "string", "enum": [ "pairing", "allowlist", "open", "disabled" ] }, "botToken": { "anyOf": [ { "type": "string" }, { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "env" }, "provider": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "id": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,127}$" } }, "required": [ "source", "provider", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "file" }, "provider": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "id": { "type": "string" } }, "required": [ "source", "provider", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "exec" }, "provider": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "id": { "type": "string" } }, "required": [ "source", "provider", "id" ], "additionalProperties": false } ] } ] }, "tokenFile": { "type": "string" }, "replyToMode": { "anyOf": [ { "type": "string", "const": "off" }, { "type": "string", "const": "first" }, { "type": "string", "const": "all" }, { "type": "string", "const": "batched" } ] }, "dm": { "type": "object", "properties": { "threadReplies": { "type": "string", "enum": [ "off", "inbound", "always" ] } }, "additionalProperties": false }, "groups": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "requireMention": { "type": "boolean" }, "ingest": { "type": "boolean" }, "disableAudioPreflight": { "type": "boolean" }, "groupPolicy": { "type": "string", "enum": [ "open", "disabled", "allowlist" ] }, "tools": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string" } }, "alsoAllow": { "type": "array", "items": { "type": "string" } }, "deny": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "toolsBySender": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string" } }, "alsoAllow": { "type": "array", "items": { "type": "string" } }, "deny": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "skills": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "allowFrom": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "systemPrompt": { "type": "string" }, "topics": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "requireMention": { "type": "boolean" }, "ingest": { "type": "boolean" }, "disableAudioPreflight": { "type": "boolean" }, "groupPolicy": { "type": "string", "enum": [ "open", "disabled", "allowlist" ] }, "skills": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "allowFrom": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "systemPrompt": { "type": "string" }, "agentId": { "type": "string" }, "errorPolicy": { "type": "string", "enum": [ "always", "once", "silent" ] }, "errorCooldownMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "errorPolicy": { "type": "string", "enum": [ "always", "once", "silent" ] }, "errorCooldownMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "allowFrom": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "defaultTo": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "groupAllowFrom": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "groupPolicy": { "default": "allowlist", "type": "string", "enum": [ "open", "disabled", "allowlist" ] }, "contextVisibility": { "type": "string", "enum": [ "all", "allowlist", "allowlist_quote" ] }, "historyLimit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dmHistoryLimit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dms": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "historyLimit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "direct": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "dmPolicy": { "type": "string", "enum": [ "pairing", "allowlist", "open", "disabled" ] }, "threadReplies": { "type": "string", "enum": [ "off", "inbound", "always" ] }, "tools": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string" } }, "alsoAllow": { "type": "array", "items": { "type": "string" } }, "deny": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "toolsBySender": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string" } }, "alsoAllow": { "type": "array", "items": { "type": "string" } }, "deny": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "skills": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "allowFrom": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "systemPrompt": { "type": "string" }, "topics": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "requireMention": { "type": "boolean" }, "ingest": { "type": "boolean" }, "disableAudioPreflight": { "type": "boolean" }, "groupPolicy": { "type": "string", "enum": [ "open", "disabled", "allowlist" ] }, "skills": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "allowFrom": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "systemPrompt": { "type": "string" }, "agentId": { "type": "string" }, "errorPolicy": { "type": "string", "enum": [ "always", "once", "silent" ] }, "errorCooldownMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "errorPolicy": { "type": "string", "enum": [ "always", "once", "silent" ] }, "errorCooldownMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "requireTopic": { "type": "boolean" }, "autoTopicLabel": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "enabled": { "type": "boolean" }, "prompt": { "type": "string" } }, "additionalProperties": false } ] } }, "additionalProperties": false } }, "textChunkLimit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "streaming": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "partial", "block", "progress" ] }, "chunkMode": { "type": "string", "enum": [ "length", "newline" ] }, "preview": { "type": "object", "properties": { "chunk": { "type": "object", "properties": { "minChars": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxChars": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "breakPreference": { "anyOf": [ { "type": "string", "const": "paragraph" }, { "type": "string", "const": "newline" }, { "type": "string", "const": "sentence" } ] } }, "additionalProperties": false }, "toolProgress": { "type": "boolean" }, "commandText": { "type": "string", "enum": [ "raw", "status" ] } }, "additionalProperties": false }, "progress": { "type": "object", "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "boolean", "const": false } ] }, "labels": { "type": "array", "items": { "type": "string" } }, "maxLines": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "render": { "type": "string", "enum": [ "text", "rich" ] }, "toolProgress": { "type": "boolean" }, "commandText": { "type": "string", "enum": [ "raw", "status" ] } }, "additionalProperties": false }, "block": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "coalesce": { "type": "object", "properties": { "minChars": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxChars": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idleMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "mediaMaxMb": { "type": "number", "exclusiveMinimum": 0 }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "mediaGroupFlushMs": { "description": "Buffer window in milliseconds for Telegram media groups/albums before dispatching them as one inbound message. Default: 500.", "type": "integer", "minimum": 10, "maximum": 60000 }, "pollingStallThresholdMs": { "type": "integer", "minimum": 30000, "maximum": 600000 }, "retry": { "type": "object", "properties": { "attempts": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minDelayMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "maxDelayMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "jitter": { "type": "number", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, "network": { "type": "object", "properties": { "autoSelectFamily": { "type": "boolean" }, "dnsResultOrder": { "type": "string", "enum": [ "ipv4first", "verbatim" ] }, "dangerouslyAllowPrivateNetwork": { "description": "Dangerous opt-in for trusted Telegram fake-IP or transparent-proxy environments where api.telegram.org resolves to private/internal/special-use addresses during media downloads.", "type": "boolean" } }, "additionalProperties": false }, "proxy": { "type": "string" }, "webhookUrl": { "description": "Public HTTPS webhook URL registered with Telegram for inbound updates. This must be internet-reachable and requires channels.telegram.webhookSecret.", "type": "string" }, "webhookSecret": { "description": "Secret token sent to Telegram during webhook registration and verified on inbound webhook requests. Telegram returns this value for verification; this is not the gateway auth token and not the bot token.", "anyOf": [ { "type": "string" }, { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "env" }, "provider": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "id": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,127}$" } }, "required": [ "source", "provider", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "file" }, "provider": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "id": { "type": "string" } }, "required": [ "source", "provider", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "exec" }, "provider": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "id": { "type": "string" } }, "required": [ "source", "provider", "id" ], "additionalProperties": false } ] } ] }, "webhookPath": { "description": "Local webhook route path served by the gateway listener. Defaults to /telegram-webhook.", "type": "string" }, "webhookHost": { "description": "Local bind host for the webhook listener. Defaults to 127.0.0.1; keep loopback unless you intentionally expose direct ingress.", "type": "string" }, "webhookPort": { "description": "Local bind port for the webhook listener. Defaults to 8787; set to 0 to let the OS assign an ephemeral port.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "webhookCertPath": { "description": "Path to the self-signed certificate (PEM) to upload to Telegram during webhook registration. Required for self-signed certs (direct IP or no domain).", "type": "string" }, "actions": { "type": "object", "properties": { "reactions": { "type": "boolean" }, "sendMessage": { "type": "boolean" }, "poll": { "type": "boolean" }, "deleteMessage": { "type": "boolean" }, "editMessage": { "type": "boolean" }, "sticker": { "type": "boolean" }, "createForumTopic": { "type": "boolean" }, "editForumTopic": { "type": "boolean" } }, "additionalProperties": false }, "threadBindings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "idleHours": { "type": "number", "minimum": 0 }, "maxAgeHours": { "type": "number", "minimum": 0 }, "spawnSessions": { "type": "boolean" }, "defaultSpawnContext": { "type": "string", "enum": [ "isolated", "fork" ] }, "spawnSubagentSessions": { "type": "boolean" }, "spawnAcpSessions": { "type": "boolean" } }, "additionalProperties": false }, "reactionNotifications": { "type": "string", "enum": [ "off", "own", "all" ] }, "reactionLevel": { "type": "string", "enum": [ "off", "ack", "minimal", "extensive" ] }, "heartbeat": { "type": "object", "properties": { "showOk": { "type": "boolean" }, "showAlerts": { "type": "boolean" }, "useIndicator": { "type": "boolean" } }, "additionalProperties": false }, "healthMonitor": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "additionalProperties": false }, "linkPreview": { "type": "boolean" }, "silentErrorReplies": { "type": "boolean" }, "responsePrefix": { "type": "string" }, "ackReaction": { "type": "string" }, "errorPolicy": { "type": "string", "enum": [ "always", "once", "silent" ] }, "errorCooldownMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "apiRoot": { "type": "string", "format": "uri" }, "trustedLocalFileRoots": { "description": "Trusted local filesystem roots for self-hosted Telegram Bot API absolute file_path values. Only absolute paths under these roots are read directly; all other absolute paths are rejected.", "type": "array", "items": { "type": "string" } }, "autoTopicLabel": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "enabled": { "type": "boolean" }, "prompt": { "type": "string" } }, "additionalProperties": false } ] }, "accounts": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "name": { "type": "string" }, "capabilities": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "inlineButtons": { "type": "string", "enum": [ "off", "dm", "group", "all", "allowlist" ] } }, "additionalProperties": false } ] }, "execApprovals": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "approvers": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "agentFilter": { "type": "array", "items": { "type": "string" } }, "sessionFilter": { "type": "array", "items": { "type": "string" } }, "target": { "type": "string", "enum": [ "dm", "channel", "both" ] } }, "additionalProperties": false }, "markdown": { "type": "object", "properties": { "tables": { "type": "string", "enum": [ "off", "bullets", "code", "block" ] } }, "additionalProperties": false }, "enabled": { "type": "boolean" }, "commands": { "type": "object", "properties": { "native": { "anyOf": [ { "type": "boolean" }, { "type": "string", "const": "auto" } ] }, "nativeSkills": { "anyOf": [ { "type": "boolean" }, { "type": "string", "const": "auto" } ] } }, "additionalProperties": false }, "customCommands": { "type": "array", "items": { "type": "object", "properties": { "command": { "type": "string" }, "description": { "type": "string" } }, "required": [ "command", "description" ], "additionalProperties": false } }, "configWrites": { "type": "boolean" }, "dmPolicy": { "default": "pairing", "type": "string", "enum": [ "pairing", "allowlist", "open", "disabled" ] }, "botToken": { "anyOf": [ { "type": "string" }, { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "env" }, "provider": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "id": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,127}$" } }, "required": [ "source", "provider", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "file" }, "provider": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "id": { "type": "string" } }, "required": [ "source", "provider", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "exec" }, "provider": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "id": { "type": "string" } }, "required": [ "source", "provider", "id" ], "additionalProperties": false } ] } ] }, "tokenFile": { "type": "string" }, "replyToMode": { "anyOf": [ { "type": "string", "const": "off" }, { "type": "string", "const": "first" }, { "type": "string", "const": "all" }, { "type": "string", "const": "batched" } ] }, "dm": { "type": "object", "properties": { "threadReplies": { "type": "string", "enum": [ "off", "inbound", "always" ] } }, "additionalProperties": false }, "groups": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "requireMention": { "type": "boolean" }, "ingest": { "type": "boolean" }, "disableAudioPreflight": { "type": "boolean" }, "groupPolicy": { "type": "string", "enum": [ "open", "disabled", "allowlist" ] }, "tools": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string" } }, "alsoAllow": { "type": "array", "items": { "type": "string" } }, "deny": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "toolsBySender": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string" } }, "alsoAllow": { "type": "array", "items": { "type": "string" } }, "deny": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "skills": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "allowFrom": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "systemPrompt": { "type": "string" }, "topics": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "requireMention": { "type": "boolean" }, "ingest": { "type": "boolean" }, "disableAudioPreflight": { "type": "boolean" }, "groupPolicy": { "type": "string", "enum": [ "open", "disabled", "allowlist" ] }, "skills": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "allowFrom": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "systemPrompt": { "type": "string" }, "agentId": { "type": "string" }, "errorPolicy": { "type": "string", "enum": [ "always", "once", "silent" ] }, "errorCooldownMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "errorPolicy": { "type": "string", "enum": [ "always", "once", "silent" ] }, "errorCooldownMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "allowFrom": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "defaultTo": { "anyOf": [ { "type": "string" }, { "type": "number" } ] }, "groupAllowFrom": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "groupPolicy": { "default": "allowlist", "type": "string", "enum": [ "open", "disabled", "allowlist" ] }, "contextVisibility": { "type": "string", "enum": [ "all", "allowlist", "allowlist_quote" ] }, "historyLimit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dmHistoryLimit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "dms": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "historyLimit": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "direct": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "dmPolicy": { "type": "string", "enum": [ "pairing", "allowlist", "open", "disabled" ] }, "threadReplies": { "type": "string", "enum": [ "off", "inbound", "always" ] }, "tools": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string" } }, "alsoAllow": { "type": "array", "items": { "type": "string" } }, "deny": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "toolsBySender": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "allow": { "type": "array", "items": { "type": "string" } }, "alsoAllow": { "type": "array", "items": { "type": "string" } }, "deny": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": false } }, "skills": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "allowFrom": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "systemPrompt": { "type": "string" }, "topics": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "requireMention": { "type": "boolean" }, "ingest": { "type": "boolean" }, "disableAudioPreflight": { "type": "boolean" }, "groupPolicy": { "type": "string", "enum": [ "open", "disabled", "allowlist" ] }, "skills": { "type": "array", "items": { "type": "string" } }, "enabled": { "type": "boolean" }, "allowFrom": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } }, "systemPrompt": { "type": "string" }, "agentId": { "type": "string" }, "errorPolicy": { "type": "string", "enum": [ "always", "once", "silent" ] }, "errorCooldownMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "errorPolicy": { "type": "string", "enum": [ "always", "once", "silent" ] }, "errorCooldownMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "requireTopic": { "type": "boolean" }, "autoTopicLabel": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "enabled": { "type": "boolean" }, "prompt": { "type": "string" } }, "additionalProperties": false } ] } }, "additionalProperties": false } }, "textChunkLimit": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "streaming": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "off", "partial", "block", "progress" ] }, "chunkMode": { "type": "string", "enum": [ "length", "newline" ] }, "preview": { "type": "object", "properties": { "chunk": { "type": "object", "properties": { "minChars": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxChars": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "breakPreference": { "anyOf": [ { "type": "string", "const": "paragraph" }, { "type": "string", "const": "newline" }, { "type": "string", "const": "sentence" } ] } }, "additionalProperties": false }, "toolProgress": { "type": "boolean" }, "commandText": { "type": "string", "enum": [ "raw", "status" ] } }, "additionalProperties": false }, "progress": { "type": "object", "properties": { "label": { "anyOf": [ { "type": "string" }, { "type": "boolean", "const": false } ] }, "labels": { "type": "array", "items": { "type": "string" } }, "maxLines": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "render": { "type": "string", "enum": [ "text", "rich" ] }, "toolProgress": { "type": "boolean" }, "commandText": { "type": "string", "enum": [ "raw", "status" ] } }, "additionalProperties": false }, "block": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "coalesce": { "type": "object", "properties": { "minChars": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "maxChars": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "idleMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "additionalProperties": false } }, "additionalProperties": false } }, "additionalProperties": false }, "mediaMaxMb": { "type": "number", "exclusiveMinimum": 0 }, "timeoutSeconds": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "mediaGroupFlushMs": { "description": "Buffer window in milliseconds for Telegram media groups/albums before dispatching them as one inbound message. Default: 500.", "type": "integer", "minimum": 10, "maximum": 60000 }, "pollingStallThresholdMs": { "type": "integer", "minimum": 30000, "maximum": 600000 }, "retry": { "type": "object", "properties": { "attempts": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 }, "minDelayMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "maxDelayMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "jitter": { "type": "number", "minimum": 0, "maximum": 1 } }, "additionalProperties": false }, "network": { "type": "object", "properties": { "autoSelectFamily": { "type": "boolean" }, "dnsResultOrder": { "type": "string", "enum": [ "ipv4first", "verbatim" ] }, "dangerouslyAllowPrivateNetwork": { "description": "Dangerous opt-in for trusted Telegram fake-IP or transparent-proxy environments where api.telegram.org resolves to private/internal/special-use addresses during media downloads.", "type": "boolean" } }, "additionalProperties": false }, "proxy": { "type": "string" }, "webhookUrl": { "description": "Public HTTPS webhook URL registered with Telegram for inbound updates. This must be internet-reachable and requires channels.telegram.webhookSecret.", "type": "string" }, "webhookSecret": { "description": "Secret token sent to Telegram during webhook registration and verified on inbound webhook requests. Telegram returns this value for verification; this is not the gateway auth token and not the bot token.", "anyOf": [ { "type": "string" }, { "oneOf": [ { "type": "object", "properties": { "source": { "type": "string", "const": "env" }, "provider": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "id": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,127}$" } }, "required": [ "source", "provider", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "file" }, "provider": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "id": { "type": "string" } }, "required": [ "source", "provider", "id" ], "additionalProperties": false }, { "type": "object", "properties": { "source": { "type": "string", "const": "exec" }, "provider": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,63}$" }, "id": { "type": "string" } }, "required": [ "source", "provider", "id" ], "additionalProperties": false } ] } ] }, "webhookPath": { "description": "Local webhook route path served by the gateway listener. Defaults to /telegram-webhook.", "type": "string" }, "webhookHost": { "description": "Local bind host for the webhook listener. Defaults to 127.0.0.1; keep loopback unless you intentionally expose direct ingress.", "type": "string" }, "webhookPort": { "description": "Local bind port for the webhook listener. Defaults to 8787; set to 0 to let the OS assign an ephemeral port.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "webhookCertPath": { "description": "Path to the self-signed certificate (PEM) to upload to Telegram during webhook registration. Required for self-signed certs (direct IP or no domain).", "type": "string" }, "actions": { "type": "object", "properties": { "reactions": { "type": "boolean" }, "sendMessage": { "type": "boolean" }, "poll": { "type": "boolean" }, "deleteMessage": { "type": "boolean" }, "editMessage": { "type": "boolean" }, "sticker": { "type": "boolean" }, "createForumTopic": { "type": "boolean" }, "editForumTopic": { "type": "boolean" } }, "additionalProperties": false }, "threadBindings": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "idleHours": { "type": "number", "minimum": 0 }, "maxAgeHours": { "type": "number", "minimum": 0 }, "spawnSessions": { "type": "boolean" }, "defaultSpawnContext": { "type": "string", "enum": [ "isolated", "fork" ] }, "spawnSubagentSessions": { "type": "boolean" }, "spawnAcpSessions": { "type": "boolean" } }, "additionalProperties": false }, "reactionNotifications": { "type": "string", "enum": [ "off", "own", "all" ] }, "reactionLevel": { "type": "string", "enum": [ "off", "ack", "minimal", "extensive" ] }, "heartbeat": { "type": "object", "properties": { "showOk": { "type": "boolean" }, "showAlerts": { "type": "boolean" }, "useIndicator": { "type": "boolean" } }, "additionalProperties": false }, "healthMonitor": { "type": "object", "properties": { "enabled": { "type": "boolean" } }, "additionalProperties": false }, "linkPreview": { "type": "boolean" }, "silentErrorReplies": { "type": "boolean" }, "responsePrefix": { "type": "string" }, "ackReaction": { "type": "string" }, "errorPolicy": { "type": "string", "enum": [ "always", "once", "silent" ] }, "errorCooldownMs": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "apiRoot": { "type": "string", "format": "uri" }, "trustedLocalFileRoots": { "description": "Trusted local filesystem roots for self-hosted Telegram Bot API absolute file_path values. Only absolute paths under these roots are read directly; all other absolute paths are rejected.", "type": "array", "items": { "type": "string" } }, "autoTopicLabel": { "anyOf": [ { "type": "boolean" }, { "type": "object", "properties": { "enabled": { "type": "boolean" }, "prompt": { "type": "string" } }, "additionalProperties": false } ] } }, "required": [ "dmPolicy", "groupPolicy" ], "additionalProperties": false } }, "defaultAccount": { "type": "string" } }, "required": [ "dmPolicy", "groupPolicy" ], "additionalProperties": false }, "label": "Telegram", "description": "simplest way to get started — register a bot with @BotFather and get going.", "uiHints": { "": { "label": "Telegram", "help": "Telegram channel provider configuration including auth tokens, retry behavior, and message rendering controls. Use this section to tune bot behavior for Telegram-specific API semantics." }, "customCommands": { "label": "Telegram Custom Commands", "help": "Additional Telegram bot menu commands (merged with native; conflicts ignored)." }, "botToken": { "label": "Telegram Bot Token", "help": "Telegram bot token used to authenticate Bot API requests for this account/provider config. Use secret/env substitution and rotate tokens if exposure is suspected." }, "dmPolicy": { "label": "Telegram DM Policy", "help": "Direct message access control (\"pairing\" recommended). \"open\" requires channels.telegram.allowFrom=[\"*\"]." }, "dm.threadReplies": { "label": "Telegram DM Thread Replies", "help": "Controls whether Telegram DMs with message_thread_id use flat sessions (\"off\", default) or thread-scoped sessions (\"inbound\" or \"always\"). Thread IDs are still preserved for replies when sessions stay flat." }, "direct.*.threadReplies": { "label": "Telegram Per-DM Thread Replies", "help": "Per-DM override for message_thread_id session threading. Use \"inbound\" only when a specific direct chat intentionally uses Telegram DM topics as separate sessions." }, "configWrites": { "label": "Telegram Config Writes", "help": "Allow Telegram to write config in response to channel events/commands (default: true)." }, "commands.native": { "label": "Telegram Native Commands", "help": "Override native commands for Telegram (bool or \"auto\")." }, "commands.nativeSkills": { "label": "Telegram Native Skill Commands", "help": "Override native skill commands for Telegram (bool or \"auto\")." }, "streaming": { "label": "Telegram Streaming Mode", "help": "Unified Telegram stream preview mode: \"off\" | \"partial\" | \"block\" | \"progress\" (default: \"partial\"). \"progress\" keeps a single editable progress draft until final delivery. Legacy boolean/streamMode keys are detected; run doctor --fix to migrate." }, "streaming.mode": { "label": "Telegram Streaming Mode", "help": "Canonical Telegram preview mode: \"off\" | \"partial\" | \"block\" | \"progress\" (default: \"partial\")." }, "streaming.chunkMode": { "label": "Telegram Chunk Mode", "help": "Chunking mode for outbound Telegram text delivery: \"length\" (default) or \"newline\"." }, "streaming.block.enabled": { "label": "Telegram Block Streaming Enabled", "help": "Enable chunked block-style Telegram preview delivery when channels.telegram.streaming.mode=\"block\"." }, "streaming.block.coalesce": { "label": "Telegram Block Streaming Coalesce", "help": "Merge streamed Telegram block replies before sending final delivery." }, "streaming.preview.chunk.minChars": { "label": "Telegram Draft Chunk Min Chars", "help": "Minimum chars before emitting a Telegram block preview chunk when channels.telegram.streaming.mode=\"block\"." }, "streaming.preview.chunk.maxChars": { "label": "Telegram Draft Chunk Max Chars", "help": "Target max size for a Telegram block preview chunk when channels.telegram.streaming.mode=\"block\"." }, "streaming.preview.chunk.breakPreference": { "label": "Telegram Draft Chunk Break Preference", "help": "Preferred breakpoints for Telegram draft chunks (paragraph | newline | sentence)." }, "streaming.preview.toolProgress": { "label": "Telegram Draft Tool Progress", "help": "Show tool/progress activity in the live draft preview message (default: true when preview streaming is active). Set false to keep tool updates out of the edited Telegram preview." }, "streaming.preview.commandText": { "label": "Telegram Draft Command Text", "help": "Command/exec detail in preview tool-progress lines: \"raw\" preserves released behavior; \"status\" shows only the tool label." }, "streaming.progress.label": { "label": "Telegram Progress Label", "help": "Initial progress draft title. Use \"auto\" for built-in single-word labels, a custom string, or false to hide the title." }, "streaming.progress.labels": { "label": "Telegram Progress Label Pool", "help": "Candidate labels for streaming.progress.label=\"auto\". Leave unset to use OpenClaw built-in progress labels." }, "streaming.progress.maxLines": { "label": "Telegram Progress Max Lines", "help": "Maximum number of compact progress lines to keep below the draft label (default: 8)." }, "streaming.progress.toolProgress": { "label": "Telegram Progress Tool Lines", "help": "Show compact tool/progress lines in progress draft mode (default: true). Set false to keep only the label until final delivery." }, "streaming.progress.commandText": { "label": "Telegram Progress Command Text", "help": "Command/exec detail in progress draft lines: \"raw\" preserves released behavior; \"status\" shows only the tool label." }, "retry.attempts": { "label": "Telegram Retry Attempts", "help": "Max retry attempts for outbound Telegram API calls (default: 3)." }, "retry.minDelayMs": { "label": "Telegram Retry Min Delay (ms)", "help": "Minimum retry delay in ms for Telegram outbound calls." }, "retry.maxDelayMs": { "label": "Telegram Retry Max Delay (ms)", "help": "Maximum retry delay cap in ms for Telegram outbound calls." }, "retry.jitter": { "label": "Telegram Retry Jitter", "help": "Jitter factor (0-1) applied to Telegram retry delays." }, "network.autoSelectFamily": { "label": "Telegram autoSelectFamily", "help": "Override Node autoSelectFamily for Telegram (true=enable, false=disable)." }, "network.dangerouslyAllowPrivateNetwork": { "label": "Telegram Dangerously Allow Private Network", "help": "Dangerous opt-in for trusted fake-IP or transparent-proxy environments where Telegram media downloads resolve api.telegram.org to private/internal/special-use addresses." }, "timeoutSeconds": { "label": "Telegram API Timeout (seconds)", "help": "Max seconds before Telegram API requests are aborted (default: 500 per grammY)." }, "mediaGroupFlushMs": { "label": "Telegram Media Group Flush (ms)", "help": "Milliseconds to buffer Telegram albums/media groups before dispatching them as one inbound message. Default: 500." }, "pollingStallThresholdMs": { "label": "Telegram Polling Stall Threshold (ms)", "help": "Milliseconds without completed Telegram getUpdates liveness before the polling watchdog restarts the polling runner. Default: 120000." }, "silentErrorReplies": { "label": "Telegram Silent Error Replies", "help": "When true, Telegram bot replies marked as errors are sent silently (no notification sound). Default: false." }, "apiRoot": { "label": "Telegram API Root URL", "help": "Custom Telegram Bot API root URL. Use the API root only (for example https://api.telegram.org), not a full /bot endpoint. Use for self-hosted Bot API servers (https://github.com/tdlib/telegram-bot-api) or reverse proxies in regions where api.telegram.org is blocked." }, "trustedLocalFileRoots": { "label": "Telegram Trusted Local File Roots", "help": "Trusted local filesystem roots for self-hosted Telegram Bot API absolute file_path values. Only absolute paths inside these roots are read directly; all other absolute paths are rejected." }, "autoTopicLabel": { "label": "Telegram Auto Topic Label", "help": "Auto-rename DM forum topics on first message using LLM. Default: true. Set to false to disable, or use object form { enabled: true, prompt: '...' } for custom prompt." }, "autoTopicLabel.enabled": { "label": "Telegram Auto Topic Label Enabled", "help": "Whether auto topic labeling is enabled. Default: true." }, "autoTopicLabel.prompt": { "label": "Telegram Auto Topic Label Prompt", "help": "Custom prompt for LLM-based topic naming. The user message is appended after the prompt." }, "capabilities.inlineButtons": { "label": "Telegram Inline Buttons", "help": "Enable Telegram inline button components for supported command and interaction surfaces. Disable if your deployment needs plain-text-only compatibility behavior." }, "execApprovals": { "label": "Telegram Exec Approvals", "help": "Telegram-native exec approval routing and approver authorization. When unset, OpenClaw auto-enables DM-first native approvals if approvers can be resolved for the selected bot account." }, "execApprovals.enabled": { "label": "Telegram Exec Approvals Enabled", "help": "Controls Telegram native exec approvals for this account: unset or \"auto\" enables DM-first native approvals when approvers can be resolved, true forces native approvals on, and false disables them." }, "execApprovals.approvers": { "label": "Telegram Exec Approval Approvers", "help": "Telegram user IDs allowed to approve exec requests for this bot account. Use numeric Telegram user IDs. If you leave this unset, OpenClaw falls back to numeric owner IDs inferred from commands.ownerAllowFrom when possible." }, "execApprovals.agentFilter": { "label": "Telegram Exec Approval Agent Filter", "help": "Optional allowlist of agent IDs eligible for Telegram exec approvals, for example `[\"main\", \"ops-agent\"]`. Use this to keep approval prompts scoped to the agents you actually operate from Telegram." }, "execApprovals.sessionFilter": { "label": "Telegram Exec Approval Session Filter", "help": "Optional session-key filters matched as substring or regex-style patterns before Telegram approval routing is used. Use narrow patterns so Telegram approvals only appear for intended sessions." }, "execApprovals.target": { "label": "Telegram Exec Approval Target", "help": "Controls where Telegram approval prompts are sent: \"dm\" sends to approver DMs (default), \"channel\" sends to the originating Telegram chat/topic, and \"both\" sends to both. Channel delivery exposes the command text to the chat, so only use it in trusted groups/topics." }, "threadBindings.enabled": { "label": "Telegram Thread Binding Enabled", "help": "Enable Telegram conversation binding features (/focus, /unfocus, /agents, and /session idle|max-age). Overrides session.threadBindings.enabled when set." }, "threadBindings.idleHours": { "label": "Telegram Thread Binding Idle Timeout (hours)", "help": "Inactivity window in hours for Telegram bound sessions. Set 0 to disable idle auto-unfocus (default: 24). Overrides session.threadBindings.idleHours when set." }, "threadBindings.maxAgeHours": { "label": "Telegram Thread Binding Max Age (hours)", "help": "Optional hard max age in hours for Telegram bound sessions. Set 0 to disable hard cap (default: 0). Overrides session.threadBindings.maxAgeHours when set." }, "threadBindings.spawnSessions": { "label": "Telegram Thread-Bound Session Spawn", "help": "Allow sessions_spawn(thread=true) and ACP thread spawns to auto-bind Telegram current conversations when supported." }, "threadBindings.defaultSpawnContext": { "label": "Telegram Thread Spawn Context", "help": "Default native subagent context for thread-bound spawns. \"fork\" starts from the requester transcript; \"isolated\" starts clean. Default: \"fork\"." } } } } }