telegram-manage-contacts

name	telegram-manage-contacts
description	Manage Telegram contacts for the telegram-notify and telegram-ask skills. Use when the user asks to add, remove, or list Telegram contacts/recipients.
metadata	{"author":"roziscoding","version":"1.0.0"}

Telegram Manage Contacts

Add, remove, and list named contacts stored in ~/.config/telegram-skills/credentials.json. These contacts can be used with --to in the telegram-notify and telegram-ask skills.

Usage

The binary is at <skill-dir>/../telegram-skills-bin/bin/telegram.

Requires the telegram-skills-bin skill. The binary lives in that sibling skill. If <skill-dir>/../telegram-skills-bin/bin/telegram does not exist, tell the user to install it (bunx skills add roziscoding/telegram-skills) instead of failing with a raw error.

Add or update a contact

Adding a contact needs a chat ID. Users rarely know their own, so the default procedure is to capture it with --get-id. Only skip this and go straight to --contact-add <name> <id> if the user gives you the chat ID up front.

Standard flow: capture the chat ID with --get-id

--get-id prints a one-time connect link and waits for the person to start the bot, then prints their name and chat ID. Nothing is written to credentials — it only reports the ID, which you then pass to --contact-add.

This command prints the link and then blocks waiting for the user, so run it in the BACKGROUND — exactly like telegram-setup — to read the link and relay it before the user acts.

# token already in credentials.json:
<skill-dir>/../telegram-skills-bin/bin/telegram --get-id

# or pass a token explicitly:
<skill-dir>/../telegram-skills-bin/bin/telegram --get-id "<TOKEN>"

It emits immediately (on stderr):

GETID_URL=https://t.me/<bot>?start=<code>
GETID_CODE=<code>
GETID_BOT=@<bot>

Tell the user to either open GETID_URL and press Start, or open the bot (GETID_BOT) in Telegram and send /start <code>. When they do, the process prints their name and ID and exits 0:

GETID_OK chat_id=<id> first_name=<first> last_name=<last>

Then add them as a contact with the captured ID:

<skill-dir>/../telegram-skills-bin/bin/telegram --contact-add <name> <id>

If it times out (5 min) or exits non-zero, tell the user and offer to retry.

Shortcut: when the user already knows the chat ID

<skill-dir>/../telegram-skills-bin/bin/telegram --contact-add alice 123456789

This is an upsert — if the contact already exists, its chat ID is updated.

List contacts

<skill-dir>/../telegram-skills-bin/bin/telegram --list-contacts

Outputs tab-separated name\tchat_id lines, one per contact.

Delete a contact

<skill-dir>/../telegram-skills-bin/bin/telegram --delete-contact alice

Notes

• Contact names are case-insensitive (stored lowercase)
• Changes are written directly to ~/.config/telegram-skills/credentials.json
• The credentials file is created automatically if it doesn't exist yet