IntercomMetrics

A comprehensive Intercom customer support metrics extraction and reporting system that automatically collects key performance indicators from your Intercom workspace and delivers actionable insights via Slack notifications.

🎯 Overview

IntercomMetrics helps customer support teams monitor and improve their performance by:

Extracting comprehensive metrics from Intercom API (conversations, response times, SLA performance)
Analyzing conversation states (open, closed, snoozed) with detailed breakdowns
Tracking response time trends with 24-hour and 14-day analysis windows
Generating escalation alerts for critical issues and performance thresholds
Delivering formatted reports to Slack channels with actionable insights
Supporting automated workflows via GitHub Actions for scheduled reporting

✨ Key Features

📊 Metrics Collection

Conversation Analysis: Track open, closed, and snoozed conversations with priority breakdowns
Response Time Monitoring: Analyze first response times and average response times
Team Performance: Monitor individual admin performance and workload distribution
SLA Tracking: Analyze SLA compliance and breach notifications
Spam Filtering: Built-in spam detection to keep metrics accurate
Pagination Support: Handle large datasets efficiently

🚨 Intelligent Alerting

Escalation Analysis: Automated detection of concerning trends and threshold breaches
Critical Alerts: Real-time notifications for urgent issues requiring immediate attention
Performance Warnings: Early indicators of potential problems
Team Health Monitoring: Identify workload imbalances and inactive team members

📈 Slack Integration

Formatted Reports: Clean, readable metrics summaries with emojis and structure
Multi-Channel Support: Send reports to different channels based on alert severity
Chart Generation: Visual trends and performance charts (optional)
Actionable Insights: Highlight conversations needing immediate attention

🚀 Quick Start

Option 1: GitHub Actions (Recommended)

Fork this repository to your GitHub account

Set up repository secrets in your GitHub repository settings:

Settings → Secrets and variables → Actions → New repository secret

Add required secrets:

INTERCOM_ACCESS_TOKEN=your_intercom_token_here
SLACK_BOT_TOKEN=xoxb-your-slack-bot-token
SLACK_CHANNEL=#your-channel
SLACK_ALERTS_CHANNEL=#alerts-channel

Run the workflow:
- Go to Actions tab → "Intercom Metrics Extraction"
- Click "Run workflow"
- Optionally enable "Also generate and send Slack report"

Option 2: Local Execution

Clone the repository:

git clone https://github.com/muldercw/IntercomMetrics.git
cd IntercomMetrics

Install dependencies:
```
pip install -r requirements.txt
```

Create environment file:

cp .env.example .env  # Create this file with your settings

Run metrics extraction:
```
python intercom_metrics.py
```
Send Slack report (optional):
```
python slack_reporter.py
```

Option 3: Self-Hosted Runner

For users who prefer running on their own infrastructure, you can deploy a self-hosted GitHub Actions runner using Docker:

🐳 Use our Dockerized Runner: muldercw/DOCERKIZED_RUNNER

This provides a complete Docker-based GitHub Actions runner that can be deployed with just:

git clone https://github.com/muldercw/DOCKERIZED_RUNNER.git
cd DOCKERIZED_RUNNER
cp .env.template .env  # Configure with your GitHub repository
docker compose up --build

Benefits of self-hosted runners:

Enhanced Security: Keep sensitive data within your infrastructure
Cost Control: No GitHub Actions minute usage for private repositories
Resource Control: Dedicated compute resources for your workflows
Network Access: Access to internal services and databases

⚙️ Configuration

Environment Variables

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

Required for Metrics Collection

# Intercom API Configuration
INTERCOM_ACCESS_TOKEN=your_intercom_access_token

# Basic Configuration
REPORT_TIMEZONE=UTC
EXCLUDE_SPAM_CONVERSATIONS=true
PAGINATE_CONVERSATIONS=true
CONVERSATION_PAGE_SIZE=50
CONVERSATION_MAX_PAGES=2

Required for Slack Reporting

# Slack Configuration (choose one method)
SLACK_BOT_TOKEN=xoxb-your-slack-bot-token  # Recommended
# OR
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/...

# Slack Channels
SLACK_CHANNEL=#intercom-metrics           # Main reports
SLACK_ALERTS_CHANNEL=#alerts-support      # Critical alerts

Getting Your Intercom Access Token

Log in to your Intercom workspace
Go to Settings → Integrations → Developer Hub
Create a new app or select existing app
Generate an Access Token with the following permissions:
- Read conversations
- Read contacts
- Read companies
- Read admins
- Read articles (optional)

Setting Up Slack Integration

Method 1: Bot Token (Recommended)

Create a Slack App:
- Go to Slack API
- Click "Create New App" → "From scratch"
- Name your app and select your workspace
Configure Bot Permissions:
- Go to "OAuth & Permissions" → "Bot Token Scopes"
- Add these scopes:
  - chat:write - Send messages
  - files:write - Upload charts
  - channels:read - Access channel information
Install App to Workspace:
- Click "Install App to Workspace"
- Copy the "Bot User OAuth Token" (starts with xoxb-)
Invite Bot to Channels:
```
/invite @YourBotName
```

Method 2: Webhook URL (Alternative)

Create Incoming Webhook:
- Go to your Slack workspace → Apps → Incoming Webhooks
- Click "Add to Slack" and select channel
- Copy the webhook URL

Note: Webhooks have limited functionality compared to bot tokens.

Configuration Options

Variable	Default	Description
`EXCLUDE_SPAM_CONVERSATIONS`	`true`	Filter out conversations identified as spam
`PAGINATE_CONVERSATIONS`	`true`	Fetch all conversations using pagination
`CONVERSATION_PAGE_SIZE`	`50`	Number of conversations per API page
`CONVERSATION_MAX_PAGES`	`2`	Maximum pages to fetch (prevents excessive API usage)
`REPORT_TIMEZONE`	`UTC`	Timezone for timestamps in reports

📋 Usage Examples

GitHub Actions Workflow

The included workflow (.github/workflows/intercom_metrics.yml) can be:

Triggered manually via the Actions tab

Scheduled using cron syntax:

on:
  schedule:
    - cron: '0 9 * * 1-5'  # 9 AM weekdays

Triggered by events:

on:
  issues:
    types: [opened, closed]

Local Automation

Set up automated reports using cron:

# Run daily at 9 AM
0 9 * * * cd /path/to/IntercomMetrics && python slack_reporter.py

# Run metrics extraction every 6 hours
0 */6 * * * cd /path/to/IntercomMetrics && python intercom_metrics.py

Custom Analysis

Extract specific metrics programmatically:

from intercom_metrics import IntercomMetricsClient

client = IntercomMetricsClient(access_token="your_token")

# Get current open conversations
open_convos = client.get_current_open_conversations(limit=20)

# Analyze response times
response_metrics = client.get_detailed_response_metrics_24h(conversation_ids)

# Generate escalation analysis
from slack_reporter import EscalationAnalyzer
analyzer = EscalationAnalyzer()
alerts = analyzer.generate_escalation_report(metrics_data)

📊 Sample Output

Slack Report Example

📊 Intercom Metrics Report - 2024-01-15 09:00

📈 Overview:
• Admins: 5
• Companies: 1,247
• Contacts: 8,932
• Conversations: 156

💬 Conversation Status:
• Open: 23
• Closed: 12,446
• Assigned: 18
• Unassigned: 5

🔄 Open Conversations Details (23 total):
• Assignment: 18 assigned, 5 unassigned
• Response status: 12 awaiting agent, 8 awaiting customer, 3 unknown
• Wait times: <1h(8), 1-4h(6), 4-24h(7), >24h(2)

⚠️ Currently (5 conversations need attention):
1. 🔴 Billing Issue - Account Suspended
   Customer: John D. | Wait: 3.2h | 🚨 Unassigned | Status: ⏳ Need to respond
   💬 "My account was suspended but I paid my bill yesterday..."

2. 🟡 Integration Problem
   Customer: Sarah M. | Wait: 1.5h | 👤 Alice | Status: ⏳ Need to respond

Critical Alert Example

🚨 CRITICAL INTERCOM ALERTS 🚨
• 🚨 CRITICAL: 25 open conversations (threshold: 20)
• 🚨 CRITICAL: Average first response time (24h) is 26.3h (threshold: 24h)
• ⚠️ WARNING: 8 unassigned conversations need attention

🔧 Advanced Configuration

Escalation Thresholds

Customize alert thresholds by modifying the EscalationAnalyzer configuration:

escalation_config = {
    'response_time_thresholds': {
        'first_response_critical_hours': 24,
        'first_response_warning_hours': 12,
        'avg_response_critical_hours': 48,
        'avg_response_warning_hours': 24
    },
    'volume_thresholds': {
        'backlog_critical_count': 20,
        'backlog_warning_count': 10,
        'daily_increase_warning_pct': 50
    }
}

Custom Metrics

Extend the system with custom metrics:

def custom_satisfaction_analysis(client):
    # Your custom analysis logic
    conversations = client.get_conversations_paginated()
    # Process satisfaction scores, custom tags, etc.
    return custom_metrics

# Integrate into reporting workflow
metrics_data['custom_analysis'] = custom_satisfaction_analysis(client)

🛠️ Troubleshooting

Common Issues

"Error: INTERCOM_ACCESS_TOKEN environment variable not set"

Verify your .env file exists and contains the token
For GitHub Actions, check that the secret is properly configured
Ensure the token has the required permissions

"Slack API error: not_in_channel"

Invite your bot to the target channel: /invite @YourBotName
Verify the channel name is correct (include # prefix)
Check that the bot has chat:write permission

"No Intercom metrics files found"

Ensure intercom_metrics.py ran successfully first
Check for any error messages in the script output
Verify API connectivity and token validity

Rate Limiting Issues

Reduce CONVERSATION_PAGE_SIZE (default: 50)
Increase delays between API calls
Consider running less frequently

Performance Optimization

Large Workspaces: For workspaces with thousands of conversations:

Set CONVERSATION_MAX_PAGES=1 for faster execution
Use EXCLUDE_SPAM_CONVERSATIONS=true to reduce noise
Run reports less frequently (daily instead of hourly)

API Usage: Monitor your Intercom API usage:

Check API rate limits in Intercom developer settings
Adjust pagination settings based on your API allowance
Consider upgrading your Intercom plan for higher limits

Debug Mode

Enable verbose logging:

export DEBUG=true
python intercom_metrics.py

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Create a feature branch: git checkout -b feature/your-feature-name
Make your changes following our coding standards
Test thoroughly with your own Intercom workspace
Submit a pull request with a clear description

Development Setup

git clone your-fork-url
cd IntercomMetrics
pip install -r requirements.txt
cp .env.example .env  # Configure for testing

Contribution Ideas

📊 Additional chart types and visualizations
🔔 New escalation rules and alert types
📱 Integration with other communication platforms
🎯 Custom metrics and KPI calculations
🛠️ Performance improvements and optimizations
📚 Documentation improvements and examples

📄 License

This project is provided as-is for educational and development purposes.

🆘 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Self-Hosted Runner: DOCERKIZED_RUNNER Repository

🙏 Acknowledgments

Built for teams using Intercom for customer support
Designed to work seamlessly with GitHub Actions workflows
Compatible with self-hosted runners for enhanced security and control

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.github/workflows		.github/workflows
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
intercom_metrics.py		intercom_metrics.py
requirements.txt		requirements.txt
slack_reporter.py		slack_reporter.py

muldercw/IntercomMetrics

Folders and files

Latest commit

History

Repository files navigation