Official Unthread Extension — The Unthread WhatsApp Bot connects your WhatsApp Business number with Unthread's powerful ticket management system via Twilio. Customers message your WhatsApp number, messages flow into Unthread as tickets, and agent replies are sent back to WhatsApp — with automatic system notifications for ticket creation and status changes.

This bot is designed for businesses managing customer support through WhatsApp — optimized for professional support workflows with seamless bidirectional communication between your team and customers.

💎 Platinum Sponsor
Unthread Streamlined support ticketing for modern teams.

Customer (WhatsApp) → Twilio → Bot → Unthread (ticket created)
                                          ↓
Agent replies in Unthread → Webhook Server → Redis Queue → Bot → Twilio → Customer (WhatsApp)

1. Customer sends a WhatsApp message
2. Twilio forwards to the bot's webhook endpoint
3. Bot resolves or creates an Unthread customer (using phone-based identity)
4. Bot resolves or creates a conversation (ticket) with the initial message
5. A "Support Ticket Created" system message is sent to the customer with their ticket number

1. The companion unthread-webhook-server receives Unthread events and pushes them to a Redis queue
2. Bot continuously polls the Redis queue
3. Agent replies (message_created) are forwarded to the customer via Twilio
4. Status changes (conversation_updated) trigger system notifications (closed, on hold, resumed)

Customers receive automatic notifications for ticket lifecycle events:

• Ticket Created — confirmation with ticket number when a new conversation is opened
• Ticket Closed — notification when a ticket is closed or resolved
• Ticket On Hold — notification when a ticket is placed on hold
• Ticket Resumed — notification when a ticket moves back to active from hold

• Seamless Ticket Creation: Incoming WhatsApp messages automatically create Unthread support tickets
• Bidirectional Communication: Agent replies in Unthread are forwarded back to the customer via WhatsApp
• System Notifications: Automatic WhatsApp messages for ticket lifecycle events (created, closed, on hold, resumed)
• Customer Management: Automatic customer profile creation using phone-based identity
• Multi-layer Storage: Nuvex-powered persistence (Memory + Redis + PostgreSQL)
• Webhook Queue Processing: Redis-based queue consumption from unthread-webhook-server
• Health Monitoring: Built-in health check endpoint with storage diagnostics
• Docker Ready: Full-stack docker-compose.yml with all required services

• Bun v1.0+
• PostgreSQL database
• Twilio account with WhatsApp sandbox (or approved number)
• Unthread API key
• Redis for platform storage/cache
• Redis for webhook queue (used by unthread-webhook-server)

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

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

cp .env.example .env

# Development (with hot reload)
bun dev

# Production
bun start

1. Go to Twilio Console > Messaging > WhatsApp Sandbox
2. Set the webhook URL to https://your-domain.com/webhooks/twilio
3. Method: POST

1. Run unthread-webhook-server with TARGET_PLATFORM=whatsapp
2. In Unthread, configure a webhook pointing to your webhook-server endpoint: https://your-domain.com/unthread-webhook
3. Subscribe to message_created and conversation_updated events

A docker-compose.yml is provided with the full stack:

# Start all services
docker compose up -d

# View logs
docker compose logs -f server

# Reset everything (fresh start with clean databases)
docker compose down -v && docker compose up -d

💡 Tip: Use docker compose down -v to completely reset your local environment. This is safe for development and useful after version upgrades or when you need a clean slate.

Services included:

This bot is built with TypeScript on the Bun runtime for enhanced performance, type safety, and developer experience.

• TypeScript: For type safety and better code maintainability
• Bun: Fast all-in-one JavaScript runtime
• Express.js: HTTP server for Twilio webhook ingestion
• Twilio SDK: WhatsApp message delivery

Storage & Performance:

• PostgreSQL: Primary database via Nuvex multi-layer storage
• Redis: High-performance caching and webhook queue consumption

Infrastructure:

• Docker Compose: Complete local development environment with all services
• Health Monitoring: Built-in health check endpoint with storage diagnostics

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 🙏