Skip to content

Support APIs Overview

Complete documentation for the CyferWall Engage Backend support system APIs, covering both customer-facing and internal staff endpoints.

🎯 API Categories

Customer APIs

Public endpoints that customers can use to manage their support cases without authentication.

Internal APIs

Staff-only endpoints for case management, requiring internal authentication.

Notification Integration

All APIs automatically trigger appropriate notifications to customers, staff, and external systems.

🚀 Customer APIs

Create Support Case

Create a new support case with automatic notifications.

Endpoint: POST /api/support/case

Authentication: None required

// Request
{
  "name": "John Doe",
  "email": "john@example.com", 
  "organization": "Acme Corp",
  "phone": "+1234567890",
  "customerType": "BUSINESS", // FREE, BUSINESS, ENTERPRISE
  "issueType": "TECHNICAL",   // TECHNICAL, BILLING, GENERAL
  "urgency": "HIGH",          // LOW, MEDIUM, HIGH, CRITICAL
  "clientOrProjectName": "My Project",
  "subject": "Unable to access dashboard",
  "message": "Detailed description of the issue..."
}

// Response
{
  "success": true,
  "caseNumber": "CW-2025-001",
  "message": "Support case created successfully",
  "estimatedResolution": "2025-01-29T10:00:00Z"
}

Notifications Triggered: - ✅ Customer: Case received confirmation - ✅ Staff: New case assignment - ✅ Operations: Case metrics update

Check Case Status

Check the current status of a support case.

Endpoint: POST /api/support/case/status

// Request
{
  "caseNumber": "CW-2025-001"
}

// Response
{
  "success": true,
  "case": {
    "caseNumber": "CW-2025-001",
    "status": "IN_PROGRESS",
    "urgency": "HIGH",
    "createdAt": "2025-01-27T10:00:00Z",
    "lastUpdated": "2025-01-27T14:30:00Z",
    "estimatedResolution": "2025-01-29T10:00:00Z"
  },
  "updates": [
    {
      "timestamp": "2025-01-27T14:30:00Z",
      "message": "Case assigned to technical team",
      "isInternal": false
    }
  ]
}

Escalate Case

Request escalation of an existing support case.

Endpoint: POST /api/support/case/escalate

// Request
{
  "caseNumber": "CW-2025-001",
  "reason": "No response for 24 hours",
  "newUrgency": "CRITICAL" // Optional
}

// Response  
{
  "success": true,
  "message": "Case escalated successfully",
  "caseNumber": "CW-2025-001",
  "newUrgency": "CRITICAL"
}

Notifications Triggered: - ✅ Customer: Escalation confirmation - ✅ Staff: Escalation alert - ✅ Management: High priority case alert

Cancel Case

Cancel an existing support case.

Endpoint: POST /api/support/case/cancel

// Request
{
  "caseNumber": "CW-2025-001",
  "reason": "Issue resolved independently"
}

// Response
{
  "success": true,
  "message": "Case cancelled successfully",
  "caseNumber": "CW-2025-001"
}

Notifications Triggered: - ✅ Customer: Cancellation confirmation - ✅ Staff: Case closure notification

🔒 Internal APIs

Authentication Required

All internal APIs require staff authentication. Implementation details TBD.

List Support Cases

Get a filtered list of all support cases with pagination.

Endpoint: GET /api/internal/support/cases

Authentication: Staff token required

// Query Parameters
{
  "status": "OPEN",           // Optional filter
  "urgency": "HIGH",          // Optional filter  
  "customerType": "BUSINESS", // Optional filter
  "assignedTo": "staff-id",   // Optional filter
  "page": 1,                  // Default: 1
  "limit": 20,               // Default: 20
  "sortBy": "createdAt",     // Default: createdAt
  "sortOrder": "desc"        // Default: desc
}

// Response
{
  "success": true,
  "cases": [
    {
      "caseNumber": "CW-2025-001",
      "customerName": "John Doe",
      "customerEmail": "john@example.com",
      "status": "IN_PROGRESS",
      "urgency": "HIGH",
      "issueType": "TECHNICAL",
      "assignedTo": {
        "id": "staff-123",
        "name": "Jane Smith"
      },
      "createdAt": "2025-01-27T10:00:00Z",
      "lastActivity": "2025-01-27T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "pages": 8
  }
}

Get Case Details

Get complete details for a specific case.

Endpoint: GET /api/internal/support/case/:caseNumber

// Response
{
  "success": true,
  "case": {
    "caseNumber": "CW-2025-001",
    "customerInfo": {
      "name": "John Doe",
      "email": "john@example.com",
      "organization": "Acme Corp",
      "phone": "+1234567890",
      "customerType": "BUSINESS"
    },
    "caseDetails": {
      "subject": "Unable to access dashboard",
      "message": "Detailed description...",
      "issueType": "TECHNICAL",
      "urgency": "HIGH",
      "status": "IN_PROGRESS",
      "priorityScore": 85
    },
    "assignment": {
      "assignedTo": "staff-123",
      "assignedAt": "2025-01-27T11:00:00Z",
      "department": "Technical Support"
    },
    "timeline": {
      "createdAt": "2025-01-27T10:00:00Z",
      "firstResponse": "2025-01-27T11:30:00Z",
      "lastActivity": "2025-01-27T14:30:00Z",
      "estimatedResolution": "2025-01-29T10:00:00Z"
    }
  },
  "updates": [...],
  "escalations": [...],
  "attachments": [...]
}

Update Case

Add an update to a support case.

Endpoint: POST /api/internal/support/case/:caseNumber/update

// Request
{
  "message": "Investigated the issue, found root cause in authentication module",
  "isInternal": false,        // Whether visible to customer
  "statusChange": "IN_PROGRESS", // Optional status update
  "attachments": []           // Optional file attachments
}

Notifications Triggered: - ✅ Customer: Case update (if not internal) - ✅ Staff: Internal update logs

Assign Case

Assign a case to a staff member.

Endpoint: PUT /api/internal/support/case/:caseNumber/assign

// Request
{
  "staffId": "staff-456",
  "department": "Technical Support",
  "notes": "Reassigning to senior engineer"
}

Notifications Triggered: - ✅ New assignee: Case assignment - ✅ Previous assignee: Case reassignment
- ✅ Customer: New contact information

🔔 Notification Integration

All support APIs are fully integrated with the notification system:

Automatic Notifications

graph LR
    A[API Call] --> B[Controller Logic]
    B --> C[Database Update]
    C --> D[Notification Trigger]
    D --> E[Template Selection]
    E --> F[Multi-channel Delivery]

    F --> G[Email]
    F --> H[SMS]
    F --> I[Webhook]

Notification Channels

Event Customer Email Staff Email SMS Webhook
Case Created ✅ ✅ ⚠️ High urgency only ✅
Case Updated ✅ ✅ ❌ ✅
Case Escalated ✅ ✅ ✅ ✅
Case Assigned ❌ ✅ ❌ ✅
Case Cancelled ✅ ✅ ❌ ✅

Integration Example

// In createSupportCaseController
import { notifications } from '@/util/notifications/ultra-simple'

export const createSupportCaseController = async (req, res) => {
  // 1. Create case in database
  const supportCase = await db.supportCase.create({ data: caseData })

  // 2. Send notifications (automatically handled)
  await notifications.email('case-received-customer', supportCase.email, {
    caseNumber: supportCase.caseNumber,
    customerName: supportCase.name,
    issueType: supportCase.issueType
  })

  await notifications.email('case-assigned-staff', 'support@cyferwall.com', {
    caseNumber: supportCase.caseNumber,
    customerName: supportCase.name,
    urgency: supportCase.urgency
  })

  // 3. Return response
  res.json({ success: true, caseNumber: supportCase.caseNumber })
}

📊 API Status & Monitoring

Health Check

Endpoint: GET /health

// Response
{
  "status": "healthy",
  "timestamp": "2025-01-27T15:30:00Z",
  "service": "engage-backend",
  "version": "1.0.0",
  "components": {
    "database": "healthy",
    "notifications": "healthy",
    "templates": "healthy"
  }
}

Notification Status

Endpoint: GET /api/internal/notifications/status

Check the status of recent notifications for debugging.

🚀 Usage Examples

Customer Support Widget

// Frontend integration example
const createCase = async (caseData) => {
  const response = await fetch('/api/support/case', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(caseData)
  })

  const result = await response.json()
  if (result.success) {
    showSuccess(`Case ${result.caseNumber} created! You'll receive updates via email.`)
  }
}

Internal Dashboard

// Staff dashboard integration
const loadCases = async (filters) => {
  const query = new URLSearchParams(filters)
  const response = await fetch(`/api/internal/support/cases?${query}`, {
    headers: { 'Authorization': `Bearer ${staffToken}` }
  })

  const { cases, pagination } = await response.json()
  renderCasesList(cases, pagination)
}

🔧 Error Handling

All APIs return consistent error responses:

// Error Response Format
{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE",
  "details": {
    // Additional error context
  }
}

Common HTTP status codes: - 200 - Success - 400 - Bad Request (validation errors) - 401 - Unauthorized (missing/invalid auth) - 404 - Not Found (case doesn't exist) - 500 - Internal Server Error

🚀 Next Steps

  1. Customer API Examples - Detailed customer API documentation
  2. Internal API Examples - Staff API implementation guide
  3. Case Management - Complete case lifecycle management
  4. Integration Testing - Test your API integration

Ready to integrate? Start with the Customer APIs →