Documentation - ChitChatPosts

Overview

ChitChatPosts is a Slack bot that observes your team's conversations and suggests social media posts. There are two ways to use it:

☁️

Option A: Hosted Version

We handle everything. Just click "Add to Slack" and you're done. Best for most teams.

✓ One-click installation
✓ Automatic updates
✓ No server to manage

Quick Start →

🔧

Option B: Self-Hosted

Full control. Clone the repo, use your own API keys, run on your infrastructure.

✓ Complete data control
✓ Use your own LLM keys
✓ Customize everything

Self-Host Guide →

Quick Start (Hosted)

Get up and running in under 2 minutes.

1

Add to Slack

Click the button below to install ChitChatPosts in your workspace:

Add to Slack

2

Allow Permissions

Slack will ask you to authorize the following:

Read messages in channels the bot is added to
Send messages as the bot
Access to slash commands

3

Invite to Channels

Add the bot to channels you want it to monitor:

/invite @ChitChatPosts

4

Start Analyzing

After some conversation happens, run:

/chitchatposts analyze

🎉 That's it! The bot will now listen to conversations and suggest post-worthy content when you run the analyze command.

Prerequisites (Self-Hosted)

Before you begin, make sure you have:

📦

Node.js 18+

JavaScript runtime

🔧

npm or yarn

Package manager

💬

Slack Workspace

Admin access required

🤖

LLM API Key

OpenAI or Claude

Step 1: Create Slack App

1

Go to Slack API Dashboard

Visit api.slack.com/apps and click "Create New App".

2

Choose "From Scratch"

Name your app (e.g., "ChitChatPosts") and select your workspace.

3

Enable Socket Mode

Go to Socket Mode in the sidebar and enable it. Generate an App-Level Token with connections:write scope.

SLACK_APP_TOKEN=xapp-1-A0123456789-...

4

Add Bot Scopes

Go to OAuth & Permissions and add these Bot Token Scopes:

channels:history channels:read chat:write commands groups:history groups:read im:history mpim:history

5

Install to Workspace

Click "Install to Workspace" and authorize. Copy the Bot User OAuth Token:

SLACK_BOT_TOKEN=xoxb-1234567890-...

6

Get Signing Secret

Go to Basic Information and copy the Signing Secret:

SLACK_SIGNING_SECRET=abc123def456...

7

Create Slash Command

Go to Slash Commands and create a new command:

Command	`/chitchatposts`
Description	Analyze conversations for post-worthy content
Usage Hint	[analyze \| history 4h \| sync]

8

Enable Events

Go to Event Subscriptions, enable events, and subscribe to:

message.channels message.groups message.im message.mpim

Step 2: Environment Variables

Create a .env file in your project root:

# Slack Configuration (Required)
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_APP_TOKEN=xapp-your-app-token

# LLM Configuration (Choose One)
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-openai-key

# Or use Claude
# LLM_PROVIDER=claude
# CLAUDE_API_KEY=your-claude-key

# Optional Configuration
PORT=3000
BUFFER_WINDOW_HOURS=4
MIN_MESSAGES_FOR_ANALYSIS=5

Variable	Required	Description
`SLACK_BOT_TOKEN`	✅	Bot User OAuth Token (starts with xoxb-)
`SLACK_SIGNING_SECRET`	✅	From Basic Information page
`SLACK_APP_TOKEN`	✅	App-Level Token (starts with xapp-)
`LLM_PROVIDER`	❌	Either "openai" or "claude" (default: openai)
`OPENAI_API_KEY`	❌*	Required if using OpenAI
`CLAUDE_API_KEY`	❌*	Required if using Claude
`PORT`	❌	Server port (default: 3000)
`BUFFER_WINDOW_HOURS`	❌	How long to keep messages (default: 4)
`MIN_MESSAGES_FOR_ANALYSIS`	❌	Minimum messages needed (default: 5)

Step 3: Run Locally

1

Clone the Repository

                                git clone https://github.com/yourusername/chitchatposts.git
cd chitchatposts
                            

2

Install Dependencies

npm install

3

Setup Environment

                                cp .env.example .env
# Edit .env with your tokens
                            

4

Start the Bot

npm run dev

You should see:

                                ⚡️ ChitChatPosts is running!
Mode: Socket Mode (real-time events)
LLM Provider: openai
LLM Configured: ✅ Yes
                            

💡 Socket Mode means no public URL is needed for local development. The bot connects directly to Slack's servers via WebSocket.

Step 4: Deploy to Production

Deploy ChitChatPosts to any Node.js hosting platform:

🚀 Railway

                            railway init
railway up
                        

▲ Vercel

                            vercel
# Set env vars in dashboard
                        

🌊 Render

                            # Connect GitHub repo
# Add environment variables
# Deploy
                        

🐳 Docker

                            docker build -t chitchatposts .
docker run -d --env-file .env chitchatposts
                        

LLM Setup

ChitChatPosts supports both OpenAI and Claude. Choose one:

Go to OpenAI API Keys
Create a new API key
Add to your .env:

                        LLM_PROVIDER=openai
OPENAI_API_KEY=sk-your-key-here
                    

Model used: GPT-4o-mini (cost-effective, fast, accurate)

Go to Anthropic Console
Create a new API key
Add to your .env:

                        LLM_PROVIDER=claude
CLAUDE_API_KEY=your-claude-key-here
                    

Model used: Claude 3 Sonnet (nuanced understanding)

Commands Reference

`/chitchatposts analyze`

Analyze the current message buffer for post-worthy content.

/chitchatposts analyze

`/chitchatposts history [time]`

Fetch and analyze messages from a specific time period.

                        /chitchatposts history 1h   # Last hour
/chitchatposts history 4h   # Last 4 hours
/chitchatposts history 1d   # Last day
                    

`/chitchatposts sync`

Fetch all messages since the last sync point.

/chitchatposts sync

Multi-Workspace OAuth (Advanced)

To support multiple workspaces, you need to implement OAuth:

⚠️ Advanced This is only needed if you want to distribute your app to multiple workspaces.

Required Changes:

Add Redirect URL in Slack App Dashboard → OAuth & Permissions
Store tokens per workspace instead of using env vars
Use dynamic token lookup when responding to events

// Example: OAuth callback handler
app.get('/slack/oauth/callback', async (req, res) => {
  const { code, team_id } = req.query;
  
  const result = await client.oauth.v2.access({
    client_id: process.env.SLACK_CLIENT_ID,
    client_secret: process.env.SLACK_CLIENT_SECRET,
    code
  });
  
  // Store token for this workspace
  await saveToken(team_id, result.access_token);
  
  res.redirect('/success');
});

Automated Suggestions (Autopilot)

ChitChatPosts can automatically analyze your channels and post suggestions without manual commands. This is the Autopilot feature.

💡 How it works: When enabled, the bot runs scheduled analysis every 6 hours and a daily summary at midnight. Suggestions are posted to a dedicated channel for your team to review.

Enable Autopilot

Add these environment variables to your .env file:

# Enable automated analysis
CRON_ENABLED=true

# Channel where suggestions will be posted
SUGGESTIONS_CHANNEL_ID=C0123456789

# Channels to monitor (comma-separated, leave empty for all)
MONITORED_CHANNELS=C0123456789,C0987654321

Variable	Required	Description
`CRON_ENABLED`	❌	Set to "true" to enable automated analysis (default: false)
`SUGGESTIONS_CHANNEL_ID`	✅*	Channel ID where suggestions will be posted
`MONITORED_CHANNELS`	❌	Comma-separated list of channel IDs to monitor

Schedule

When Autopilot is enabled, the bot runs on the following schedule:

Every 6 hours (0:00, 6:00, 12:00, 18:00 UTC) — Analyzes the last 6 hours of conversation
Daily at midnight (UTC) — Comprehensive 24-hour summary

Smart Features

🔁

Deduplication

Skips suggestions that are too similar to previous ones (>80% match)

⏭️

Skip Empty Runs

Won't re-analyze if no new messages have arrived since the last run

📢

Dedicated Channel

All automated suggestions go to a channel you specify

🔒

Human Approval

Suggestions are never posted to social media automatically

Example Output

Here's what an automated suggestion looks like in Slack:

                    💡 New Post Suggestion
Source: 6-hour analysis • Generated automatically

Why this works:
User shares a significant productivity improvement achieved through AI tools, showcasing a tangible benefit that resonates with others in the industry.

📝 LinkedIn Draft:
Excited to share a recent breakthrough! We leveraged AI to reduce our publication time from 4 hours to just 2 minutes...

𝕏 Twitter/X Draft:
Just reduced our publication time from 4 hours to 2 mins using AI! 🚀 Huge boost in team performance. #Productivity #AI

🔒 Please review and edit before posting. Human approval required.
                

⚠️ Finding Channel IDs Right-click a channel in Slack → "View channel details" → Scroll to the bottom to find the Channel ID (starts with C).

Installation Guide

Overview

Option A: Hosted Version

Option B: Self-Hosted

Quick Start (Hosted)

Add to Slack

Allow Permissions

Invite to Channels

Start Analyzing

Prerequisites (Self-Hosted)

Step 1: Create Slack App

Go to Slack API Dashboard

Choose "From Scratch"

Enable Socket Mode

Add Bot Scopes

Install to Workspace

Get Signing Secret

Create Slash Command

Enable Events

Step 2: Environment Variables

Step 3: Run Locally

Clone the Repository

Install Dependencies

Setup Environment

Start the Bot

Step 4: Deploy to Production

🚀 Railway

▲ Vercel

🌊 Render

🐳 Docker

LLM Setup

Commands Reference

/chitchatposts analyze

/chitchatposts history [time]

/chitchatposts sync

Multi-Workspace OAuth (Advanced)

Required Changes:

Automated Suggestions (Autopilot)

Enable Autopilot

Schedule

Smart Features

Example Output

Need Help?

`/chitchatposts analyze`

`/chitchatposts history [time]`

`/chitchatposts sync`