WAHA TUI

WhatsApp in your terminal.

⚠️ Beta - This project is under active development. Some features may be incomplete or change between releases.

A beautiful Terminal User Interface for WhatsApp using WAHA (WhatsApp HTTP API). Manage your WhatsApp sessions, chats, and messages directly from your terminal with an intuitive TUI powered by OpenTUI.

Features

• 📱 Session Management - Create, view, and manage WAHA sessions with QR code or phone number pairing
• 💬 Chat Interface - Browse chats with WhatsApp-style layout and real-time updates
• ✉️ Messaging - Send and receive messages with read receipts, (edited) indicators, and auto-history loading
• 📊 Interactive Polls - View and vote in polls with real-time result progress bars (█░)
• 🔗 Link Previews - Rich metadata rendering for URLs (title, description, domain) directly in the chat
• 🔍 Search & Filters - Filter chats by all, unread, favorites, groups, or labeled with instant global and in-chat search
• 📋 Context Menus - Right-click style menus for chats (archive, delete, mark unread, pin, mute) and messages (star, pin, react, forward, delete)
• ⚙️ Settings - Configurable notification preferences, enter-to-send, and background sync
• 🔔 Desktop Notifications - Native OS notifications for messages and calls with per-category controls
• ⏱️ Disappearing Messages - Visibility indicators for chats with disappearing mode enabled
• 🔄 Real-Time Updates - WebSocket-powered live updates for messages, reactions, polls, labels, and typing indicators
• 🆕 Update Checker - Automatic notification when a new version is available

Screenshots

Quick Start

Run directly with bunx (no installation required)

bunx @muhammedaksam/waha-tui

Or install globally

bun add -g @muhammedaksam/waha-tui
waha-tui

Or clone and run locally

git clone https://github.com/muhammedaksam/waha-tui.git
cd waha-tui
bun install
bun dev

Prerequisites

• Bun >= 1.0
• A running WAHA server

WEBJS Engine Configuration

If you're using the WEBJS engine (default for WAHA CORE), you must enable tagsEventsOn in your session config to receive typing indicators (presence.update) and message ack events:

{
  "name": "default",
  "config": {
    "webjs": {
      "tagsEventsOn": true
    }
  }
}

Note: This setting is required for real-time typing indicators to work. See WAHA documentation for more details.

Configuration

On first run, WAHA TUI will prompt you for configuration with a beautiful setup wizard.

Configuration is stored in $XDG_CONFIG_HOME/waha-tui/ (defaults to ~/.config/waha-tui/) with secrets separated from metadata:

$XDG_CONFIG_HOME/waha-tui/.env (Secrets)

# WAHA TUI Configuration
# Connection settings for WAHA server

WAHA_URL=http://localhost:3000
WAHA_API_KEY=your-api-key-here

$XDG_CONFIG_HOME/waha-tui/config.json (Metadata & Settings)

{
  "version": "1.6.1",
  "createdAt": "2024-12-19T00:00:00.000Z",
  "updatedAt": "2024-12-19T00:00:00.000Z",
  "settings": {
    "enterIsSend": true,
    "messageNotifications": {
      "showNotifications": true,
      "showReactionNotifications": false,
      "playSound": true
    },
    "groupNotifications": {
      "showNotifications": true,
      "showReactionNotifications": false,
      "playSound": true
    },
    "statusNotifications": {
      "showNotifications": false,
      "showReactionNotifications": false,
      "playSound": false
    },
    "showPreviews": true,
    "backgroundSync": true
  }
}

Development: Project .env

For development, you can also create a .env in the project root which takes precedence:

WAHA_URL=http://localhost:3000
WAHA_API_KEY=your-api-key-here

Usage

Keyboard Shortcuts

Global

| Key | Action | | -------- | ------------------- | | 1 | Go to Sessions view | | 2 | Go to Chats view | | Ctrl+C | Exit immediately |

QR / Phone Pairing

| Key | Action | | ----------- | ---------------------------- | | p | Switch to phone pairing mode | | q | Switch to QR mode / Go back | | 0-9 | Enter phone number digits | | Backspace | Delete last digit | | Enter | Submit phone number | | Esc | Cancel phone pairing |

Sessions

| Key | Action | | ---------- | -------------------------------- | | ↑/↓ | Navigate session list | | Enter | Select session | | Home/End | Jump to first / last session | | n | Create new session | | r | Refresh sessions | | q | Logout & delete selected session |

⚠️ The q key in Sessions view performs a destructive action: it logs out and deletes the current session.

Chats

| Key | Action | | ---------------- | --------------------------------------------------- | | ↑/↓ | Navigate chat list | | Enter | Open selected chat | | Home/End | Jump to first / last chat | | PageUp/Left | Page up (12 items) | | PageDown/Right | Page down (12 items) | | Tab/Shift+Tab | Cycle filters (all/unread/favorites/groups/labeled) | | / or Ctrl+F | Focus search input | | n | Start new chat | | c | Open chat context menu | | s | Open settings | | r | Refresh chats | | Ctrl+A | Toggle archived chats view | | Esc | Clear search / Exit archived / Go back |

Conversation

| Key | Action | | ---------------- | ----------------------------------- | | i | Enter message input mode | | ↑/↓ | Scroll messages | | PageUp/Left | Scroll up (large jump) | | PageDown/Right | Scroll down (large jump) | | o | Open/download last media message | | p | Create poll | | a | Attach media | | e | React with emoji to last message | | m | Open message context menu | | / or Ctrl+F | Open in-chat search | | Esc | Exit input mode / Clear search | | Enter | Next search result (when searching) | | Shift+Enter | Prev search result (when searching) |

Settings

| Key | Action | | -------------- | ------------------------------ | | ↑/↓ or j/k | Navigate menu items | | Enter/Space | Toggle setting / Open sub-menu | | Esc | Go back |

Debug Logging

Enable debug logging to troubleshoot issues:

# Via environment variable
WAHA_TUI_DEBUG=1 bun dev

# Via command-line flag
bun dev --debug

Debug logs are saved to $XDG_CONFIG_HOME/waha-tui/debug.log with automatic sanitization of sensitive data.

Development

See DEVELOPMENT.md for development setup, commands, and project structure.

Technologies

• Runtime: Bun
• UI Framework: OpenTUI
• WAHA SDK: @muhammedaksam/waha-node
• TypeScript: Type-safe development

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Security

See SECURITY.md for security policy and reporting vulnerabilities.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• WAHA HTTP API - WhatsApp HTTP API
• WAHA Node SDK - TypeScript SDK for WAHA
• OpenTUI - Terminal UI framework used by waha-tui