Communication Queue API - Complete Guide 🚀

Status: ✅ Newly Implemented
Date: October 26, 2025

🎯 Overview

The Communication Queue API provides HTTP endpoints for monitoring, managing, and controlling the communication queue system. These endpoints enable operations teams, administrators, and frontend applications to interact with the queue effectively.

What Was Missing Before

❌ No HTTP access to queue - Queue was invisible to external systems
❌ No monitoring capabilities - Couldn't see pending/failed jobs
❌ No manual intervention - Couldn't retry failed jobs
❌ No operational dashboards - Frontend couldn't display queue status

What's Available Now

✅ Full HTTP API - RESTful endpoints for all queue operations
✅ Real-time monitoring - Stats, pending jobs, failed jobs
✅ Manual intervention - Retry, cancel, delete jobs
✅ Debugging tools - Inspect specific jobs and their history
✅ Admin UI ready - Frontend can now build dashboards

📍 Base Path

/api/businesses/:businessId/communication-queue/

All endpoints require:

Valid business ID in the URL
Authentication token (Bearer)
Appropriate permissions (role-based)

🔗 API Endpoints

1. Get Queue Statistics ⭐

Essential for monitoring dashboard

GET /api/businesses/:businessId/communication-queue/stats
Authorization: Bearer {token}

Response:

{
  "total": 150,
  "pending": 45,
  "processing": 5,
  "completed": 90,
  "failed": 10,
  "cancelled": 0,
  "oldestPending": "2025-10-26T10:30:00Z",
  "avgProcessingTimeSeconds": 2.5
}

Use Cases:

Real-time monitoring dashboard
Alert if pending > threshold
Track processing performance
Capacity planning

Example curl:

curl -X GET "http://localhost:3000/api/businesses/550e8400-e29b-41d4-a716-446655440000/communication-queue/stats" \
  -H "Authorization: Bearer your-jwt-token"

2. List Pending Jobs 📋

See what's waiting to be processed

GET /api/businesses/:businessId/communication-queue/pending?limit=50
Authorization: Bearer {token}

Query Parameters:

limit (optional): Maximum number of jobs to return (default: 10)

Response:

[
  {
    "id": "job-uuid-1",
    "communicationId": "comm-uuid-1",
    "status": "pending",
    "priority": "high",
    "scheduledAt": "2025-10-26T11:00:00Z",
    "attempts": 0,
    "maxAttempts": 3,
    "payload": "{...}",
    "createdAt": "2025-10-26T10:55:00Z"
  },
  {
    "id": "job-uuid-2",
    "communicationId": "comm-uuid-2",
    "status": "pending",
    "priority": "normal",
    "scheduledAt": "2025-10-26T11:05:00Z",
    "attempts": 0,
    "maxAttempts": 3,
    "payload": "{...}",
    "createdAt": "2025-10-26T10:58:00Z"
  }
]

Use Cases:

Monitor queue backlog
Check if specific communication is pending
Verify scheduled send times
Debug queue delays

Example curl:

curl -X GET "http://localhost:3000/api/businesses/550e8400-e29b-41d4-a716-446655440000/communication-queue/pending?limit=20" \
  -H "Authorization: Bearer your-jwt-token"

3. List Failed Jobs 🚨

Critical for operations - see what's broken

GET /api/businesses/:businessId/communication-queue/failed?limit=50
Authorization: Bearer {token}

Query Parameters:

limit (optional): Maximum number of jobs to return (default: 50)

Response:

[
  {
    "id": "job-uuid-3",
    "communicationId": "comm-uuid-3",
    "status": "failed",
    "priority": "normal",
    "scheduledAt": "2025-10-26T09:00:00Z",
    "attempts": 3,
    "maxAttempts": 3,
    "lastError": "SendGrid API error: Invalid email address",
    "payload": "{...}",
    "createdAt": "2025-10-26T08:55:00Z",
    "updatedAt": "2025-10-26T09:15:00Z"
  }
]

Use Cases:

Operations monitoring - Alert on failures
Error analysis - Group by error type
Manual recovery - Identify jobs to retry
Service health - Track failure rate

Example curl:

curl -X GET "http://localhost:3000/api/businesses/550e8400-e29b-41d4-a716-446655440000/communication-queue/failed?limit=10" \
  -H "Authorization: Bearer your-jwt-token"

4. Get Specific Job 🔍

Inspect a single job in detail

GET /api/businesses/:businessId/communication-queue/:id
Authorization: Bearer {token}

Response:

{
  "id": "job-uuid-1",
  "communicationId": "comm-uuid-1",
  "status": "completed",
  "priority": "high",
  "scheduledAt": "2025-10-26T10:00:00Z",
  "startedAt": "2025-10-26T10:00:15Z",
  "completedAt": "2025-10-26T10:00:18Z",
  "attempts": 1,
  "maxAttempts": 3,
  "payload": "{\"channel\":\"email\",\"recipientContact\":\"user@example.com\",...}",
  "createdAt": "2025-10-26T09:55:00Z",
  "updatedAt": "2025-10-26T10:00:18Z"
}

Use Cases:

Debug specific job failures
Audit trail investigation
Performance analysis (timing)
Payload inspection

Example curl:

curl -X GET "http://localhost:3000/api/businesses/550e8400-e29b-41d4-a716-446655440000/communication-queue/job-uuid-1" \
  -H "Authorization: Bearer your-jwt-token"

5. Retry Failed Job 🔄

Manually retry a failed or cancelled job

POST /api/businesses/:businessId/communication-queue/:id/retry
Authorization: Bearer {token}

Response:

{
  "success": true,
  "message": "Job successfully queued for retry",
  "job": {
    "id": "job-uuid-3",
    "status": "pending",
    "attempts": 0,
    "scheduledAt": "2025-10-26T11:30:00Z",
    ...
  }
}

Behavior:

✅ Resets attempts to 0
✅ Sets status to "pending"
✅ Schedules immediately
✅ Clears error messages
✅ Works on "failed" and "cancelled" jobs
❌ Cannot retry "completed" or "processing" jobs

Use Cases:

Fix and retry - After fixing API credentials
Transient errors - Retry after temporary outage
Bulk retry - Retry multiple failed jobs
Manual recovery - Operations intervention

Example curl:

curl -X POST "http://localhost:3000/api/businesses/550e8400-e29b-41d4-a716-446655440000/communication-queue/job-uuid-3/retry" \
  -H "Authorization: Bearer your-jwt-token"

Error Response (if can't retry):

{
  "success": false,
  "message": "Job job-uuid-3 cannot be retried (current status: completed)"
}

6. Cancel Pending Job ⛔

Stop a scheduled job from being sent

POST /api/businesses/:businessId/communication-queue/:id/cancel
Authorization: Bearer {token}

Response:

{
  "success": true,
  "message": "Job cancelled successfully",
  "job": {
    "id": "job-uuid-4",
    "status": "cancelled",
    "updatedAt": "2025-10-26T11:35:00Z",
    ...
  }
}

Behavior:

✅ Sets status to "cancelled"
✅ Prevents job from processing
✅ Works on "pending" and "processing" jobs
❌ Cannot cancel "completed" or "failed" jobs

Use Cases:

Stop scheduled sends - Cancel future communications
Fix mistakes - Cancel before sending wrong message
Compliance - Cancel to customer who opted out
Emergency stop - Prevent problematic communication

Example curl:

curl -X POST "http://localhost:3000/api/businesses/550e8400-e29b-41d4-a716-446655440000/communication-queue/job-uuid-4/cancel" \
  -H "Authorization: Bearer your-jwt-token"

7. Delete Job (Admin Only) 🗑️

Permanently remove a job from the queue

DELETE /api/businesses/:businessId/communication-queue/:id
Authorization: Bearer {token}

Response:

HTTP 204 No Content

⚠️ WARNING: This is a destructive operation!

Use Cases:

Cleanup - Remove old failed jobs
Data retention - Comply with data policies
Database hygiene - Prevent queue table bloat
Admin operations - Remove stuck/corrupted jobs

Best Practice: Use with caution! Consider archiving instead.

Example curl:

curl -X DELETE "http://localhost:3000/api/businesses/550e8400-e29b-41d4-a716-446655440000/communication-queue/job-uuid-5" \
  -H "Authorization: Bearer your-jwt-token"

8. Get Jobs by Communication 📄

See all queue attempts for a specific communication

GET /api/businesses/:businessId/communication-queue/by-communication/:communicationId
Authorization: Bearer {token}

Response:

[
  {
    "id": "job-uuid-6",
    "communicationId": "comm-uuid-1",
    "status": "failed",
    "attempts": 1,
    "lastError": "Connection timeout",
    "scheduledAt": "2025-10-26T09:00:00Z",
    ...
  },
  {
    "id": "job-uuid-7",
    "communicationId": "comm-uuid-1",
    "status": "failed",
    "attempts": 2,
    "lastError": "Connection timeout",
    "scheduledAt": "2025-10-26T09:05:00Z",
    ...
  },
  {
    "id": "job-uuid-8",
    "communicationId": "comm-uuid-1",
    "status": "completed",
    "attempts": 3,
    "scheduledAt": "2025-10-26T09:20:00Z",
    ...
  }
]

Use Cases:

Retry history - See all attempts for one communication
Debugging - Understand retry behavior
Audit trail - Complete send history
Performance analysis - Time between retries

Example curl:

curl -X GET "http://localhost:3000/api/businesses/550e8400-e29b-41d4-a716-446655440000/communication-queue/by-communication/comm-uuid-1" \
  -H "Authorization: Bearer your-jwt-token"

9. Trigger Manual Processing ⚡

Force immediate queue processing (testing/debugging)

POST /api/businesses/:businessId/communication-queue/process-now
Authorization: Bearer {token}

Response:

{
  "success": true,
  "message": "Queue processing completed"
}

Behavior:

Immediately runs processQueue() method
Normally runs every 30 seconds via cron
Useful for testing or forcing immediate send

Use Cases:

Testing - Verify queue processing works
Debugging - Trigger processing manually
Emergency - Force sends without waiting for cron
Development - Test integration quickly

⚠️ Note: Admin only! Use sparingly in production.

Example curl:

curl -X POST "http://localhost:3000/api/businesses/550e8400-e29b-41d4-a716-446655440000/communication-queue/process-now" \
  -H "Authorization: Bearer your-jwt-token"

📊 Frontend Integration Examples

React Hook for Queue Stats

// useQueueStats.ts
import { useEffect, useState } from 'react';
import { api } from '@/lib/api';

export function useQueueStats(businessId: string, refreshInterval = 30000) {
  const [stats, setStats] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    const fetchStats = async () => {
      try {
        const data = await api(`/businesses/${businessId}/communication-queue/stats`);
        setStats(data);
      } catch (error) {
        console.error('Failed to fetch queue stats', error);
      } finally {
        setLoading(false);
      }
    };

    fetchStats();
    const interval = setInterval(fetchStats, refreshInterval);

    return () => clearInterval(interval);
  }, [businessId, refreshInterval]);

  return { stats, loading };
}

Dashboard Component

// QueueDashboard.tsx
export function QueueDashboard({ businessId }: Props) {
  const { stats, loading } = useQueueStats(businessId);

  if (loading) return <Skeleton />;

  return (
    <Card>
      <CardHeader>
        <CardTitle>Communication Queue Status</CardTitle>
      </CardHeader>
      <CardContent>
        <div className="grid grid-cols-3 gap-4">
          <StatCard label="Pending" value={stats.pending} color="blue" />
          <StatCard label="Processing" value={stats.processing} color="yellow" />
          <StatCard label="Failed" value={stats.failed} color="red" />
        </div>

        {stats.failed > 0 && (
          <Alert variant="destructive" className="mt-4">
            <AlertCircle className="h-4 w-4" />
            <AlertTitle>Failed Jobs Detected</AlertTitle>
            <AlertDescription>
              {stats.failed} jobs have failed. <Link to="/queue/failed">View details</Link>
            </AlertDescription>
          </Alert>
        )}
      </CardContent>
    </Card>
  );
}

Retry Failed Job Action

// retryJob.ts
export async function retryJob(businessId: string, jobId: string) {
  const response = await api(`/businesses/${businessId}/communication-queue/${jobId}/retry`, {
    method: 'POST',
  });

  if (response.success) {
    toast({
      title: 'Job Queued',
      description: 'Job has been queued for retry',
    });
  } else {
    toast({
      title: 'Retry Failed',
      description: response.message,
      variant: 'destructive',
    });
  }

  return response;
}

🔐 Security & Permissions

Recommended Permission Structure

// Permissions for queue endpoints
export const QueuePermissions = {
  viewStats: {
    action: 'view',
    subject: 'CommunicationQueue',
  },
  viewJobs: {
    action: 'viewJobs',
    subject: 'CommunicationQueue',
  },
  retryJobs: {
    action: 'retry',
    subject: 'CommunicationQueue',
  },
  cancelJobs: {
    action: 'cancel',
    subject: 'CommunicationQueue',
  },
  deleteJobs: {
    action: 'delete',
    subject: 'CommunicationQueue', // Admin only
  },
  processManually: {
    action: 'process',
    subject: 'CommunicationQueue', // Admin only
  },
};

Role-Based Access

Role	Stats	View Jobs	Retry	Cancel	Delete	Manual Process
Admin	✅	✅	✅	✅	✅	✅
Manager	✅	✅	✅	✅	❌	❌
Support	✅	✅	✅	❌	❌	❌
User	✅	❌	❌	❌	❌	❌

📈 Monitoring & Alerting

Key Metrics to Track

Queue Size - Alert if pending > 100
Failed Jobs - Alert if failed > 10
Processing Time - Alert if avgProcessingTime > 10s
Oldest Pending - Alert if job pending > 5 minutes

Example Monitoring Dashboard Queries

// Check queue health
const isHealthy = 
  stats.pending < 100 &&
  stats.failed < 10 &&
  stats.processing < 20;

// Calculate failure rate
const failureRate = (stats.failed / stats.total) * 100;

// Alert if failure rate > 5%
if (failureRate > 5) {
  sendAlert('High failure rate in communication queue');
}

🎯 Best Practices

1. Polling Frequency

Dashboard stats: 30 seconds
Failed jobs list: 60 seconds
Individual job status: On-demand only

2. Retry Strategy

Check error message before retrying
Fix underlying issues first (e.g., API keys)
Don't bulk retry without investigation
Consider rate limits

3. Cancellation

Verify job details before cancelling
Log cancellation reason
Notify relevant parties
Cannot undo cancellation (unless you retry)

4. Deletion

Only delete very old failed jobs
Archive important data first
Admin-only operation
Consider data retention policies

🔧 Troubleshooting

Problem: "Queue is growing"

# Check stats
GET /communication-queue/stats
→ If pending > 100, investigate

# Check oldest pending job
→ Look at oldestPending timestamp
→ If > 5 minutes, queue is stuck

# Trigger manual processing (admin)
POST /communication-queue/process-now

Problem: "Many failed jobs"

# Get failed jobs
GET /communication-queue/failed?limit=50

# Check error messages
→ Group by lastError
→ Identify common causes (e.g., "Invalid API key")

# Fix underlying issue
→ Update credentials, fix config, etc.

# Retry failed jobs
POST /communication-queue/:id/retry (for each)

Problem: "Job stuck in processing"

# Get specific job
GET /communication-queue/:id

# Check startedAt timestamp
→ If processing > 10 minutes, likely stuck

# Cancel and retry
POST /communication-queue/:id/cancel
POST /communication-queue/:id/retry

🚀 What's Next

Immediate Improvements

✅ Add webhooks for queue events
✅ Bulk operations (retry all failed)
✅ Filtering (by status, priority, date range)
✅ Pagination for large result sets
✅ Export failed jobs as CSV

Future Enhancements

Real-time updates (WebSocket)
Queue analytics (charts, trends)
Scheduled reports (daily email with stats)
Auto-recovery (intelligent retry)
ML-based failure prediction

📝 Summary

What You Can Do Now

✅ Monitor - See queue status in real-time
✅ Debug - Inspect failed jobs and errors
✅ Intervene - Manually retry or cancel jobs
✅ Maintain - Clean up old jobs
✅ Build UI - Frontend dashboards now possible

Impact

🎯 Visibility - No more "black box" queue
🔧 Control - Operations can manage queue
📊 Insights - Data-driven decisions
🚨 Reliability - Faster issue resolution
👥 Collaboration - Shared understanding of system state

Congratulations! The Communication Queue is now fully accessible via REST API! 🎉

🎯 Overview​

What Was Missing Before​

What's Available Now​

📍 Base Path​

🔗 API Endpoints​

1. Get Queue Statistics ⭐​

2. List Pending Jobs 📋​

3. List Failed Jobs 🚨​

4. Get Specific Job 🔍​

5. Retry Failed Job 🔄​

6. Cancel Pending Job ⛔​

7. Delete Job (Admin Only) 🗑️​

8. Get Jobs by Communication 📄​

9. Trigger Manual Processing ⚡​

📊 Frontend Integration Examples​

React Hook for Queue Stats​

Dashboard Component​

Retry Failed Job Action​

🔐 Security & Permissions​

Recommended Permission Structure​

Role-Based Access​

📈 Monitoring & Alerting​

Key Metrics to Track​

Example Monitoring Dashboard Queries​

🎯 Best Practices​

1. Polling Frequency​

2. Retry Strategy​

3. Cancellation​

4. Deletion​

🔧 Troubleshooting​

Problem: "Queue is growing"​

Problem: "Many failed jobs"​

Problem: "Job stuck in processing"​

🚀 What's Next​

Immediate Improvements​

Future Enhancements​

📝 Summary​

What You Can Do Now​

Impact​

🎯 Overview

What Was Missing Before

What's Available Now

📍 Base Path

🔗 API Endpoints

1. Get Queue Statistics ⭐

2. List Pending Jobs 📋

3. List Failed Jobs 🚨

4. Get Specific Job 🔍

5. Retry Failed Job 🔄

6. Cancel Pending Job ⛔

7. Delete Job (Admin Only) 🗑️

8. Get Jobs by Communication 📄

9. Trigger Manual Processing ⚡

📊 Frontend Integration Examples

React Hook for Queue Stats

Dashboard Component

Retry Failed Job Action

🔐 Security & Permissions

Recommended Permission Structure

Role-Based Access

📈 Monitoring & Alerting

Key Metrics to Track

Example Monitoring Dashboard Queries

🎯 Best Practices

1. Polling Frequency

2. Retry Strategy

3. Cancellation

4. Deletion

🔧 Troubleshooting

Problem: "Queue is growing"

Problem: "Many failed jobs"

Problem: "Job stuck in processing"

🚀 What's Next

Immediate Improvements

Future Enhancements

📝 Summary

What You Can Do Now

Impact