A TypeScript-based reporting bot that summarizes activity from your Twenty CRM workspace and sends daily/periodic reports to Slack, Discord, and WhatsApp. Meet Kylian Mbaguette, your friendly CRM activity reporter!

Features

🧑‍💻 People & Company Tracking: Summarizes newly created people and companies
🎯 Opportunity Monitoring: Reports on new opportunities created, broken down by stage
✅ Task Analytics:
- Tracks task creation
- Calculates on-time completion rates
- Identifies team members with the most overdue tasks (the "slackers")
🔔 Multi-Platform Notifications: Send reports to Slack, Discord, and/or WhatsApp
⏰ Configurable Time Range: Look back any number of days

Prerequisites

Node.js (v14 or higher recommended)
TypeScript
A Twenty CRM account with API access
Optional: Slack webhook, Discord webhook, and/or WhatsApp Business API access

Installation

# Clone the repository
git clone <your-repo-url>
cd <project-directory>

# Install dependencies
npm install

Configuration

Create a .env file in the root directory with the following variables:

# Required
TWENTY_API_KEY=your_twenty_api_key_here
DAYS_AGO=7  # Number of days to look back

# Optional - Include only the platforms you want to use
SLACK_HOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL
DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/YOUR/WEBHOOK/URL
FB_GRAPH_TOKEN=your_facebook_graph_api_token
WHATSAPP_RECIPIENT_PHONE_NUMBER=+1234567890

Environment Variables

Variable	Required	Description
`TWENTY_API_KEY`	✅ Yes	Your Twenty CRM API key
`DAYS_AGO`	✅ Yes	Number of days to look back for the report
`SLACK_HOOK_URL`	❌ No	Slack incoming webhook URL
`DISCORD_WEBHOOK_URL`	❌ No	Discord webhook URL
`FB_GRAPH_TOKEN`	❌ No	Facebook Graph API token for WhatsApp
`WHATSAPP_RECIPIENT_PHONE_NUMBER`	❌ No	WhatsApp recipient phone number (with country code)

Usage

# Run the application
npm start
# or
node dist/index.js  # if compiled

# For development
npm run dev  # if you have ts-node configured

Project Structure

.
├── index.ts                              # Main entry point
├── people-creation-summariser.ts         # Summarizes people/company creation
├── opportunity-creation-summariser.ts    # Summarizes opportunity creation
├── task-creation-summariser.ts           # Summarizes task creation & completion
├── senders.ts                            # Handles sending to Slack/Discord/WhatsApp
├── utils.ts                              # API request utility
└── README.md

How It Works

Data Collection: The bot queries the Twenty CRM API for activities within the specified time range
Analysis:
- Counts new people and companies
- Categorizes opportunities by stage
- Calculates task completion rates and identifies overdue tasks
Reporting: Formats the data into friendly messages
Distribution: Sends reports to configured platforms (Slack, Discord, WhatsApp)

Report Format

Each report includes:

Bonjour! 🥖 Je m'appelle Kylian Mbaguette. Over the last X days:

🧑‍💻 People & Companies
- X People and Y Companies were added

🎯 Opportunities
- X Opportunities were added: Y in NEW, Z in PROPOSAL

📋 Tasks
- X Tasks were created
- Y% Tasks were completed on time
- [Name] slacked the most with Z Tasks overdue

API Integration

This bot uses the Twenty CRM REST API. The following endpoints are used:

GET /people - Fetch people data
GET /companies - Fetch company data
GET /opportunities - Fetch opportunity data
GET /tasks - Fetch task data
GET /workspaceMembers/{id} - Fetch workspace member details

Development

# Install dependencies
npm install

# Compile TypeScript
npx tsc

# Run in development mode
npx ts-node index.ts

Notes

The "slacker" detection is lighthearted and identifies team members with the most overdue tasks
At least one messaging platform must be configured for the bot to send reports
The bot uses ISO date format (YYYY-MM-DD) for date filtering
Task completion percentage only considers incomplete tasks (excludes already completed tasks from the calculation)

Troubleshooting

Issue: No messages being sent

Solution: Ensure at least one messaging platform is configured with valid credentials

Issue: API authentication errors

Solution: Verify your TWENTY_API_KEY is correct and has necessary permissions

Issue: WhatsApp messages not sending

Solution: Ensure both FB_GRAPH_TOKEN and WHATSAPP_RECIPIENT_PHONE_NUMBER are set correctly

Contributing

Built with ❤️ and 🥖 by Azmat, Ali and Mike from 9dots