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)

🤗 Special Thanks

💎 Platinum Sponsor
Unthread Streamlined support ticketing for modern teams.

🤔 How It Works

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.

🚀 Quick Start

Prerequisites

• 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)

1) Install

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

2) Configure

cp .env.example .env

Required variables:

Variable	Purpose
TWILIO_ACCOUNT_SID	Twilio account SID
TWILIO_AUTH_TOKEN	Twilio auth token
TWILIO_WHATSAPP_NUMBER	Sender WhatsApp number (for example whatsapp:+14155238886)
TWILIO_WEBHOOK_URL	Public webhook URL for signature validation
UNTHREAD_API_KEY	Unthread API key
UNTHREAD_SLACK_CHANNEL_ID	Unthread target channel
POSTGRES_URL	PostgreSQL connection string

Important optional variables:

Variable	Default	Notes
NODE_ENV	dev	dev, development, prod, production, test, staging
PORT	3000	App port
REDIS_URL	empty	Platform cache via Nuvex
WEBHOOK_REDIS_URL	empty	Required for webhook queue consumer
WEBHOOK_QUEUE_NAME	unthread-events	Queue name used by webhook server
UNTHREAD_WEBHOOK_SECRET	empty	Optional webhook secret
SLACK_TEAM_ID	empty	Optional, auto-detected for Slack file downloads
PUBLIC_BASE_URL	derived from TWILIO_WEBHOOK_URL	Base URL for media token links
MEDIA_TOKEN_TTL_SECONDS	600	Media proxy token TTL in seconds
MAX_ATTACHMENT_SIZE_BYTES	16777216	Max inbound attachment size

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

3) Run

# development
bun dev

# production
bun start

4) Point Twilio to the webhook

In Twilio WhatsApp Sandbox, set:

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

5) Run webhook ingestion for outbound replies

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

• message_created
• conversation_updated

🔌 Endpoints

Method	Path	Purpose
POST	/webhooks/twilio	Inbound Twilio WhatsApp webhook
GET	/media/:token	Short-lived media proxy for Twilio
GET	/health	App, version, and storage health

🐳 Docker Quick Start

docker compose up -d
docker compose logs -f server

Reset local data:

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

✅ Validate Changes

bun run lint
bun run typecheck
bun run test

💬 Community Discussions

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

🛟 Help & Support

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

🎯 Contributing

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.

💖 Sponsors

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! ☕

⭐ GitHub Star Nomination

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!

📃 License

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

📝 Author

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 🙏