# Neuron Telegram Gateway — Setup

The Telegram gateway lets you chat with your Neuron soul via Telegram. Plain messages go to the soul; commands give access to memory and status.

## 1. Create a bot via @BotFather

1. Open Telegram and search for **@BotFather**
2. Send `/newbot`
3. Pick a name (e.g. "Neuron")
4. Pick a username (must end in `bot`, e.g. `myneuron_bot`)
5. BotFather replies with your **HTTP API token** — looks like `7123456789:ABCdef...`
6. Optionally set a description: `/setdescription` → select your bot → type a description

## 2. Store the token in the macOS Keychain

Never put the token in a plist, `.env`, or any file that might be committed.

```bash
security add-generic-password \
  -s neuron-telegram-bot \
  -a neuron \
  -w '<paste token here>'
```

Verify:
```bash
security find-generic-password -s neuron-telegram-bot -a neuron -w
```

## 3. Load the LaunchAgent

```bash
launchctl load ~/Library/LaunchAgents/ai.neuron.telegram-gateway.plist
```

Check it started:
```bash
launchctl list | grep telegram
tail -f ~/.neuron/logs/telegram-gateway.out.log
```

## 4. Test

Send your bot a message in Telegram. It should reply using your soul's voice.

## Commands

| Command | What it does |
|---------|-------------|
| `<any text>` | Forwarded to the soul → responds in its voice |
| `/memory <query>` | Searches soul memories, returns top 3 |
| `/remember <text>` | Stores text as a memory node |
| `/status` | Reports whether the soul is reachable |

## Unload / stop

```bash
launchctl unload ~/Library/LaunchAgents/ai.neuron.telegram-gateway.plist
```

## Troubleshoot

- **"token not found"** — re-run step 2 above
- **"Soul is resting"** — the soul daemon at `http://localhost:7770` is not running; start it with `launchctl load ~/Library/LaunchAgents/ai.neuron.engram.plist` (or whichever plist runs the soul)
- **Logs**: `~/.neuron/logs/telegram-gateway.out.log` and `telegram-gateway.err.log`
- **Test gateway script directly**:
  ```bash
  TELEGRAM_BOT_TOKEN=<token> ~/Development/neuron-technologies/neuron/tools/telegram-gateway.sh
  ```

## Soul API endpoints used

| Endpoint | Purpose |
|----------|---------|
| `POST /api/chat` | Forward messages to the soul |
| `POST /api/neuron/recall` | Search memories |
| `POST /api/neuron/memory` | Store conversation as a memory node |