301 lines
8.5 KiB
Markdown
301 lines
8.5 KiB
Markdown
# Messenger TUI
|
|
|
|
Terminal-based Matrix client for accessing Facebook Messenger via self-hosted bridge.
|
|
|
|
## Overview
|
|
|
|
This project connects to a self-hosted Matrix homeserver (`matrix.kokoham.com`) with a mautrix-facebook bridge, providing a lightweight TUI for messaging on Messenger without the heavy desktop/mobile apps.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────┐
|
|
│ sleepy-mini │
|
|
│ │
|
|
│ ┌─────────────────┐ ┌─────────────────────────────┐ │
|
|
│ │ Matrix Homeserver │ │ mautrix-facebook bridge │ │
|
|
│ │ (Conduit) │◄──►│ │ │
|
|
│ │ matrix.kokoham.com │ └──────────────┬────────────┘ │
|
|
│ └─────────┬───────────┘ │ │
|
|
│ │ │ │
|
|
│ │ Facebook/Meta │ │
|
|
│ │ Messenger │ │
|
|
│ │ ◄──── │ │
|
|
│ │ │ │
|
|
└─────────────┼───────────────────────────────┼─────────────────────────┘
|
|
│ │
|
|
▼ ▼
|
|
┌────────────────────────────────┐ ┌──────────────────────────────┐
|
|
│ WeeChat TUI (Laptop) │ │ YouTube (Phone) │
|
|
│ │ └──────────────────────────────┘
|
|
└────────────────────────────────┘
|
|
```
|
|
|
|
## Server Info
|
|
|
|
- **Homeserver**: `https://matrix.kokoham.com`
|
|
- **Server Location**: `sleepy-mini:~/Documents/personal/projects/messenger_homeserver`
|
|
|
|
## Features
|
|
|
|
- [x] Text messaging
|
|
- [ ] Group chats
|
|
- [ ] Image/media receive
|
|
- [ ] Image/media send
|
|
- [ ] Notifications
|
|
- [ ] Search
|
|
|
|
## Prerequisites
|
|
|
|
- WeeChat with Matrix plugin
|
|
- Matrix account on `matrix.kokoham.com`
|
|
- Server-side: Conduit + mautrix-facebook bridge (see [Messenger-Homeserver](../Messenger-Homeserver/))
|
|
|
|
## Setup
|
|
|
|
### 1. Install WeeChat
|
|
|
|
```bash
|
|
# macOS
|
|
brew install weechat
|
|
|
|
# Linux (Debian/Ubuntu)
|
|
sudo apt install weechat
|
|
|
|
# Linux (Arch)
|
|
sudo pacman -S weechat
|
|
```
|
|
|
|
### 2. First-Time WeeChat Setup
|
|
|
|
Run WeeChat for the first time:
|
|
```bash
|
|
weechat
|
|
```
|
|
|
|
Set your username:
|
|
```
|
|
/set weechat look.nick "your_nick"
|
|
```
|
|
|
|
### 3. Load Matrix Plugin
|
|
|
|
WeeChat 4.0+ has built-in Matrix support. Load it:
|
|
```
|
|
/plugin load matrix
|
|
```
|
|
|
|
### 4. Configure Server Connection
|
|
|
|
```bash
|
|
# Add the server
|
|
/server add kokoham https://matrix.kokoham.com:443
|
|
|
|
# Enable TLS
|
|
/set plugins.var.dev矩阵.server.kokoham.ssl_verify on
|
|
|
|
# Disable certificate verification for self-signed (if needed)
|
|
# /set plugins.var.dev矩阵.server.kokoham.ssl_verify off
|
|
|
|
# Auto-connect on startup
|
|
/set plugins.var.dev矩阵.server.kokoham.autoconnect on
|
|
```
|
|
|
|
### 5. Register/Login
|
|
|
|
**If this is a new account:**
|
|
```
|
|
/connect kokoham
|
|
/msg #register:matrix.kokoham.com your_password
|
|
```
|
|
|
|
**If you already have an account:**
|
|
```
|
|
/connect kokoham
|
|
/matrix login your_username your_password
|
|
```
|
|
|
|
### 6. Save Configuration
|
|
|
|
```
|
|
/save
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Essential WeeChat Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/buffer list` | List all joined rooms/chats |
|
|
| `/join #room:matrix.kokoham.com` | Join a room |
|
|
| `/query username` | Open private chat |
|
|
| `/window swap` | Swap windows |
|
|
| `Alt+Left/Right` or `Ctrl+P/Ctrl+N` | Switch buffers |
|
|
| `Ctrl+W then n` | Close current buffer |
|
|
| `/close` | Close current chat |
|
|
| `/set` | View/set options |
|
|
| `/help matrix` | Matrix-specific help |
|
|
| `/help` | General WeeChat help |
|
|
| `/quit` | Exit WeeChat |
|
|
|
|
### Matrix-Specific Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/matrix info` | Show room/user info |
|
|
| `/matrix devices` | Manage encryption devices |
|
|
| `/matrix keys` | Manage encryption keys |
|
|
| `/matrix room invite @user:domain` | Invite user to room |
|
|
|
|
### Typing and Sending
|
|
|
|
- Just type and press Enter to send
|
|
- `Ctrl+Q` to quote special characters
|
|
- `Ctrl+U` to clear line
|
|
|
|
### Navigation
|
|
|
|
- `Ctrl+X` to switch between rooms with same name
|
|
- `/bar scroll` to scroll buffers
|
|
|
|
## Configuration
|
|
|
|
### Recommended Settings
|
|
|
|
Copy `config/weechat.conf` snippets to your WeeChat:
|
|
|
|
```weechat
|
|
# Autojoin channels/rooms on connect
|
|
/set plugins.var.dev矩阵.server.kokoham.autojoin_commands "/join *"
|
|
|
|
/set plugins.var.dev矩阵.notify.enabled on
|
|
/set plugins.var.dev矩阵.notify.message on
|
|
/set plugins.var.dev矩阵.notify.self on
|
|
|
|
# Show join/part messages (optional)
|
|
/set weechat.look.buffer_notify_default all
|
|
|
|
# Auto-open DMs when received
|
|
/set plugins.var.dev矩阵.server.kokoham.automaticrooms room
|
|
|
|
# Notification commands (requires relay or external script)
|
|
# /set plugins.var.dev矩阵.notify.command "/exec -nocommand echo 'New message from $1'"
|
|
```
|
|
|
|
### Color Scheme (Optional)
|
|
|
|
```weechat
|
|
/color reset
|
|
/set weechat.color.chat_time_delimiters lightgreen
|
|
/set weechat.color.chat_highlight lightmagenta
|
|
```
|
|
|
|
## Scripts & Tools
|
|
|
|
### Quick Connect Script
|
|
|
|
Run after WeeChat is installed:
|
|
```bash
|
|
cd ~/Documents/personal/projects/messenger_tui
|
|
./scripts/quick_connect.sh
|
|
```
|
|
|
|
### Notification Relay (Optional)
|
|
|
|
For desktop notifications, use `weechat-matrix-notify-relay` or configure a notification command:
|
|
|
|
```bash
|
|
# macOS notification example
|
|
/set plugins.var.dev矩阵.notify.command "/exec -nocommand osascript -e 'display notification \"${message}\" with title \"WeeChat: ${nick}\"'"
|
|
```
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
messenger_tui/
|
|
├── README.md # This file
|
|
├── .gitignore
|
|
├── SETUP.md # Detailed setup guide (this file)
|
|
├── config/
|
|
│ └── weechat.conf # Config snippets to copy
|
|
└── scripts/
|
|
├── setup_weechat.sh # Initial setup script
|
|
└── quick_connect.sh # Connect to kokoham server
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Connection Issues
|
|
|
|
**"Unable to connect" error:**
|
|
```bash
|
|
# Check if server is reachable
|
|
curl https://matrix.kokoham.com/_matrix/client/versions
|
|
|
|
# Try without SSL verification (for self-signed certs)
|
|
/set plugins.var.dev矩阵.server.kokoham.ssl_verify off
|
|
/disconnect kokoham
|
|
/connect kokoham
|
|
```
|
|
|
|
**TLS certificate errors:**
|
|
```bash
|
|
# On macOS, install certs if needed
|
|
/usr/local/bin/cert-sync /etc/ssl/cert.pem # with certsync
|
|
# or
|
|
brew install ca-certificates
|
|
```
|
|
|
|
### Login Issues
|
|
|
|
**Invalid username/password:**
|
|
- Make sure you've registered or that the admin has created your account
|
|
- Check password doesn't contain special characters (escape them)
|
|
|
|
**"Authentication failed":**
|
|
```bash
|
|
# Clear saved credentials
|
|
/unset plugins.var.dev矩阵.server.kokoham.password
|
|
/matrix login your_username your_password
|
|
```
|
|
|
|
### Performance Issues
|
|
|
|
**Slow or laggy:**
|
|
```bash
|
|
# Reduce sync interval
|
|
/set plugins.var.dev矩阵.server.kokoham.poll_timeout 5000
|
|
|
|
# Disable typing notifications
|
|
/set plugins.var.dev矩阵.typing_timeout 0
|
|
```
|
|
|
|
### Encryption (E2EE)
|
|
|
|
WeeChat Matrix supports end-to-end encryption:
|
|
|
|
```bash
|
|
# First time setup
|
|
/matrix keys device_id
|
|
# This generates your encryption keys
|
|
|
|
# Verify a device
|
|
/matrix devices verify DEVICE_ID
|
|
```
|
|
|
|
## Known Limitations
|
|
|
|
- Voice/video calls: Not supported via bridge
|
|
- Read receipts: Partial support
|
|
- Some rich media features may not work
|
|
- Encryption setup requires manual key management
|
|
|
|
## See Also
|
|
|
|
- [WeeChat Quick Start](https://weechat.org/doc/quickstart/)
|
|
- [WeeChat Matrix Plugin Docs](https://weechat.org/plugins/source/devel-matrix/)
|
|
- [mautrix-facebook](https://docs.mau.fi/bridges/python/facebook/index.html)
|
|
- [Conduit Matrix Server](https://conduit.rs/)
|
|
- [Matrix.org](https://matrix.org/)
|