Unthread WhatsApp Bot 📱

Official Unthread Extension for WhatsApp support via Twilio.

This integration does three core things:

• Converts inbound WhatsApp messages into Unthread conversations
• Sends agent replies from Unthread back to WhatsApp
• Sends automatic status system messages (created, closed, on hold, resumed)

💎 Platinum Sponsor
Unthread Streamlined support ticketing for modern teams.

Customer (WhatsApp) -> Twilio -> Bot -> Unthread
                                      |
Agent (Unthread) <- Webhook Server <- Redis Queue <- Bot

• Inbound path: Twilio calls POST /webhooks/twilio, then the bot resolves/creates customer + conversation in Unthread.
• Outbound path: unthread-webhook-server pushes Unthread events to Redis, then this bot forwards replies to WhatsApp.
• File support: inbound and outbound attachments are supported through media proxy links.

• Node.js 22, 24, or 26 (default runtime: Node.js 26)
• Bun 1.x
• Twilio account with WhatsApp sandbox or approved number
• Unthread API key and channel ID
• PostgreSQL
• Redis for webhook queue (required for outbound events)
• Redis for platform cache (optional, recommended)

git clone https://github.com/wgtechlabs/unthread-whatsapp-bot.git
cd unthread-whatsapp-bot
bun install

cp .env.example .env

Required variables:

Important optional variables:

Unthread API base URL is fixed internally to https://api.unthread.io/api.

# development
bun dev

# production
bun start

In Twilio WhatsApp Sandbox, set:

• URL: https://your-domain.com/webhooks/twilio
• Method: POST

Run unthread-webhook-server with TARGET_PLATFORM=whatsapp, then in Unthread subscribe to:

• message_created
• conversation_updated

Docker images use Node.js 26 Alpine as the base runtime (with Bun installed for the app toolchain).

docker compose up -d
docker compose logs -f server

Reset local data:

docker compose down -v && docker compose up -d

bun run lint
bun run typecheck
bun run test

Join our community discussions to get help, share ideas, and connect with other users:

• 📣 Announcements: Official updates from the maintainer
• 📸 Showcase: Show and tell your implementation
• 💖 Wall of Love: Share your experience with the bot
• 🛟 Help & Support: Get assistance from the community
• 🧠 Ideas: Suggest new features and improvements

Need help? Check our Help & Support discussions or create a new issue.

Important: All pull requests must be submitted to the dev branch. PRs to main will be automatically rejected.

Contributions are welcome! Your code must pass bun run typecheck before merging.

Like this project? Leave a star! ⭐⭐⭐⭐⭐

There are several ways you can support this project:

• Become a sponsor and get some perks! 💖
• Buy me a coffee if you just love what I do! ☕

Found this project helpful? Consider nominating me (@warengonzaga) for the GitHub Star program! This recognition supports ongoing development of this project and my other open-source projects. GitHub Stars are recognized for their significant contributions to the developer community — your nomination makes a difference and encourages continued innovation!

This project is licensed under the GNU General Public License v3.0. See the LICENSE file for the full license text.

This project is created by Waren Gonzaga under WG Technology Labs, with the help of awesome contributors.

💻 with ❤️ by Waren Gonzaga under WG Technology Labs, and Him 🙏