WhatsApp Voice Message Transcription and AI Assistant

Warning

For educational purposes only. This project uses the unofficial WhatsApp multi-device protocol via whatsmeow. Running automated bots on a personal WhatsApp account violates WhatsApp's Terms of Service and risks having your account permanently banned.

Do not use this in production or at any scale.

If you need a production-grade WhatsApp integration, use the official WhatsApp Business Platform (Cloud API) provided by Meta.

A microservices-based WhatsApp bot that transcribes voice messages and audio files, with optional AI-powered responses via Groq.

Table of Contents

• Features
• Technologies Used
• Setup
  • Prerequisites
  • Environment Variables
  • Docker Compose (recommended)
  • Manual Installation
    • Go
    • Python
• Usage
  • Trigger Commands
  • Optional Flag
• Configuration
• Testing
• API Endpoint
• Contributing
• Acknowledgements

Features

• Transcribes WhatsApp voice notes and regular audio files
• Two trigger modes — transcribe-only, or transcribe and send to Groq for an AI response
• Early validation: replies with a usage hint if the quoted message is not audio
• Configurable transcription server URL and message prefix
• No GCC required — uses a pure-Go SQLite driver (modernc.org/sqlite)

Technologies Used

• Go
• Python
• FastAPI + Uvicorn
• SQLite (via modernc.org/sqlite - no CGO)
• whatsmeow — unofficial WhatsApp multi-device library
• Faster-Whisper — local speech recognition
• Groq API — fast LLM inference

Setup

Prerequisites

• Go 1.25+
• Python 3.x with uv
• A Groq API key from console.groq.com/keys

Note

GCC is no longer required. The project switched from mattn/go-sqlite3 (CGO) to modernc.org/sqlite (pure Go), so it builds on any platform without a C compiler.

Environment Variables

Copy sample.env to .env and fill in your values:

GROQ_API_KEY=your_key_here
TRANSCRIBE_URL=http://<flask-server-ip>:5000/transcribe

Variable	Required	Description
GROQ_API_KEY	For 1> transcribe	Groq API key for AI responses
TRANSCRIBE_URL	No	Transcription server URL. Defaults to http://127.0.0.1:5000/transcribe

Docker Compose (recommended)

The easiest way to run both services together. Only GROQ_API_KEY needs to be set — TRANSCRIBE_URL is wired automatically via Docker's internal network.

1. Copy sample.env to .env and add your Groq API key:

   GROQ_API_KEY=your_key_here

2. Build and start both services:

   docker compose up --build

   The first build downloads the medium.en Whisper model (~1.5 GB) and bakes it into the image. Subsequent starts are instant.

3. On first run, scan the QR code printed in the terminal to log into WhatsApp.

   If running detached (-d), view the QR code with:

   docker compose logs -f bot

The WhatsApp session is stored in a named Docker volume (whatsapp_session) so you only need to scan the QR code once. The transcription API docs are available at http://localhost:8000/docs.

Manual Installation

Go

Install dependencies:

go mod tidy

Build the binary:

# Linux / macOS
go build -o whatsapp-bot .

# Windows
go build -o whatsapp-bot.exe .

Note

Use go build rather than go run. On some platforms (e.g. Windows with Application Control policies), go run compiles to a temp directory that may be blocked from executing.

Python

Install dependencies via uv:

uv sync

Usage

1. Start the transcription server:

   uv run main.py

   If the bot runs on a different machine, note the server's IP address and set it as TRANSCRIBE_URL in your .env.

2. Start the bot:

   # Linux / macOS
   ./whatsapp-bot
   
   # Windows
   .\whatsapp-bot.exe

3. On first run, scan the QR code displayed in the terminal to log into WhatsApp.

4. Reply to a voice note or audio file with one of the trigger commands below.

Trigger Commands

Command	Behaviour
1> transcribe	Transcribe the audio, then send the transcript to Groq for an AI response
2> transcribe	Transcribe the audio only. No AI response sent

The trigger can appear anywhere in the message (e.g. can you 1> transcribe this?).

If you reply to a message that is not a voice note or audio file, the bot will send a hint explaining what to do instead.

Optional Flag

./whatsapp-bot --message-head "Transcript: "

--message-head sets the text prepended to every transcription reply. Defaults to *Transcript:*\n> (bold label with a block-quote indent).

Configuration

Setting	How to change
Transcription server URL	Set TRANSCRIBE_URL in .env
Groq AI model	Edit the Model field in groq/groq.go
Whisper model size	Edit model_name in main.py (default: medium.en)
Transcription reply prefix	Pass --message-head flag at startup

Testing

Run the full test suite:

go test ./...

For verbose output:

go test ./... -v

18 tests are included across two packages:

Test	Package	Cases
TestParseTrigger	main	9 - trigger command parsing edge cases
TestGetTranscription	main	4 - HTTP client against a local test server
TestHtmlToWhatsAppFormat	groq	10 - HTML-to-WhatsApp text conversion
TestSendPostRequestGroq	groq	4 - Groq API client against a local test server

All tests run without network access or external services.

API Endpoint

The transcription service exposes a single endpoint:

POST /transcribe

• Request body: raw binary audio data (application/octet-stream)
• Response: JSON object

{
  "transcription": "the transcribed text",
  "language": "en"
}

Contributing

1. Create a new issue
2. Fork the repository
3. Create a new branch
4. Commit your changes
5. Push to the branch
6. Create a new Pull Request

Acknowledgements

1. YASSERMD/whatsmeow-groq
2. hoehermann/whatsmeow-transcribe