{ "schema": "snappy-card/1", "skill": "snappy-telegram", "tier": "public", "origin_tier": "base", "purpose": "You handle Snappy's Telegram channel: Robert self-notifications (morning briefings, EOD digests, deploy/revenue/error alerts, long-running task progress). Direct Bot API calls to `api.telegram.org` -- no Xano middleware.", "verbs": [ { "name": "read", "args": [ "limit?" ], "effect": "read", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts read" }, { "name": "messages", "args": [ "limit?" ], "effect": "read", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts messages" }, { "name": "updates", "args": [], "effect": "read", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts updates" }, { "name": "me", "args": [], "effect": "read", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts me" }, { "name": "send", "args": [ "text" ], "effect": "send", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts send \"\"" }, { "name": "photo", "args": [ "url", "caption?" ], "effect": "send", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts photo " }, { "name": "document", "args": [ "url", "caption?" ], "effect": "send", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts document " }, { "name": "video", "args": [ "url", "caption?" ], "effect": "send", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts video " }, { "name": "voice", "args": [ "url", "caption?" ], "effect": "send", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts voice " }, { "name": "poll", "args": [ "question", "options-json" ], "effect": "send", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts poll '[\"\"]'" }, { "name": "keyboard", "args": [ "text", "keyboard-json" ], "effect": "send", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts keyboard \"\" '[\"\"]'" }, { "name": "edit", "args": [ "message_id", "text" ], "effect": "write-reversible", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts edit \"\"" }, { "name": "delete", "args": [ "message_id" ], "effect": "delete", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts delete " }, { "name": "show", "args": [ "kind" ], "effect": "send", "firstCall": " --json \\" }, { "name": "album", "args": [ "kind" ], "effect": "send", "firstCall": " --json \\" }, { "name": "decisions", "args": [], "effect": "read", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts decisions" }, { "name": "progress", "args": [ "message_id", "text" ], "effect": "write-reversible", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts progress \"\"" }, { "name": "replace", "args": [ "message_id", "kind" ], "effect": "write-reversible", "firstCall": "npx tsx ~/.claude/skills/snappy-telegram/api.ts replace --from " } ], "faces": [], "agents": [], "uses": [ "snappy-ops", "snappy-slack", "snappy-whatsapp", "snappy-deploy", "snappy-freshbooks" ], "used_by": [ "snappy-client-ray", "snappy-slack" ], "checks": { "pass": 41, "fail": 13, "defer": 7, "line": "41 of 54 checks pass", "failing": [ { "id": 4, "rule": "Near-neighbour descriptions cross-reference each other", "says": "near neighbours not named: snappy-client-feisst, snappy-runner, snappy-specwatch" }, { "id": 5, "rule": "Description is valid, third-person, and says what plus when", "says": "1305 chars" }, { "id": 7, "rule": "Promised and declared verbs have no set difference", "says": "promised-only=[list, draft]; loader-missing=[]" }, { "id": 8, "rule": "Skill body and reference graph stay within disclosure budgets", "says": "498 lines; ~7278 tokens" }, { "id": 9, "rule": "Time-sensitive prose is isolated under Old patterns", "says": "2 time-sensitive instruction line(s) outside Old patterns" }, { "id": 10, "rule": "One term names each concept", "says": "mixed synonym sets: endpoint/url/route/path" }, { "id": 24, "rule": "Answer size is bounded by requested limit", "says": "unbounded growth: read:non-monotone, messages:non-monotone, updates:non-monotone" }, { "id": 40, "rule": "Metadata, skill body, and resources follow three-level budgets", "says": "metadata ~327 tokens; body ~7278 tokens" }, { "id": 43, "rule": "A read is one call, not a queued job", "says": "messages:p50>3s-or-missing, decisions:p50>3s-or-missing" }, { "id": 54, "rule": "At least three eval scenarios precede ready status", "says": "0 eval scenario(s); ready=true" }, { "id": 55, "rule": "Eval scenarios are multi-call with ground truth", "says": "eval manifest missing" }, { "id": 57, "rule": "Eval manifest contains a disjoint holdout", "says": "0 disjoint holdout scenario(s)" }, { "id": 60, "rule": "Loader publishes the contract's derived first call, current", "says": "generated block is stale against HAND_CONTRACT; run fix-loader" } ] }, "coverage": null, "spec": null, "evals": null, "files": [ "AGENTS.md", "SKILL.md", "adapter.ts", "api-reference.md", "api.ts", "face-channel.test.ts", "face.test.ts", "faces.ts", "faces/components/telegram-chat-list.css", "faces/components/telegram-chat-list.tsx", "faces/family.tsx", "faces/fixtures/telegram-decision.json", "faces/fixtures/telegram-draft.json", "faces/fixtures/telegram-list.json", "faces/fixtures/telegram-message.json", "fixtures/callback-query.json", "png.ts", "receipt.test.ts", "receipt.ts", "refusals.test.ts", "workflows.md" ], "total_size": 217144, "checksum": "sha256:9db4c570c598b51f1d21d880f4faa2a02600d4fea8a977bc32bfc5b1c9355dbe", "built_at": "2026-09-09T22:11:10.506Z", "openapi": { "openapi": "3.1.0", "info": { "title": "snappy-telegram", "version": "0.0.0", "description": "Telegram Bot API channel for Snappy: direct calls to api.telegram.org (no Xano middleware) to send text, photos, documents, video, voice, polls, inline keyboards, message edits, and Robert self-notifications (daily digests, morning briefings, deploy alerts, long-task progress via editMessageText); the delivery target for producer skills; getUpdates for debugging incoming messages. Use when Robert says: /snappy-telegram, \\\"send it to my telegram\\\", \\\"notify me on telegram\\\", \\\"i am not getting any messages on telegram\\\", \\\"is telegram working\\\", \\\"summarize what is in my telegram inbox\\\", \\\"post it to linkedin, skool, and telegram\\\", \\\"an agent that responds to me in realtime on telegram\\\", \\\"tg\\\". AND THE FACE CHANNEL: `show`/`album`/`replace` draw any of the 66 snappy-faces as a real card and send it as a photo with its decision doors as pressable inline buttons, `decisions` reads back which door he tapped, `progress` edits one message in place. Triggers on: telegram, tg, bot api, sendMessage, telegram inbox, notify robert, show him the face, send the card to telegram, buttons on telegram, what did he press, telegram genui, face on my phone. NOT Slack (see snappy-slack). NOT WhatsApp (see snappy-whatsapp). NOT the Snappy OS connector plumbing behind Telegram (see snappy-os-operator)." }, "x-snappy-transport": "cli", "servers": [ { "url": "npx tsx ~/.claude/skills/snappy-telegram/api.ts", "description": "The hand itself. Every path is a verb word, every query or body key an argument." } ], "paths": { "/read": { "get": { "operationId": "snappy_telegram_read", "summary": "snappy-telegram read", "x-snappy-effect": "read", "x-snappy-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "How many messages to return, newest last", "default": 20, "maximum": 100, "x-snappy-position": 0 } }, { "name": "json", "in": "query", "required": false, "schema": { "x-snappy-flag": "--json" } } ], "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/messages": { "get": { "operationId": "snappy_telegram_messages", "summary": "snappy-telegram messages", "x-snappy-effect": "read", "x-snappy-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "How many messages to return, newest last", "default": 20, "maximum": 100, "x-snappy-position": 0 } }, { "name": "json", "in": "query", "required": false, "schema": { "x-snappy-flag": "--json" } } ], "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/updates": { "get": { "operationId": "snappy_telegram_updates", "summary": "snappy-telegram updates", "x-snappy-effect": "read", "x-snappy-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "name": "json", "in": "query", "required": false, "schema": { "x-snappy-flag": "--json" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "description": "How many buffered updates to return, oldest first. The count is the FLAG --limit, never a positional word; default 20, ceiling 100", "default": 20, "minimum": 1, "maximum": 100, "x-snappy-flag": "--limit" } } ], "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/me": { "get": { "operationId": "snappy_telegram_me", "summary": "snappy-telegram me", "x-snappy-effect": "read", "x-snappy-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "name": "json", "in": "query", "required": false, "schema": { "x-snappy-flag": "--json" } } ], "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/send": { "post": { "operationId": "snappy_telegram_send", "summary": "snappy-telegram send", "x-snappy-effect": "send", "x-snappy-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "The message's words, verbatim", "x-snappy-position": 0 }, "to": { "x-snappy-flag": "--to" }, "json": { "x-snappy-flag": "--json" } }, "required": [ "text" ] } } } }, "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/photo": { "post": { "operationId": "snappy_telegram_photo", "summary": "snappy-telegram photo", "x-snappy-effect": "send", "x-snappy-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "An http(s) address Telegram can fetch the file from, or a local path this Computer can read", "x-snappy-position": 0 }, "caption": { "type": "string", "description": "The words shown under the file", "x-snappy-position": 1 } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/document": { "post": { "operationId": "snappy_telegram_document", "summary": "snappy-telegram document", "x-snappy-effect": "send", "x-snappy-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "An http(s) address Telegram can fetch the file from, or a local path this Computer can read", "x-snappy-position": 0 }, "caption": { "type": "string", "description": "The words shown under the file", "x-snappy-position": 1 } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/video": { "post": { "operationId": "snappy_telegram_video", "summary": "snappy-telegram video", "x-snappy-effect": "send", "x-snappy-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "An http(s) address Telegram can fetch the file from, or a local path this Computer can read", "x-snappy-position": 0 }, "caption": { "type": "string", "description": "The words shown under the file", "x-snappy-position": 1 } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/voice": { "post": { "operationId": "snappy_telegram_voice", "summary": "snappy-telegram voice", "x-snappy-effect": "send", "x-snappy-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "description": "An http(s) address Telegram can fetch the file from, or a local path this Computer can read", "x-snappy-position": 0 }, "caption": { "type": "string", "description": "The words shown under the file", "x-snappy-position": 1 } }, "required": [ "url" ] } } } }, "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/poll": { "post": { "operationId": "snappy_telegram_poll", "summary": "snappy-telegram poll", "x-snappy-effect": "send", "x-snappy-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "question": { "type": "string", "description": "The poll's question, verbatim", "x-snappy-position": 0 }, "options-json": { "type": "string", "description": "The poll's answers as a JSON array of strings", "x-snappy-position": 1 } }, "required": [ "question", "options-json" ] } } } }, "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/keyboard": { "post": { "operationId": "snappy_telegram_keyboard", "summary": "snappy-telegram keyboard", "x-snappy-effect": "send", "x-snappy-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "text": { "type": "string", "description": "The words above the buttons, verbatim", "x-snappy-position": 0 }, "keyboard-json": { "type": "string", "description": "The buttons as a JSON array of rows, each row an array of `{ text, callback_data }`", "x-snappy-position": 1 } }, "required": [ "text", "keyboard-json" ] } } } }, "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/edit": { "post": { "operationId": "snappy_telegram_edit", "summary": "snappy-telegram edit", "x-snappy-effect": "write-reversible", "x-snappy-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "string", "description": "The Telegram message id this hand returned when it sent the message", "x-snappy-position": 0 }, "text": { "type": "string", "description": "The words that replace the message's current text", "x-snappy-position": 1 } }, "required": [ "message_id", "text" ] } } } }, "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/delete": { "post": { "operationId": "snappy_telegram_delete", "summary": "snappy-telegram delete", "x-snappy-effect": "delete", "x-snappy-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "string", "description": "The Telegram message id this hand returned when it sent the message", "x-snappy-position": 0 } }, "required": [ "message_id" ] } } } }, "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/show": { "post": { "operationId": "snappy_telegram_show", "summary": "snappy-telegram show", "x-snappy-effect": "send", "x-snappy-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "Which face to draw, by its `snappy-faces` kind — `linkedin-post`, `gmail-list`", "x-snappy-position": 0 }, "from": { "x-snappy-flag": "--from" }, "example": { "x-snappy-flag": "--example" }, "idempotency": { "x-snappy-flag": "--idempotency" }, "doors": { "x-snappy-flag": "--doors" }, "caption": { "x-snappy-flag": "--caption" }, "ref": { "x-snappy-flag": "--ref" }, "json": { "x-snappy-flag": "--json" } }, "required": [ "kind" ] } } } }, "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/album": { "post": { "operationId": "snappy_telegram_album", "summary": "snappy-telegram album", "x-snappy-effect": "send", "x-snappy-annotations": { "readOnlyHint": false, "destructiveHint": true, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "description": "Which face to draw, by its `snappy-faces` kind — `linkedin-post`, `gmail-list`", "x-snappy-position": 0 }, "from": { "x-snappy-flag": "--from" }, "example": { "x-snappy-flag": "--example" }, "idempotency": { "x-snappy-flag": "--idempotency" }, "caption": { "x-snappy-flag": "--caption" }, "json": { "x-snappy-flag": "--json" } }, "required": [ "kind" ] } } } }, "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/decisions": { "get": { "operationId": "snappy_telegram_decisions", "summary": "snappy-telegram decisions", "x-snappy-effect": "read", "x-snappy-annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "parameters": [ { "name": "json", "in": "query", "required": false, "schema": { "x-snappy-flag": "--json" } } ], "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/progress": { "post": { "operationId": "snappy_telegram_progress", "summary": "snappy-telegram progress", "x-snappy-effect": "write-reversible", "x-snappy-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "string", "description": "The Telegram message id this hand returned when it sent the message", "x-snappy-position": 0 }, "text": { "type": "string", "description": "The words that replace the message's current text", "x-snappy-position": 1 } }, "required": [ "message_id", "text" ] } } } }, "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } }, "/replace": { "post": { "operationId": "snappy_telegram_replace", "summary": "snappy-telegram replace", "x-snappy-effect": "write-reversible", "x-snappy-annotations": { "readOnlyHint": false, "destructiveHint": false, "idempotentHint": false, "openWorldHint": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "message_id": { "type": "string", "description": "The Telegram message id this hand returned when it sent the message", "x-snappy-position": 0 }, "kind": { "type": "string", "description": "Which face to draw, by its `snappy-faces` kind — `linkedin-post`, `gmail-list`", "x-snappy-position": 1 }, "from": { "x-snappy-flag": "--from" }, "example": { "x-snappy-flag": "--example" }, "idempotency": { "x-snappy-flag": "--idempotency" }, "doors": { "x-snappy-flag": "--doors" }, "caption": { "x-snappy-flag": "--caption" }, "json": { "x-snappy-flag": "--json" } }, "required": [ "message_id", "kind" ] } } } }, "responses": { "200": { "description": "The verb's own answer, as printed by `--json`." } } } } }, "components": { "schemas": { "SnappyRefusal": { "type": "object", "required": [ "outcome", "code", "message" ], "properties": { "outcome": { "type": "string", "const": "refused" }, "code": { "type": "string", "description": "A row of the closed refusal table." }, "message": { "type": "string" }, "fix": { "type": "string" } } } } }, "x-snappy-requires": [ "TELEGRAM_BOT_TOKEN", "TELEGRAM_ROBERT_CHAT_ID" ] } }