https://github.com/ches-ctrl/ai-tinkerers-hack
https://github.com/ches-ctrl/ai-tinkerers-hack
Last synced: 10 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/ches-ctrl/ai-tinkerers-hack
- Owner: Ches-ctrl
- License: mit
- Created: 2025-07-17T17:07:40.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2025-07-17T19:23:14.000Z (11 months ago)
- Last Synced: 2025-07-17T20:37:02.806Z (11 months ago)
- Language: Python
- Size: 108 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
## Installation
### Prerequisites
- Go
- Python 3.6+
- FFmpeg (_optional_) - Only needed for audio messages. If you want to send audio files as playable WhatsApp voice messages, they must be in `.ogg` Opus format. With FFmpeg installed, the server will automatically convert non-Opus audio files. Without FFmpeg, you can still send raw audio files using the `send_file` tool.
### Steps
1. **Clone this repository**
```bash
git clone XXX
cd XXX
```
2. **Run the WhatsApp bridge**
Navigate to the whatsapp-bridge directory and run the Go application:
```bash
cd whatsapp-bridge
go run main.go
```
The first time you run it, you will be prompted to scan a QR code. Scan the QR code with your WhatsApp mobile app to authenticate.
After approximately 20 days, you will might need to re-authenticate.
## Architecture Overview
This application consists of two main components:
1. **Go WhatsApp Bridge** (`whatsapp-bridge/`): A Go application that connects to WhatsApp's web API, handles authentication via QR code, and stores message history in SQLite. It serves as the bridge between WhatsApp and the server.
XXX
### Data Storage
- All message history is stored in a SQLite database within the `whatsapp-bridge/store/` directory
- The database maintains tables for chats and messages
- Messages are indexed for efficient searching and retrieval
## Usage
Once connected, you can XXX
### Media Handling Features
The server supports both sending and receiving various media types:
#### Media Sending
You can send various media types to your WhatsApp contacts:
- **Images, Videos, Documents**: Use the `send_file` tool to share any supported media type.
- **Voice Messages**: Use the `send_audio_message` tool to send audio files as playable WhatsApp voice messages.
- For optimal compatibility, audio files should be in `.ogg` Opus format.
- With FFmpeg installed, the system will automatically convert other audio formats (MP3, WAV, etc.) to the required format.
- Without FFmpeg, you can still send raw audio files using the `send_file` tool, but they won't appear as playable voice messages.
#### Media Downloading
By default, just the metadata of the media is stored in the local database. The message will indicate that media was sent. To access this media you need to use the download_media tool which takes the `message_id` and `chat_jid` (which are shown when printing messages containing the meda), this downloads the media and then returns the file path which can be then opened or passed to another tool.
## Technical Details
2. The server queries the Go bridge for WhatsApp data or directly to the SQLite database
3. The Go accesses the WhatsApp API and keeps the SQLite database up to date
4. Data flows back through the chain
## Troubleshooting
- Make sure both the Go application and the Python server are running for the integration to work properly.
### Authentication Issues
- **QR Code Not Displaying**: If the QR code doesn't appear, try restarting the authentication script. If issues persist, check if your terminal supports displaying QR codes.
- **WhatsApp Already Logged In**: If your session is already active, the Go bridge will automatically reconnect without showing a QR code.
- **Device Limit Reached**: WhatsApp limits the number of linked devices. If you reach this limit, you'll need to remove an existing device from WhatsApp on your phone (Settings > Linked Devices).
- **No Messages Loading**: After initial authentication, it can take several minutes for your message history to load, especially if you have many chats.
- **WhatsApp Out of Sync**: If your WhatsApp messages get out of sync with the bridge, delete both database files (`whatsapp-bridge/store/messages.db` and `whatsapp-bridge/store/whatsapp.db`) and restart the bridge to re-authenticate.