API Reference

Integrate BossBot into your workflows. All endpoints require authentication via API key.

Authentication

Include your API key in every request header:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Get your API key from Settings → API Keys in your dashboard.

Incoming Webhooks

BossBot sends real-time events to your webhook URL. Configure in Settings → Webhook Integration.

All webhooks include an X-BossBot-Signature header (HMAC-SHA256) for verification.

Rate Limits

Leads

List Leads

Returns paginated leads with filters.

Get Lead Detail

Update Lead Status

{
  "status": "qualified"
}

Bulk Change Status

{
  "lead_ids": [1, 2, 3, 4, 5],
  "status": "contacted"
}

Bulk Add Tag

{
  "lead_ids": [1, 2, 3],
  "tag": "vip",
  "action": "add"
}

Messages

Send Manual Reply

{
  "text": "Hi! Thanks for reaching out."
}

Bulk Send Message

{
  "lead_ids": [1, 2, 3],
  "message": "Hi ! Special offer for you."
}

Appointments

Create Appointment

{
  "datetime": "2026-05-15 14:00",
  "service": "Consultation"
}

Campaigns

List Campaigns

Create Campaign

{
  "name": "April Promotion",
  "filters": {"status": "qualified", "channel": "whatsapp"},
  "message": "Hi ! We have something special for you."
}

Preview Audience

{
  "filters": {"status": "qualified"}
}

// Response:
{
  "ok": true,
  "audience_count": 42,
  "sample": [{"name": "John", "phone": "+1..."}]
}

Send Campaign

Campaign Stats

Analytics

Overview KPIs

Returns: total leads, conversion rate, escalation rate, bot resolution %, average rating.

Conversion Funnel

SLA Metrics

SLA Dashboard

Returns first response time, resolution time, SLA compliance %, queue depth, agent scores.

// Response:
{
  "first_response": {
    "avg_seconds": 12.5,
    "compliance_pct": 95.2,
    "target_seconds": 300
  },
  "resolution": {
    "avg_seconds": 43200,
    "compliance_pct": 87.0,
    "target_seconds": 86400
  },
  "queue": {
    "open_leads": 15,
    "waiting_human": 3,
    "escalated_open": 1
  },
  "agents": [
    {"agent": "Maria", "total": 45, "resolved": 38, "resolution_rate": 84.4}
  ]
}

Webhook Events

Configure webhook URL in Settings. Events are signed with HMAC-SHA256.

Webhook Signature Verification

Every webhook includes an X-BossBot-Signature header. Verify it to ensure the request is authentic.

Python

import hmac, hashlib

def verify_webhook(payload_bytes, signature, secret):
    expected = hmac.new(
        secret.encode(), payload_bytes, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

# In your Flask/Django handler:
sig = request.headers.get("X-BossBot-Signature", "")
if not verify_webhook(request.data, sig, WEBHOOK_SECRET):
    abort(401)

Node.js

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signature)
  );
}

// In your Express handler:
app.post('/webhook', (req, res) => {
  const sig = req.headers['x-bossbot-signature'];
  if (!verifyWebhook(req.rawBody, sig, WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  // Process event...
});

cURL (test)

# Generate a test signature:
echo -n '{"event":"test"}' | openssl dgst -sha256 -hmac "your-secret"

# Send with signature:
curl -X POST https://your-server.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-BossBot-Signature: abc123..." \
  -d '{"event":"test"}'

Zapier / Make / n8n

Use BossBot webhooks with any automation platform:

1. Go to Settings → Webhook Integration
2. Paste your Zapier/Make webhook URL
3. Select events to subscribe to
4. Click "Send Test" to verify connection

Example Zapier zaps:

• New Lead → Google Sheets: Auto-log every lead
• Appointment Booked → Slack: Notify your team
• Lead Escalated → Email: Alert the manager