# Channel Setup Guide

This guide covers step-by-step setup for each communication channel supported by Familiar.

---

## Telegram (Recommended)

1. Open Telegram and search for **@BotFather**
2. Send `/newbot`
3. Choose a name (e.g. "My Familiar")
4. Choose a username (e.g. `my_familiar_bot`)
5. Copy the bot token (format: `123456789:ABCdefGhIjKlMnOpQrStUvWxYz`)
6. Set `TELEGRAM_BOT_TOKEN` in your `.env` file or enter it during onboarding
7. Send `/start` to your bot to claim ownership

**Tip:** Enable inline mode in BotFather (`/setinline`) for richer interactions.

---

## Discord

1. Go to [discord.com/developers/applications](https://discord.com/developers/applications)
2. Click **New Application** → name it → **Create**
3. Go to **Bot** → **Add Bot**
4. Enable **Message Content Intent** under Privileged Gateway Intents
5. Copy the bot token
6. Go to **OAuth2** → **URL Generator**:
   - Scopes: `bot`
   - Permissions: Send Messages, Read Message History, Embed Links
7. Open the generated URL to invite the bot to your server
8. Set `DISCORD_BOT_TOKEN` in your `.env` file or enter it during onboarding

---

## Matrix / Element

1. Create a bot account on your homeserver (e.g. via Element → Register)
2. Choose authentication method:
   - **Password auth:** Set `MATRIX_USER` and `MATRIX_PASSWORD`
   - **Access token:** Go to Settings → Security → Access Token, set `MATRIX_ACCESS_TOKEN`
3. Set `MATRIX_HOMESERVER` to your homeserver URL (e.g. `https://matrix.org`)
4. Invite the bot to a room
5. (Optional) Set `OWNER_MATRIX_ID` to your Matrix ID for owner-level access

**E2EE support:** Install `familiar-agent[matrix]` for end-to-end encryption.

---

## WhatsApp

WhatsApp integration uses a Node.js bridge via whatsapp-web.js.

### Prerequisites

- Node.js v18+ — install from [nodejs.org](https://nodejs.org/)
- npm packages: `npm install whatsapp-web.js qrcode-terminal ws`

### Setup

1. During onboarding, set the bridge port (default: `3001`)
2. Accept the offer to create `whatsapp_bridge.js` in `~/.familiar/`
3. Start the bridge: `node ~/.familiar/whatsapp_bridge.js`
4. Scan the QR code with WhatsApp on your phone to pair
5. The bridge maintains a session after the first pairing

**Environment variables:**
- `WHATSAPP_BRIDGE_PORT` — WebSocket port for the bridge (default: `3001`)

---

## Signal

Signal integration uses [signal-cli](https://github.com/AsamK/signal-cli).

### Install signal-cli

- **macOS:** `brew install signal-cli`
- **Linux (apt):** `apt install signal-cli`
- **Manual:** Download from [GitHub releases](https://github.com/AsamK/signal-cli/releases)

### Setup

1. Register or link a phone number:
   ```bash
   signal-cli -u +14155551234 register
   # or link to existing account:
   signal-cli link -n "Familiar"
   ```
2. Set `SIGNAL_PHONE` to your number with country code (e.g. `+14155551234`)
3. (Optional) Set `SIGNAL_ALLOWED_CONTACTS` to restrict who can message the bot

---

## iMessage (macOS only)

iMessage integration uses AppleScript to interact with Messages.app.

### Requirements

- macOS with Messages.app signed in to an Apple ID
- Familiar must run on the same Mac

### Setup

1. Select iMessage during onboarding — no additional credentials needed
2. Ensure Messages.app is running and signed in
3. Grant Familiar accessibility permissions if prompted

**Note:** iMessage is only available on macOS (`sys.platform == "darwin"`).

---

## Microsoft Teams

Teams integration uses Azure Bot Services.

### Setup

1. Go to [portal.azure.com](https://portal.azure.com)
2. Create a new **Azure Bot** resource
3. Under **Configuration**:
   - Copy the **Microsoft App ID**
   - Click **Manage Password** → generate a new client secret
4. Under **Channels** → connect **Microsoft Teams**
5. Set environment variables:
   - `TEAMS_APP_ID` — the Microsoft App ID
   - `TEAMS_APP_PASSWORD` — the client secret
   - `TEAMS_TENANT_ID` (optional) — for single-tenant deployments

### Testing

After setup, search for your bot in Teams and send a message.

---

## Terminal / CLI

No setup required. This is the default fallback channel.

```bash
python -m familiar
```

Type messages directly in the terminal. Useful for testing and local-only use.

---

## Multi-Channel

Familiar supports running multiple channels simultaneously. The first channel is the "primary" (used for proactive briefings). Additional channels run in background threads.

```bash
# Via environment variable
export ENABLED_CHANNELS=telegram,discord,cli
python -m familiar

# Via CLI flags
python -m familiar --telegram --discord
```

Configure all channels during onboarding by selecting multiple options, or re-run with `--reconfigure` to change later.

---

## Owner PIN Claim Flow

During onboarding, you set a 4-8 digit owner PIN. This PIN verifies you are the owner when you first interact with the bot.

### How it works

1. The onboarding wizard generates (or you choose) a PIN
2. The PIN is hashed with PBKDF2-HMAC-SHA256 and stored as `OWNER_PIN_HASH` in `.env`
3. When you first message the bot (e.g. send `/start` on Telegram), the bot asks for your PIN
4. Enter the PIN as your first message to claim ownership
5. Once claimed, the bot remembers your user ID and grants owner-level access

**Important:** The raw PIN is never stored. Only the salted hash is persisted.

---

## Encryption Setup

Familiar can encrypt all data at rest (conversations, contacts, tasks, analytics).

### Configuration

- **`ENCRYPTION_ENABLED`** — set to `true` in `.env` to enable
- **`ENCRYPTION_PASSPHRASE`** — the passphrase used to derive the encryption key

### What gets encrypted

- SQLite databases (analytics, training data)
- Conversation history
- Contact information and user preferences
- Task and calendar data

### How it works

- Data is encrypted using the passphrase-derived key when written to disk
- Data is decrypted only in memory while Familiar is running
- If you lose the passphrase, the data is **unrecoverable**

You can enable encryption during onboarding or later by telling your bot "encrypt all my data stores".

---

## Lightweight Model

When using Ollama, Familiar can run a second smaller model for background tasks (planning, memory extraction, summarization). This keeps the main model free for conversations.

### RAM-based recommendations

| RAM | Bundle | Main Model | Background Model | Total Size |
|-----|--------|-----------|-----------------|------------|
| < 4 GB | Pi | qwen2.5:0.5b | — | ~540 MB |
| 4-8 GB | Standard | llama3.2 | qwen2.5:0.5b | ~2.9 GB |
| 8+ GB | Full | qwen2.5:7b | qwen2.5:0.5b | ~5.5 GB |

### Environment variables

- **`FAMILIAR_LIGHTWEIGHT_MODEL`** — the model used for background tasks (e.g. `qwen2.5:0.5b`)
- The main model is set via `llm.ollama_model` in `config.yaml`

---

## Briefing Dependencies

The morning briefing pulls data from multiple sources. For full functionality:

- **Google Calendar** — `python -m familiar --setup-google` to authorize
- **Gmail** — authorized via the same Google OAuth flow
- **Tasks** — built-in task system, no extra setup needed

### Without Google Calendar/Gmail

The briefing still works but only includes:
- Pending tasks and reminders
- System status
- Any other configured integrations

Run `python -m familiar --setup-google` to connect Google services.

---

## Test Messages

After onboarding, Familiar sends a test message to verify the connection works.

### Per-channel behavior

| Channel | Test Message Behavior |
|---------|----------------------|
| Telegram | Waits for you to send `/start`, then replies with greeting |
| Discord | Sends greeting to the first text channel in the first server |
| Matrix | Sends greeting to the first joined room |
| WhatsApp | Deferred — greeting sent when the bridge starts |
| Signal | Deferred — greeting sent when signal-cli connects |
| iMessage | Deferred — greeting sent on first launch |
| Teams | Deferred — greeting sent when bot resource connects |
| CLI | Greeting printed directly in terminal |

---

## Reconfigure Workflow

To change your setup after initial onboarding:

```bash
python -m familiar --reconfigure
```

### PIN gate

If you have an owner PIN set, `--reconfigure` requires you to enter it before proceeding. This prevents unauthorized changes to your configuration.

### What gets cleaned up

When you change channels during reconfiguration, secrets for deselected channels are removed from `.env`:

- Deselecting Telegram removes `TELEGRAM_BOT_TOKEN`, `OWNER_TELEGRAM_ID`
- Deselecting Discord removes `DISCORD_BOT_TOKEN`
- Deselecting Matrix removes `MATRIX_HOMESERVER`, `MATRIX_USER`, `MATRIX_PASSWORD`, `MATRIX_ACCESS_TOKEN`, `OWNER_MATRIX_ID`
- Deselecting Signal removes `SIGNAL_PHONE`
- Deselecting Teams removes `TEAMS_APP_ID`, `TEAMS_APP_PASSWORD`, `TEAMS_TENANT_ID`

Disabling encryption removes `ENCRYPTION_ENABLED` and `ENCRYPTION_PASSPHRASE`.

The legacy `LLM_DEFAULT_PROVIDER` variable is always cleaned up in favor of `DEFAULT_PROVIDER`.
