{"id":"ccbbab27-5888-4ddd-89d8-ead44e82a3ae","shortId":"U9Xbxm","kind":"skill","title":"instar-telegram","tagline":"Send and receive messages via Telegram for two-way agent communication. Use when the agent needs to notify the user, alert them about something, relay a response, or when Telegram messaging is the requested channel. Trigger words: send message, Telegram, notify, alert user, messa","description":"# instar-telegram — Two-Way Telegram Messaging for Agents\n\nInstar provides native Telegram integration that turns your Telegram group into a living dashboard. Each scheduled job gets its own forum topic. You can message your agent from your phone and get replies anywhere. The agent can reach out proactively when it needs your attention.\n\n## Getting Started\n\nBefore using this skill, check if Instar is available:\n\n1. Check for Instar: `ls .instar/config.json 2>/dev/null || which instar 2>/dev/null`\n2. If neither exists, Instar is not installed. Tell the user:\n\n   > \"Right now, to see what your agent is doing, you have to sit at your computer and read the terminal. If it finishes a job at 3 AM, you don't know until you check. If it hits a problem and needs your input, it just... waits.\n   >\n   > **Instar connects your agent to Telegram.** Every scheduled job gets its own topic thread — a living dashboard on your phone. Your agent messages you when something needs attention. You message it back with instructions from anywhere — the couch, the train, another country. It's two-way: you're not just monitoring, you're collaborating.\n   >\n   > It takes about 2 minutes to set up. One command:\n   >\n   > ```\n   > npx instar\n   > ```\n   >\n   > Your agent goes from something you check on to something that reaches out to you. [Learn more at instar.sh](https://instar.sh)\"\n\n   If the user agrees, run `npx instar` and follow the interactive setup.\n   If they decline, acknowledge and suggest they visit https://instar.sh when ready.\n\n3. If Instar is installed, verify the server: `curl -sf http://localhost:4040/health`\n4. If server is not running: \"The Instar server needs to be running. Want me to start it? (`instar server start`)\"\n5. Once running, proceed with the instructions below.\n\n**Note**: Telegram integration also requires a configured bot token and group chat ID. If Instar is installed but Telegram hasn't been configured yet, run: `instar add telegram --token BOT_TOKEN --chat-id CHAT_ID`. To get a bot token, message [@BotFather](https://t.me/BotFather) on Telegram and use `/newbot`. To get your chat ID, add the bot to a group, then check `https://api.telegram.org/bot<TOKEN>/getUpdates`.\n\n---\n\n## Core Concepts\n\n- **Topics** are Telegram Forum topic threads that map to Claude sessions.\n- **One topic per session**: Messages in a topic go to its paired Claude session.\n- **/new command**: Sends `/new` in Telegram to create a fresh topic with a new session.\n- **Job topics**: Each scheduled job automatically gets its own topic for status updates.\n- **Proactive messaging**: The agent can send to any topic at any time, not just in reply.\n\nYour Telegram group becomes a dashboard where you can see what every job is doing, send instructions to any session, and get notified of anything that needs attention.\n\n---\n\n## Sending Messages\n\n### Send to a specific topic\n\n```bash\nAUTH=$(python3 -c \"import json; print(json.load(open('.instar/config.json'))['auth']['token'])\")\n\n# Get available topics first\ncurl -s http://localhost:4040/telegram/topics \\\n  -H \"Authorization: Bearer $AUTH\" | python3 -m json.tool\n\n# Send a message to topic ID 123\ncurl -s -X POST http://localhost:4040/telegram/reply/123 \\\n  -H 'Content-Type: application/json' \\\n  -H \"Authorization: Bearer $AUTH\" \\\n  -d '{\"text\": \"Task complete! Report is at docs/report.md\"}'\n```\n\n### Send using the relay script (simpler, no auth needed in-session)\n\nIf `.claude/scripts/telegram-reply.sh` exists (created during instar setup):\n\n```bash\n# Send to topic 123\ncat <<'EOF' | .claude/scripts/telegram-reply.sh 123\nYour message here.\n\nCan be multi-line.\nEOF\n```\n\n### Telegram message formatting\n\nTelegram supports markdown for formatting:\n\n```bash\ncurl -s -X POST http://localhost:4040/telegram/reply/123 \\\n  -H 'Content-Type: application/json' \\\n  -H \"Authorization: Bearer $AUTH\" \\\n  -d '{\n    \"text\": \"*Task complete!*\\n\\n_Duration: 4 minutes_\\n\\nReport written to `docs/report.md`\"\n  }'\n```\n\nSupported: `*bold*`, `_italic_`, `` `code` ``, `[link](url)`\n\n---\n\n## Topic Management\n\n### List all topics and their sessions\n\n```bash\nAUTH=$(python3 -c \"import json; print(json.load(open('.instar/config.json'))['auth']['token'])\")\n\ncurl -s http://localhost:4040/telegram/topics \\\n  -H \"Authorization: Bearer $AUTH\" | python3 -m json.tool\n```\n\nResponse shows each topic's ID, name, and which session it's paired with.\n\n### Check message history for a topic\n\n```bash\n# Last 20 messages\ncurl -s \"http://localhost:4040/telegram/topics/123/messages?limit=20\" \\\n  -H \"Authorization: Bearer $AUTH\" | python3 -m json.tool\n```\n\n---\n\n## Receiving Messages\n\nWhen a user sends a message in a Telegram topic, the instar server receives it and injects it into the corresponding Claude session. Messages arrive in this format:\n\n```\n[telegram:123] User message text here\n```\n\nWhen handling messages with this prefix:\n\n1. Strip the `[telegram:N]` prefix before interpreting the message content\n2. Process the request\n3. Send the response back to topic N using the relay methods above\n\n### Handling Telegram input in session prompts\n\nIf a session was spawned to handle Telegram input, structure it to handle the relay:\n\n```json\n{\n  \"name\": \"interactive-chat\",\n  \"prompt\": \"You are handling messages from Telegram. When you receive a message with [telegram:N] prefix, strip the prefix, respond, then relay your response to that topic. Use .claude/scripts/telegram-reply.sh to send replies.\"\n}\n```\n\n---\n\n## Proactive Messaging Patterns\n\n### Alert the user when something needs attention\n\n```bash\nAUTH=$(python3 -c \"import json; print(json.load(open('.instar/config.json'))['auth']['token'])\")\n\n# Get the primary/interactive topic ID from config\nPRIMARY_TOPIC=$(python3 -c \"\nimport json\nconfig = json.load(open('.instar/config.json'))\nprint(config.get('telegram', {}).get('primaryTopicId', ''))\n\")\n\n# Send an alert\ncurl -s -X POST \"http://localhost:4040/telegram/reply/$PRIMARY_TOPIC\" \\\n  -H 'Content-Type: application/json' \\\n  -H \"Authorization: Bearer $AUTH\" \\\n  -d '{\"text\": \"⚠️ Health check failed: database connection timeout. Investigating.\"}'\n```\n\n### Job completion notifications\n\nWhen a scheduled job completes, instar automatically posts a summary to the job's Telegram topic. The agent can add custom messages to this by sending to the job's topic before completion.\n\n### Structured status updates\n\nFor complex jobs, send incremental updates as the work proceeds:\n\n```bash\n# At the start of a long job\nsend_status() {\n  local topic=$1\n  local message=$2\n  curl -s -X POST \"http://localhost:4040/telegram/reply/$topic\" \\\n    -H 'Content-Type: application/json' \\\n    -H \"Authorization: Bearer $AUTH\" \\\n    -d \"{\\\"text\\\": \\\"$message\\\"}\" > /dev/null\n}\n\nsend_status 456 \"Starting audit... fetching dependencies\"\n# ... do work ...\nsend_status 456 \"Dependencies checked. Reviewing auth flows...\"\n# ... more work ...\nsend_status 456 \"Audit complete. Report at docs/audit.md\"\n```\n\n---\n\n## The /new Command\n\nSending `/new` in the Telegram group creates a fresh forum topic with a new Claude session. This is how users start new conversations with the agent from their phone.\n\nThe session inherits:\n- Full project context from `CLAUDE.md`\n- Agent identity from `AGENT.md` and `USER.md`\n- Recent memory from `MEMORY.md`\n- All skills and scripts\n\nNew sessions auto-expire after inactivity but can be respawned by sending a message to the topic.\n\n---\n\n## Using Telegram as a Living Dashboard\n\nWith jobs configured, your Telegram group shows:\n\n- **One topic per job**: See what each scheduled task last reported\n- **Interactive topic**: Your main conversation channel\n- **Health check topic**: Server status every 5 minutes\n\nThis creates a persistent view of your agent's activity without needing to check logs or run CLI commands. The dashboard updates itself as jobs run.\n\n---\n\n## Troubleshooting\n\n### Test the Telegram connection\n\n```bash\ncurl -s http://localhost:4040/status | python3 -c \"\nimport json, sys\ns = json.load(sys.stdin)\ntg = s.get('telegram', {})\nprint('Telegram connected:', tg.get('connected', False))\nprint('Bot username:', tg.get('botUsername', 'unknown'))\n\"\n```\n\n### View recent Telegram events\n\n```bash\nAUTH=$(python3 -c \"import json; print(json.load(open('.instar/config.json'))['auth']['token'])\")\ncurl -s \"http://localhost:4040/events?type=telegram_message&since=1\" \\\n  -H \"Authorization: Bearer $AUTH\" | python3 -m json.tool\n```\n\n### Messages not arriving in sessions\n\n1. Verify the server is running: `curl http://localhost:4040/health`\n2. Check topic-session mapping: `curl http://localhost:4040/telegram/topics`\n3. Verify the bot is in your group and has message permissions\n4. Check server logs: `.instar/logs/server.log`","tags":["instar","telegram","jkheadley","agent-framework","agent-identity","agent-infrastructure","agent-memory","agent-skills","ai-agents","ai-safety","autonomous-agents","claude-code"],"capabilities":["skill","source-jkheadley","skill-instar-telegram","topic-agent-framework","topic-agent-identity","topic-agent-infrastructure","topic-agent-memory","topic-agent-skills","topic-ai-agents","topic-ai-safety","topic-autonomous-agents","topic-claude-code","topic-cli","topic-cron","topic-job-scheduler"],"categories":["instar"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/JKHeadley/instar/instar-telegram","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add JKHeadley/instar","source_repo":"https://github.com/JKHeadley/instar","install_from":"skills.sh"}},"qualityScore":"0.479","qualityRationale":"deterministic score 0.48 from registry signals: · indexed on github topic:agent-skills · 59 github stars · SKILL.md body (8,707 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-02T06:55:53.582Z","embedding":null,"createdAt":"2026-04-18T22:14:37.629Z","updatedAt":"2026-05-02T06:55:53.582Z","lastSeenAt":"2026-05-02T06:55:53.582Z","tsv":"'/bot':402 '/botfather)':381 '/dev/null':122,126,1001 '/getupdates':403 '/new':431,434,1030,1033 '/newbot':386 '1':115,758,978,1222,1235 '123':543,590,594,747 '2':121,125,127,243,769,981,1244 '20':701,708 '3':164,295,773,1253 '4':307,635,1265 '4040/events':1217 '4040/health':306,1243 '4040/status':1174 '4040/telegram/reply':896,987 '4040/telegram/reply/123':549,618 '4040/telegram/topics':529,671,1252 '4040/telegram/topics/123/messages':706 '456':1004,1013,1023 '5':328,1137 'acknowledg':287 'activ':1148 'add':362,392,939 'agent':14,19,58,85,94,144,188,206,253,462,937,1057,1069,1146 'agent.md':1072 'agre':275 'alert':25,46,847,890 'also':339 'anoth':225 'anyth':499 'anywher':92,220 'api.telegram.org':401 'api.telegram.org/bot':400 'application/json':554,623,903,993 'arriv':742,1232 'attent':103,212,502,853 'audit':1006,1024 'auth':511,520,533,558,574,627,657,666,675,712,855,864,907,997,1017,1203,1212,1226 'author':531,556,625,673,710,905,995,1224 'auto':1086 'auto-expir':1085 'automat':451,926 'avail':114,523 'back':216,777 'bash':510,586,612,656,699,854,966,1170,1202 'bearer':532,557,626,674,711,906,996,1225 'becom':478 'bold':643 'bot':343,365,375,394,1193,1256 'botfath':378 'botusernam':1196 'c':513,659,857,876,1176,1205 'cat':591 'channel':39,1130 'chat':347,368,370,390,811 'chat-id':367 'check':110,116,172,258,399,693,911,1015,1132,1152,1245,1266 'claud':415,429,739,1046 'claude.md':1068 'claude/scripts/telegram-reply.sh':580,593,840 'cli':1156 'code':645 'collabor':239 'command':249,432,1031,1157 'communic':15 'complet':562,631,918,924,952,1025 'complex':957 'comput':153 'concept':405 'config':872,879 'config.get':884 'configur':342,358,1109 'connect':186,914,1169,1188,1190 'content':552,621,768,901,991 'content-typ':551,620,900,990 'context':1066 'convers':1054,1129 'core':404 'correspond':738 'couch':222 'countri':226 'creat':438,582,1038,1140 'curl':303,526,544,613,668,703,891,982,1171,1214,1241,1250 'custom':940 'd':559,628,908,998 'dashboard':72,201,480,1106,1159 'databas':913 'declin':286 'depend':1008,1014 'docs/audit.md':1028 'docs/report.md':566,641 'durat':634 'eof':592,603 'event':1201 'everi':191,486,1136 'exist':130,581 'expir':1087 'fail':912 'fals':1191 'fetch':1007 'finish':160 'first':525 'flow':1018 'follow':280 'format':606,611,745 'forum':79,409,1041 'fresh':440,1040 'full':1064 'get':76,90,104,194,373,388,452,496,522,866,886 'go':425 'goe':254 'group':68,346,397,477,1037,1112,1260 'h':530,550,555,619,624,672,709,899,904,989,994,1223 'handl':753,786,798,804,815 'hasn':355 'health':910,1131 'histori':695 'hit':175 'id':348,369,371,391,542,684,870 'ident':1070 'import':514,660,858,877,1177,1206 'in-sess':576 'inact':1089 'increment':960 'inherit':1063 'inject':734 'input':181,788,800 'instal':134,299,352 'instar':2,50,59,112,118,124,131,185,251,278,297,314,325,350,361,584,729,925 'instar-telegram':1,49 'instar.sh':270,271,292 'instar/config.json':120,519,665,863,882,1211 'instar/logs/server.log':1269 'instruct':218,334,491 'integr':63,338 'interact':282,810,1125 'interactive-chat':809 'interpret':765 'investig':916 'ital':644 'job':75,162,193,446,450,487,917,923,932,948,958,973,1108,1117,1163 'json':515,661,807,859,878,1178,1207 'json.load':517,663,861,880,1181,1209 'json.tool':536,678,715,1229 'know':169 'last':700,1123 'learn':267 'limit':707 'line':602 'link':646 'list':650 'live':71,200,1105 'local':976,979 'localhost':305,528,548,617,670,705,895,986,1173,1216,1242,1251 'log':1153,1268 'long':972 'ls':119 'm':535,677,714,1228 'main':1128 'manag':649 'map':413,1249 'markdown':609 'memori':1076 'memory.md':1078 'messa':48 'messag':7,35,43,56,83,207,214,377,421,460,504,539,596,605,694,702,717,723,741,749,754,767,816,823,845,941,980,1000,1097,1220,1230,1263 'method':784 'minut':244,636,1138 'monitor':236 'multi':601 'multi-lin':600 'n':632,633,637,762,780,826 'name':685,808 'nativ':61 'need':20,101,179,211,316,501,575,852,1150 'neither':129 'new':444,1045,1053,1083 'note':336 'notif':919 'notifi':22,45,497 'npx':250,277 'nreport':638 'one':248,417,1114 'open':518,664,862,881,1210 'pair':428,691 'pattern':846 'per':419,1116 'permiss':1264 'persist':1142 'phone':88,204,1060 'post':547,616,894,927,985 'prefix':757,763,827,830 'primari':873,897 'primary/interactive':868 'primarytopicid':887 'print':516,662,860,883,1186,1192,1208 'proactiv':98,459,844 'problem':177 'proceed':331,965 'process':770 'project':1065 'prompt':791,812 'provid':60 'python3':512,534,658,676,713,856,875,1175,1204,1227 're':233,238 'reach':96,263 'read':155 'readi':294 'receiv':6,716,731,821 'recent':1075,1199 'relay':29,570,783,806,833 'repli':91,474,843 'report':563,1026,1124 'request':38,772 'requir':340 'respawn':1093 'respond':831 'respons':31,679,776,835 'review':1016 'right':138 'run':276,312,319,330,360,1155,1164,1240 's.get':1184 'schedul':74,192,449,922,1121 'script':571,1082 'see':141,484,1118 'send':4,42,433,464,490,503,505,537,567,587,721,774,842,888,945,959,974,1002,1011,1021,1032,1095 'server':302,309,315,326,730,1134,1238,1267 'session':416,420,430,445,494,578,655,688,740,790,794,1047,1062,1084,1234,1248 'set':246 'setup':283,585 'sf':304 'show':680,1113 'simpler':572 'sinc':1221 'sit':150 'skill':109,1080 'skill-instar-telegram' 'someth':28,210,256,261,851 'source-jkheadley' 'spawn':796 'specif':508 'start':105,323,327,969,1005,1052 'status':457,954,975,1003,1012,1022,1135 'strip':759,828 'structur':801,953 'suggest':289 'summari':929 'support':608,642 'sys':1179 'sys.stdin':1182 't.me':380 't.me/botfather)':379 'take':241 'task':561,630,1122 'telegram':3,9,34,44,51,55,62,67,190,337,354,363,383,408,436,476,604,607,726,746,761,787,799,818,825,885,934,1036,1102,1111,1168,1185,1187,1200,1219 'tell':135 'termin':157 'test':1166 'text':560,629,750,909,999 'tg':1183 'tg.get':1189,1195 'thread':198,411 'time':470 'timeout':915 'token':344,364,366,376,521,667,865,1213 'topic':80,197,406,410,418,424,441,447,455,467,509,524,541,589,648,652,682,698,727,779,838,869,874,898,935,950,977,988,1042,1100,1115,1126,1133,1247 'topic-agent-framework' 'topic-agent-identity' 'topic-agent-infrastructure' 'topic-agent-memory' 'topic-agent-skills' 'topic-ai-agents' 'topic-ai-safety' 'topic-autonomous-agents' 'topic-claude-code' 'topic-cli' 'topic-cron' 'topic-job-scheduler' 'topic-sess':1246 'train':224 'trigger':40 'troubleshoot':1165 'turn':65 'two':12,53,230 'two-way':11,52,229 'type':553,622,902,992,1218 'unknown':1197 'updat':458,955,961,1160 'url':647 'use':16,107,385,568,781,839,1101 'user':24,47,137,274,720,748,849,1051 'user.md':1074 'usernam':1194 'verifi':300,1236,1254 'via':8 'view':1143,1198 'visit':291 'wait':184 'want':320 'way':13,54,231 'without':1149 'word':41 'work':964,1010,1020 'written':639 'x':546,615,893,984 'yet':359","prices":[{"id":"46115ae1-b570-45c2-9e0f-4cf43174a52a","listingId":"ccbbab27-5888-4ddd-89d8-ead44e82a3ae","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"JKHeadley","category":"instar","install_from":"skills.sh"},"createdAt":"2026-04-18T22:14:37.629Z"}],"sources":[{"listingId":"ccbbab27-5888-4ddd-89d8-ead44e82a3ae","source":"github","sourceId":"JKHeadley/instar/instar-telegram","sourceUrl":"https://github.com/JKHeadley/instar/tree/main/skills/instar-telegram","isPrimary":false,"firstSeenAt":"2026-04-18T22:14:37.629Z","lastSeenAt":"2026-05-02T06:55:53.582Z"}],"details":{"listingId":"ccbbab27-5888-4ddd-89d8-ead44e82a3ae","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"JKHeadley","slug":"instar-telegram","github":{"repo":"JKHeadley/instar","stars":59,"topics":["agent-framework","agent-identity","agent-infrastructure","agent-memory","agent-skills","ai-agents","ai-safety","autonomous-agents","claude-code","cli","cron","job-scheduler","llm","mcp","npm-package","open-source","persistency","telegram-bot","typescript","whatsapp"],"license":"mit","html_url":"https://github.com/JKHeadley/instar","pushed_at":"2026-05-02T05:23:59Z","description":"Persistent Claude Code agents with scheduling, sessions, memory, and Telegram.","skill_md_sha":"1a4012f8a6c26497affa9c810b37ba3c06472b42","skill_md_path":"skills/instar-telegram/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/JKHeadley/instar/tree/main/skills/instar-telegram"},"layout":"multi","source":"github","category":"instar","frontmatter":{"name":"instar-telegram","license":"MIT","description":"Send and receive messages via Telegram for two-way agent communication. Use when the agent needs to notify the user, alert them about something, relay a response, or when Telegram messaging is the requested channel. Trigger words: send message, Telegram, notify, alert user, message me, ping me, let me know, reach out.","compatibility":"Works best with instar (npx instar). If not installed, the skill will guide you through setup."},"skills_sh_url":"https://skills.sh/JKHeadley/instar/instar-telegram"},"updatedAt":"2026-05-02T06:55:53.582Z"}}