telechatai 1.0.0

Claude AI on your phone/desktop — personal, self-hosted messenger bot for Telegram, WhatsApp, and Slack

Telechat

Claude AI on your phone / desktop — personal, self-hosted, zero-infrastructure.
Supports WhatsApp, Telegram, and Slack simultaneously from a single process.

A bot that connects to Claude AI via two modes:

• CLI mode — Uses the Claude Code CLI (claude). No API key needed if you have a Claude subscription.
• API mode — Uses the Anthropic API directly. Requires an API key. Works in Docker.

Install

# npm (auto-installs Python deps on first run)
npm install -g telechat
telechat

# pip
pip install telechat
telechat

Quick Start (from source)

# Clone
git clone https://github.com/telechatai/telechat.git
cd telechat

# Install
./scripts/install.sh

# Edit .env with your tokens
nano .env

# Run
./scripts/start.sh

Platform comparison

	Telegram	WhatsApp	Slack
Bridge	Telegram Bot API	Green API free tier	Slack Bolt + Socket Mode
Setup	Talk to @BotFather	Scan a QR code	Create a Slack app
Photo / file support	Yes	Text only	Text only
Interactive UI	Inline buttons	No	Reactions as status indicator
Works without public URL	Yes (polling)	Yes (polling)	Yes (WebSocket)
Works on corporate Wi-Fi	Depends	Yes	Yes

---

Setup

1 — Choose your platform(s)

Set BOT_MODE in .env — accepts a comma-separated list or a shorthand:

Value	What starts
telegram	Telegram only (default)
whatsapp	WhatsApp only
slack	Slack only
telegram,slack	Telegram + Slack
telegram,whatsapp	Telegram + WhatsApp
both	Telegram + WhatsApp (legacy alias)
all	All three platforms

---

2a — Telegram setup

1. Open Telegram and search for @BotFather (verified blue checkmark).
2. Send /newbot and follow the prompts.
3. Copy the token → set TELEGRAM_BOT_TOKEN in .env.

Optional: customize your bot

BotFather command	What it does
/setdescription	Text users see before starting the bot
/setabouttext	Bio shown on the bot's profile
/setuserpic	Profile picture
/setcommands	Register autocomplete hints

Register command hints:

start - Welcome message
reset - Clear conversation history
mode - Show current mode and model
id - Show your Telegram user ID

Finding your user ID (for ALLOWED_USER_IDS)

1. Start your bot and send /id
2. Copy the numeric ID → paste into ALLOWED_USER_IDS in .env

---

2b — Slack setup (Socket Mode — no public URL needed)

Corporate / enterprise workspace? Most company Slack workspaces (e.g. Intuit) block individual users from installing new apps. If you hit "An error occurred while creating your request", create a free personal workspace at slack.com/get-started and install the bot there instead. You're the admin — no approval needed. Invite your teammates to the personal workspace to share the bot.

Step-by-step

1. Go to https://api.slack.com/apps → Create New App → From scratch
   (pick your personal workspace, not a corporate one)

2. Settings → Socket Mode → Enable
   → Create an App-Level Token → name it anything → scope: connections:write
   → copy the xapp-1-... token — this is SLACK_APP_TOKEN

3. OAuth & Permissions → Bot Token Scopes → add all of these:

   Scope	Purpose
   chat:write	Send messages
   channels:history	Read public channel messages
   groups:history	Read private channel messages
   im:history	Read DMs
   im:write	Open DM conversations
   app_mentions:read	Detect @mentions
   reactions:write	Show ⏳ while Claude thinks

4. Event Subscriptions → Enable → Subscribe to bot events:
   message.im, message.channels, message.groups, app_mention
   → Save Changes

5. OAuth & Permissions → Install to Workspace → Allow
   → copy the xoxb-... Bot Token — this is SLACK_BOT_TOKEN

6. In your Slack workspace, invite the bot to any channel: /invite @yourbot

.env for Slack

BOT_MODE=slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-1-...

# Your Slack member ID to restrict access (leave empty to allow everyone)
# Find it: click your name → View profile → ⋯ → Copy member ID
SLACK_ALLOWED_USER_IDS=U01234567

How it works

Trigger	How to use
Direct message	Just message the bot
Channel	@yourbot <question>
Thread	Reply mentioning the bot to keep conversation in-thread

A ⏳ reaction appears on your message while Claude is thinking, removed when done.

---

2c — WhatsApp setup (Green API — free, no Meta account needed)

1. Sign up at https://console.green-api.com
2. Click Create instance → choose Developer plan (free — 1 500 msg/month)
3. In the instance dashboard → Scan QR → scan with your WhatsApp phone
4. Copy Instance ID and API Token → paste into .env:

BOT_MODE=whatsapp
GREEN_API_INSTANCE_ID=1234567890
GREEN_API_TOKEN=your_token_here
WHATSAPP_ALLOWED_NUMBERS=919876543210   # your number without the +

Corporate network note: Green API works over standard HTTPS polling — no webhook or public URL needed. If Telegram is blocked on your network, use BOT_MODE=whatsapp instead.

---

3 — Configure Claude

All Claude settings apply to both platforms:

Variable	Default	Description
CLAUDE_MODE	cli	cli or api
ANTHROPIC_API_KEY	—	Required for API mode
CLAUDE_MODEL	claude-sonnet-4-20250514	API mode model
SYSTEM_PROMPT	(generic)	Your personal instructions to Claude
CLAUDE_CLI_WORK_DIR	~	Working directory for CLI
CLAUDE_CLI_ADD_DIRS	—	Comma-separated extra dirs Claude can access
CLAUDE_CLI_PERMISSION_MODE	—	acceptEdits / auto / bypassPermissions
CLAUDE_CLI_MODEL	sonnet	CLI model: haiku / sonnet / opus
CLAUDE_TIMEOUT	180	Seconds to wait for Claude
RATE_LIMIT_REQUESTS	20	Max messages per window
RATE_LIMIT_WINDOW	60	Rate limit window (seconds)

CLI mode — requires Claude Code CLI installed and authenticated:

# Install Claude Code CLI: https://docs.anthropic.com/en/docs/claude-code
claude auth login

API mode:

CLAUDE_MODE=api
ANTHROPIC_API_KEY=sk-ant-...

---

Running

Foreground

./scripts/start.sh

As a system service (macOS launchd / Linux systemd)

./scripts/service.sh install    # Install and start
./scripts/service.sh status     # Check status
./scripts/service.sh logs       # Tail logs
./scripts/service.sh restart    # Restart
./scripts/service.sh stop       # Stop
./scripts/service.sh uninstall  # Remove service

Docker (API mode only)

# Set CLAUDE_MODE=api in .env
docker compose up -d
docker logs -f telechat

---

Telegram commands

Command	Description
/start	Welcome message
/reset	Clear conversation history
/mode	Show current mode and model
/model	Switch model (haiku / sonnet / opus)
/verbose	Set output verbosity: 0 quiet · 1 normal · 2 detailed
/permissions	Change CLI permission mode
/usage	Show usage statistics
/id	Show your Telegram user ID

---

WhatsApp usage

Just send a message. There are no slash commands — WhatsApp is intentionally kept simple.

---

Project structure

├── main.py            Entry point — reads BOT_MODE, starts adapters
├── claude_core.py     Shared: Claude CLI/API, SQLite history, rate limiting
├── telegram_bot.py    Telegram adapter
├── whatsapp_bot.py    WhatsApp adapter (Green API polling)
├── slack_bot.py       Slack adapter (Socket Mode)
├── bot.py             Backward-compat shim (runs Telegram, same as before)
├── scripts/
│   ├── install.sh
│   ├── start.sh
│   └── service.sh
├── Dockerfile         (API mode only)
├── docker-compose.yml
├── requirements.txt
└── .env.example

---

Features

• Three platforms — Telegram, WhatsApp, and Slack from one process (BOT_MODE=all)
• Dual Claude mode — CLI (free with Claude subscription) or API
• Typing indicator — shows "typing…" while Claude processes
• Image & file analysis — Telegram only (photos + documents)
• Model switching — haiku / sonnet / opus from Telegram inline buttons
• Verbose mode — see what tools Claude is using
• Rate limiting — configurable per-user throttling
• Persistent history — SQLite, keyed per platform+user; survives restarts
• Usage tracking — per-user message and token statistics
• Markdown rendering — formatted responses with plain-text fallback

---

Per-developer sharing

Each developer runs their own instance on their own machine:

1. Clone this repo
2. ./scripts/install.sh
3. Set their own credentials + SYSTEM_PROMPT in .env
4. ./scripts/start.sh

No shared server. No shared credentials. Fully private.

---

Security

• Set ALLOWED_USER_IDS (Telegram) or WHATSAPP_ALLOWED_NUMBERS to restrict who can use your bot
• Never commit .env — it is in .gitignore
• In CLI mode the bot inherits your Claude auth — don't run on untrusted machines

---

Troubleshooting

Symptom	Fix
WhatsApp: no replies	Check instance status in Green API console — must be authorized
Slack: "error creating request" on install	Corporate workspace blocks app installs — create a free personal workspace at slack.com/get-started instead
Slack: bot doesn't respond	Check Socket Mode is enabled; App-Level Token must have connections:write scope
Slack: works in channels but not DMs	Add im:history + im:write scopes and reinstall the app to workspace
Slack: missing messages after reinstall	Re-subscribe to events (message.im, message.channels, etc.) under Event Subscriptions
Telegram: SSL/handshake error	Telegram may be blocked on your network; use BOT_MODE=slack or BOT_MODE=whatsapp
claude: command not found	Install Claude Code CLI and ensure it's in PATH
Response cut off	Bot auto-chunks at 4 000 chars per message — expected
Bot stops after reboot	Use ./scripts/service.sh install for a proper system service

---

License

MIT