Audience Builder — Auto-tagging contacts for WhatsApp campaigns

A web app that lets you build segmentation rules combining any Chatwoot attribute and automatically apply audience tags.

Why I built it

Manually tagging contacts in Chatwoot for WhatsApp campaigns is tedious: filter → tag page by page → repeat every campaign. This app automates that by letting you define rules visually and apply tags to all matching contacts in one click.

How it works

1. Build your rule by selecting fields (custom attributes, standard fields, labels, inbox/channel) and operators (equals, contains, greater than, etc.)
2. Choose AND or OR logic for combining conditions
3. Preview matching contacts
4. Execute — the app tags all matches with NNN_tag_<your-name> format

The tag in Chatwoot is the saved rule — no database needed. Stateless by design.

Key features

• All Chatwoot attribute types: text, number, date, list, boolean
• Contact and Conversation-scoped custom attributes (evaluates against the latest conversation)
• AND/OR flat logic matching Chatwoot's contact filter API semantics
• Preview before tagging — see exactly who will be tagged
• Split-tagging: tag only the first N contacts
• Tag lifecycle: list, count, and delete audience tags from the app
• Chatwoot-native UI with light/dark mode (prefers-color-scheme)

Tech stack

• Python 3.12 + FastAPI
• httpx async HTTP client with retry
• Jinja2 + vanilla JS (no build step)
• Docker multi-arch (arm64)
• MIT licensed

Quick start

git clone https://github.com/CrisAlva1414/Chatwoot-Tags.git
cd Chatwoot-Tags
cp .env.example .env
# Edit .env with your Chatwoot instance URL, account ID, and bot token
docker compose up -d

Open http://localhost:8000 and start building audiences.

Screenshots

Coming soon — but it looks and feels like Chatwoot native UI.

Feedback and contributions welcome!