wgtechlabs/unthread-whatsapp-bot

wgtechlabs/unthread-whatsapp-bot repository overview

⁠Unthread WhatsApp Bot

Official Unthread extension for WhatsApp support via Twilio. Bridges WhatsApp customers to your Unthread support workspace — inbound, outbound, and file attachments included.

⁠What it does

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)
Supports inbound and outbound file attachments via media proxy

⁠How it works

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

Inbound: Twilio calls POST /webhooks/twilio, the bot resolves or creates the customer and conversation in Unthread.
Outbound: unthread-webhook-server⁠ pushes Unthread events to Redis; this bot forwards replies to WhatsApp.

⁠Quick Start

docker compose up -d
docker compose logs -f server

⁠Required Environment Variables

Variable	Purpose
`TWILIO_ACCOUNT_SID`	Twilio account SID
`TWILIO_AUTH_TOKEN`	Twilio auth token
`TWILIO_WHATSAPP_NUMBER`	Sender WhatsApp number (e.g. `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

⁠Key Optional Variables

Variable	Default	Notes
`REDIS_URL`	empty	Platform cache via Nuvex
`WEBHOOK_REDIS_URL`	empty	Required for outbound replies
`WEBHOOK_QUEUE_NAME`	`unthread-events`	Queue name used by webhook server
`PORT`	`3000`	App port
`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

⁠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

⁠Prerequisites

Twilio account with WhatsApp sandbox or approved number
Unthread API key and channel ID
PostgreSQL
Redis (required for outbound events, optional for platform cache)

⁠Links

GitHub: wgtechlabs/unthread-whatsapp-bot⁠
Issues & Support: GitHub Discussions⁠
Deploy on Railway: One-click deploy⁠

Licensed under GNU GPL v3.0⁠ · Made by WG Technology Labs⁠

Tag summary

Recent tags

Content type

Image

Digest

sha256:4b6ea1c68…

Size

103.9 MB

Last updated

1 day ago

docker pull wgtechlabs/unthread-whatsapp-bot

This week's pulls

Pulls:

706

Last week

Learn more⁠