CRM & Platform Integration Guide

Overview

ChatMox sends real-time insights and alerts to your CRM and communication platforms so your team never has to babysit a dashboard:

• Error Alerts: when something breaks
• Performance Alerts: when latency spikes
• Weekly Reports: health summaries
• Cost Insights: daily / weekly spending
• Optimization Suggestions: actionable improvements
• Request Replay Status: debug session results

Each integration works via one (or more) of three mechanisms:

1. Webhooks: ChatMox pushes alerts to your platform
2. API Polling: you pull data from ChatMox on a schedule
3. OAuth: secure, scoped authentication for connected apps

Supported Integrations

Slack Integration

Setup Instructions

Step 1: Create a Slack App

1. Go to api.slack.com/apps
2. Click Create New App, then From scratch
3. App name: ChatMox Alerts
4. Choose your workspace
5. Click Create App

Step 2: Configure Incoming Webhook

1. In your app, go to Incoming Webhooks (left sidebar)
2. Toggle Activate Incoming Webhooks to On
3. Click Add New Webhook to Workspace
4. Select a channel, e.g. #chatmox-alerts (create it if needed)
5. Click Allow
6. Copy the webhook URL (looks like https://hooks.slack.com/services/T000/B000/XXXX)

Step 3: Add to ChatMox

POST /v1/admin/integrations/slack

{
  "name": "Slack Team",
  "webhook_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX",
  "channel": "#chatmox-alerts",
  "events": [
    "error_alert",
    "performance_alert",
    "weekly_report",
    "cost_milestone"
  ],
  "threshold_error_rate": 5,
  "threshold_latency_ms": 2000
}

Response

{
  "id": "int-slack-001",
  "platform": "slack",
  "status": "active",
  "created_at": "2026-06-12T10:30:00Z",
  "webhook_url": "https://hooks.slack.com/services/...",
  "test_message_sent": true
}

Message Formats

Error Alert

ERROR DETECTED

Provider: Gemini
Type: Rate Limit Exceeded
Error Rate: 12%
Affected Requests: 47

Recent Errors:
• Invalid API Key (15 times)
• Connection Timeout (12 times)
• Quota Exceeded (20 times)

Action: Check API key configuration
Debug Link: https://chatmox.com/logs?trace_uuid=abc123...

Performance Alert

PERFORMANCE SPIKE

Metric: Response Latency
Current: 3.5s (baseline: 1.2s)
Change: +192%

Provider: Claude
Status: 12% requests slow

Possible Causes:
• High token count (+40%)
• Cache miss (99%)
• API rate limiting

Suggestion: Reduce history window or use Gemini

Weekly Report

WEEKLY HEALTH REPORT

Performance:
• Success Rate: 98.5% (+0.3%)
• Avg Latency: 1.15s (-0.2s)
• Error Rate: 1.5% (-0.5%)

Cost:
• Total Spent: $342.50
• Avg Per Request: $0.0042
• Trending: +5% (usual growth)

Top Provider: Claude (65%)
Best Provider: Gemini (fastest)
Cheapest: DeepSeek ($0.003/req)

Top Issues:
1. Missing chunks (23%)
2. Slow responses (15%)
3. API errors (8%)

Optimizations Available:
• Switch 20% traffic to Gemini: Save $50/month
• Reduce history to 3 msgs: Save 30% latency
• Remove unused chunks: Clean up KB

Cost Milestone Alert

COST ALERT

You've spent $500 this month!
Budget remaining: $500 (50%)
Days left: 9

Burn Rate: $55.5/day
Projected Total: $1,000 (no changes)

Top Cost Drivers:
1. Claude API: 65% ($325)
2. Gemini API: 25% ($125)
3. Embeddings: 10% ($50)

Recommendations:
• Switch to DeepSeek for 80% of requests: Save $200
• Enable Claude cache: Save $100
• Reduce context window: Save $150

Optimization Suggestion

OPTIMIZATION AVAILABLE

Issue: Unused Chunks Detected
Impact: 10% KB bloat, slower searches

Data:
• Total Chunks: 247
• Used in Responses: 89
• Unused: 158

Savings Potential:
• Performance: +40% faster RAG retrieval
• Cost: -$5/month
• Quality: No change (never helped)

Action: Review and delete unused chunks
Link: https://chatmox.com/kb-analysis?brand_id=xyz

Custom Formatting

You can customize how alerts look:

{
  "slack_formatting": {
    "emoji_alerts": true,
    "thread_replies": true,
    "mention_on_critical": "@channel",
    "color_coding": {
      "error": "#FF0000",
      "warning": "#FFA500",
      "success": "#00FF00"
    }
  }
}

Testing the Slack Integration

Send a test message

curl -X POST https://your-chatmox-api.com/v1/admin/integrations/slack/test \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_id": "int-slack-001",
    "event_type": "error_alert"
  }'

Microsoft Teams Integration

Setup Instructions

Step 1: Create an Incoming Webhook

1. In Microsoft Teams, go to your channel
2. Click ... (More options), then Connectors
3. Search for Incoming Webhook
4. Click Configure
5. Name: ChatMox Alerts
6. (Optional) upload an image/icon
7. Click Create
8. Copy the webhook URL

Step 2: Add to ChatMox

POST /v1/admin/integrations/teams

{
  "name": "Teams Channel",
  "webhook_url": "https://outlook.webhook.office.com/webhookb2/...",
  "events": [
    "error_alert",
    "performance_alert",
    "weekly_report",
    "cost_milestone"
  ]
}

Message Format (Teams)

Teams uses Adaptive / MessageCard formatting for richer notifications:

{
  "@type": "MessageCard",
  "@context": "https://schema.org/extensions",
  "summary": "ChatMox Error Alert",
  "themeColor": "0078D4",
  "sections": [
    {
      "activityTitle": "Error Alert Detected",
      "activitySubtitle": "Gemini API - Rate Limit",
      "facts": [
        { "name": "Error Rate:", "value": "12%" },
        { "name": "Affected Requests:", "value": "47" },
        { "name": "Status:", "value": "Critical" }
      ]
    }
  ],
  "potentialAction": [
    {
      "@type": "OpenUri",
      "name": "View Logs",
      "targets": [
        { "os": "default", "uri": "https://chatmox.com/logs?trace_uuid=abc123" }
      ]
    }
  ]
}

Discord Integration

Setup Instructions

Step 1: Create a Discord Webhook

1. In your Discord server, go to channel settings
2. Go to Integrations, then Webhooks
3. Click Create Webhook
4. Name: ChatMox Alerts
5. (Optional) upload an icon
6. Click Copy Webhook URL

Step 2: Add to ChatMox

POST /v1/admin/integrations/discord

{
  "name": "Discord Server",
  "webhook_url": "https://discordapp.com/api/webhooks/123456789/abcdefghijklmnopqrst",
  "events": [
    "error_alert",
    "performance_alert",
    "weekly_report"
  ],
  "embed_format": true,
  "mention_role": "@admins"
}

Message Format (Discord)

Discord uses rich embeds:

{
  "embeds": [
    {
      "title": "Error Alert",
      "description": "Gemini API errors detected",
      "color": 16711680,
      "fields": [
        { "name": "Error Rate", "value": "12%", "inline": true },
        { "name": "Requests", "value": "47", "inline": true }
      ],
      "footer": { "text": "ChatMox Analytics" }
    }
  ]
}

Webhook Integration

For platforms not listed above, use a generic webhook.

Generic Webhook

POST /v1/admin/integrations/webhook

{
  "name": "Custom Webhook",
  "webhook_url": "https://your-system.com/api/chatmox-alerts",
  "events": [
    "error_alert",
    "performance_alert",
    "weekly_report"
  ],
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY",
    "X-Custom-Header": "value"
  },
  "payload_template": "chatmox_standard"
}

Webhook Payload Format

{
  "event_type": "error_alert",
  "timestamp": "2026-06-12T14:30:00Z",
  "severity": "critical",
  "data": {
    "provider": "gemini",
    "error_type": "rate_limit",
    "error_rate": 0.12,
    "affected_requests": 47,
    "message": "Gemini API rate limit exceeded",
    "suggestion": "Check API quota or wait before retrying"
  },
  "links": {
    "debug": "https://chatmox.com/logs?trace_uuid=abc123",
    "dashboard": "https://chatmox.com/admin/dashboard"
  },
  "retry_count": 0,
  "idempotency_key": "evt-abc123-def456"
}

Webhook Retry Logic

• Retry on: 5xx status codes, timeouts
• Retry count: 3 attempts
• Backoff: exponential (1s, 2s, 4s)
• Timeout: 10 seconds

Looking for the full webhook event reference, signature verification, and code samples in PHP, Python, Node.js, Ruby, C#, Java and Go? See the Webhooks documentation.

Email Integration

Setup

POST /v1/admin/integrations/email

{
  "name": "Email Alerts",
  "recipients": [
    "admin@company.com",
    "team@company.com"
  ],
  "events": [
    "weekly_report",
    "critical_alert",
    "cost_milestone"
  ],
  "frequency": "weekly",
  "day_of_week": "monday",
  "time_of_day": "09:00",
  "timezone": "UTC"
}

Email Template

Subject: [ChatMox] Weekly Health Report - June 12, 2026

Hello Team,

Here's your ChatMox weekly summary:

PERFORMANCE METRICS
- Success Rate: 98.5%
- Avg Latency: 1.15s
- Error Rate: 1.5%

COSTS THIS WEEK
- Total: $342.50
- Claude: $225 (65%)
- Gemini: $85 (25%)
- Embeddings: $32.50 (10%)

TOP RECOMMENDATIONS
1. Switch 20% to Gemini: Save $50/month
2. Reduce history window: +30% latency
3. Remove unused chunks: Cleaner KB

TRENDS
- Usage: +5% (normal growth)
- Costs: +3% (optimization potential)
- Quality: +2% (improvements working)

VIEW DETAILED ANALYTICS
https://chatmox.com/admin/dashboard

Questions? Reply to this email or visit docs.chatmox.io

---
ChatMox Team

API Integration

Prefer to fetch insights programmatically? Call the ChatMox Insights API directly.

Get Weekly Report

GET /v1/admin/insights/weekly-report

curl https://your-chatmox-api.com/v1/admin/insights/weekly-report \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "period": "2026-06-05 to 2026-06-12",
  "performance": {
    "success_rate": 0.985,
    "avg_latency_ms": 1150,
    "error_rate": 0.015,
    "trend": "up"
  },
  "cost": {
    "total": 342.50,
    "by_provider": {
      "claude": { "amount": 225, "percentage": 65 },
      "gemini": { "amount": 85, "percentage": 25 },
      "embeddings": { "amount": 32.50, "percentage": 10 }
    }
  },
  "recommendations": [
    {
      "type": "cost_optimization",
      "title": "Switch to cheaper provider",
      "description": "Use Gemini for 20% of requests",
      "potential_savings": 50
    }
  ]
}

Get Error Alerts

GET /v1/admin/insights/errors

curl "https://your-chatmox-api.com/v1/admin/insights/errors?days=7&severity=critical" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "total_errors": 47,
  "by_type": {
    "rate_limit": 20,
    "api_key_invalid": 15,
    "timeout": 12
  },
  "by_provider": {
    "gemini": 35,
    "claude": 10,
    "deepseek": 2
  },
  "suggestions": [
    "Check Gemini API key configuration",
    "Implement rate limiting on client side"
  ]
}

Get Performance Metrics

GET /v1/admin/insights/performance

curl "https://your-chatmox-api.com/v1/admin/insights/performance?granularity=hourly" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "data": [
    {
      "timestamp": "2026-06-12T14:00:00Z",
      "latency_ms": 1240,
      "success_rate": 0.98,
      "requests": 245,
      "errors": 5,
      "provider": "claude"
    }
  ]
}

Configuration

Global Settings

POST /v1/admin/integrations/settings

{
  "alert_thresholds": {
    "error_rate_percent": 5,
    "latency_ms": 2000,
    "cost_daily": 100
  },
  "notification_rules": {
    "critical": {
      "methods": ["slack", "email", "sms"],
      "mention": "@channel",
      "escalate_after_hours": true
    },
    "warning": {
      "methods": ["slack"],
      "mention": null,
      "escalate_after_hours": false
    }
  },
  "quiet_hours": {
    "enabled": true,
    "start": "18:00",
    "end": "09:00",
    "timezone": "UTC"
  },
  "digest_frequency": "daily",
  "digest_time": "09:00"
}

Per-Integration Settings

{
  "integration_id": "int-slack-001",
  "settings": {
    "thread_replies": true,
    "mention_on_critical": "@channel",
    "suppress_duplicates_minutes": 15,
    "max_messages_per_hour": 20,
    "detailed_logging": true
  }
}

Testing

Send a Test Alert

curl -X POST https://your-chatmox-api.com/v1/admin/integrations/{integration_id}/test \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "error_alert",
    "test_data": {
      "provider": "gemini",
      "error_rate": 0.12,
      "message": "Test error alert"
    }
  }'

Response

{
  "status": "success",
  "message": "Test message sent successfully",
  "platform": "slack",
  "delivery_time_ms": 145,
  "channel": "#chatmox-alerts"
}

Verify Webhook Health

curl https://your-chatmox-api.com/v1/admin/integrations/{integration_id}/health \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response

{
  "status": "healthy",
  "last_sent": "2026-06-12T14:30:00Z",
  "success_rate": 0.995,
  "last_5_deliveries": [
    { "timestamp": "2026-06-12T14:30:00Z", "status": "delivered" },
    { "timestamp": "2026-06-12T14:00:00Z", "status": "delivered" },
    { "timestamp": "2026-06-12T13:30:00Z", "status": "delivered" }
  ]
}

Troubleshooting

1. Webhook not receiving messages

Problem: messages aren't showing up in Slack / Teams.

Diagnose

# Check integration status
curl https://your-chatmox-api.com/v1/admin/integrations/{id}/status

# View recent deliveries
curl https://your-chatmox-api.com/v1/admin/integrations/{id}/deliveries?limit=20

# Send test message
curl -X POST https://your-chatmox-api.com/v1/admin/integrations/{id}/test

Likely causes

• Invalid webhook URL (copy-paste error)
• Channel doesn't exist
• Webhook app doesn't have permissions
• Webhook expired (re-create it)

Fix

1. Verify the webhook URL is correct
2. Test it manually: curl -X POST {webhook_url} -d '{"text":"test"}'
3. Re-create the webhook on the platform
4. Check platform permissions / scopes

2. Events not triggering

Problem: specific event types never send alerts.

Check

# Verify event is enabled
curl https://your-chatmox-api.com/v1/admin/integrations/{id}

# Check event thresholds
curl https://your-chatmox-api.com/v1/admin/integrations/settings

Common causes

• Event not enabled in the integration config
• Threshold too high (e.g. alert only on 20% errors, but errors are at 5%)
• Quiet hours are active

Fix

{
  "events": [
    "error_alert",      // Make sure enabled
    "performance_alert"
  ],
  "threshold_error_rate": 5  // Adjust threshold
}

3. Duplicate messages

Problem: the same alert is sent multiple times.

{
  "settings": {
    "suppress_duplicates_minutes": 15,
    "deduplicate_by": ["event_type", "provider"]
  }
}

4. Rate limit errors

Problem: getting 429 errors from the webhook platform.

{
  "rate_limiting": {
    "max_messages_per_minute": 10,
    "batch_alerts": true,
    "batch_window_seconds": 60
  }
}

Debug Logs

Enable detailed logging:

curl -X POST https://your-chatmox-api.com/v1/admin/integrations/{id}/settings \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "debug_logging": true
  }'

Then view logs:

curl https://your-chatmox-api.com/v1/admin/integrations/{id}/logs?limit=100

Best Practices

1. Start with one integration

• Test with Slack first (easiest)
• Verify alerts are working
• Then add more platforms

2. Set appropriate thresholds

{
  "error_rate": 5,           // 5% errors = alert
  "latency_ms": 2000,        // 2s latency = alert
  "cost_daily": 100          // $100/day = alert
}

3. Use quiet hours

{
  "quiet_hours": {
    "start": "18:00",
    "end": "09:00"
  }
}

4. Suppress duplicates

Prevent alert spam:set suppress_duplicates_minutes to 15-30.

5. Use mention rules

{
  "critical": "@channel",
  "warning": null,
  "info": null
}

6. Regular testing

• Test each integration monthly
• Verify webhook URLs still work
• Check delivery success rate

API Reference

Support

Need help getting an integration working?

• Email: info@chatmox.com
• Docs: docs.chatmox.io
• Or reach out via our contact page

Version 1.0 · Last updated 2026-06-12 · Status: Production Ready