Business Hours API

The Business Hours API manages organization operating hours, holiday schedules, and provides real-time availability checks. Business hours affect SLA calculations and auto-responses.

Business Hours Object

{
  id: string;                    // UUID
  organization_id: string;       // UUID of the organization
  timezone: string;              // IANA timezone (e.g., 'America/New_York')
  schedule: ScheduleItem[];      // Weekly schedule
  holidays: Holiday[];           // Holiday dates
  enabled: boolean;              // Whether business hours are active
  created_at: string;            // ISO timestamp
  updated_at: string;            // ISO timestamp
}

Schedule Item Schema

{
  day: number;      // 0-6 (Sunday = 0, Saturday = 6)
  start: string;    // Start time in "HH:MM" format (24-hour)
  end: string;      // End time in "HH:MM" format (24-hour)
}

Holiday Schema

{
  date: string;     // Date in "YYYY-MM-DD" format
  name: string;     // Holiday name
}

Get Business Hours

Retrieve the organization's business hours configuration.

Procedure: businessHours.get

Authentication: Required

Input: None

Example:

curl -X GET "https://your-domain.com/api/trpc/businessHours.get" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "organization_id": "org-uuid",
        "timezone": "America/New_York",
        "schedule": [
          { "day": 1, "start": "09:00", "end": "17:00" },
          { "day": 2, "start": "09:00", "end": "17:00" },
          { "day": 3, "start": "09:00", "end": "17:00" },
          { "day": 4, "start": "09:00", "end": "17:00" },
          { "day": 5, "start": "09:00", "end": "17:00" }
        ],
        "holidays": [
          { "date": "2024-12-25", "name": "Christmas Day" },
          { "date": "2024-01-01", "name": "New Year's Day" }
        ],
        "enabled": true,
        "created_at": "2024-01-01T00:00:00.000Z",
        "updated_at": "2024-01-15T10:30:00.000Z"
      }
    }
  }
}

Update Business Hours

Update the business hours configuration. Admin only.

Procedure: businessHours.update

Authentication: Required (Admin)

Input:

{
  timezone?: string;             // IANA timezone
  schedule?: ScheduleItem[];     // Weekly schedule
  enabled?: boolean;             // Enable/disable business hours
}

Example:

curl -X POST "https://your-domain.com/api/trpc/businessHours.update" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "timezone": "America/Los_Angeles",
      "schedule": [
        { "day": 1, "start": "08:00", "end": "18:00" },
        { "day": 2, "start": "08:00", "end": "18:00" },
        { "day": 3, "start": "08:00", "end": "18:00" },
        { "day": 4, "start": "08:00", "end": "18:00" },
        { "day": 5, "start": "08:00", "end": "18:00" }
      ],
      "enabled": true
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "timezone": "America/Los_Angeles",
        "schedule": [...],
        "enabled": true,
        "updated_at": "2024-01-15T11:00:00.000Z"
      }
    }
  }
}

Add Holiday

Add a holiday to the calendar. Admin only.

Procedure: businessHours.addHoliday

Authentication: Required (Admin)

Input:

{
  date: string;   // Date in "YYYY-MM-DD" format
  name: string;   // Holiday name
}

Example:

curl -X POST "https://your-domain.com/api/trpc/businessHours.addHoliday" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{
    "json": {
      "date": "2024-07-04",
      "name": "Independence Day"
    }
  }'

Response:

{
  "result": {
    "data": {
      "json": {
        "id": "uuid",
        "holidays": [
          { "date": "2024-07-04", "name": "Independence Day" },
          { "date": "2024-12-25", "name": "Christmas Day" }
        ],
        "updated_at": "2024-01-15T11:00:00.000Z"
      }
    }
  }
}

Remove Holiday

Remove a holiday from the calendar. Admin only.

Procedure: businessHours.removeHoliday

Authentication: Required (Admin)

Input:

{
  date: string;  // Date in "YYYY-MM-DD" format
}

Example:

curl -X POST "https://your-domain.com/api/trpc/businessHours.removeHoliday" \
  -H "Content-Type: application/json" \
  -H "Cookie: your-session-cookie" \
  -d '{"json":{"date":"2024-07-04"}}'

Response:

{
  "result": {
    "data": {
      "json": {
        "success": true
      }
    }
  }
}

Check Current Availability

Check if the organization is currently within business hours.

Procedure: businessHours.isCurrentlyOpen

Authentication: Required

Input: None

Example:

curl -X GET "https://your-domain.com/api/trpc/businessHours.isCurrentlyOpen" \
  -H "Cookie: your-session-cookie"

Response:

{
  "result": {
    "data": {
      "json": {
        "isOpen": true,
        "timezone": "America/New_York",
        "currentTime": "2024-01-15T14:30:00.000Z",
        "localTime": "09:30",
        "nextChange": {
          "type": "close",
          "time": "17:00",
          "date": "2024-01-15"
        }
      }
    }
  }
}

Response when closed:

{
  "result": {
    "data": {
      "json": {
        "isOpen": false,
        "timezone": "America/New_York",
        "currentTime": "2024-01-15T23:00:00.000Z",
        "localTime": "18:00",
        "reason": "outside_hours",
        "nextChange": {
          "type": "open",
          "time": "09:00",
          "date": "2024-01-16"
        }
      }
    }
  }
}

Closed reason values:

• outside_hours - Outside scheduled business hours
• holiday - Today is a holiday
• disabled - Business hours feature is disabled

Day Numbers

Common Timezones

Use Cases

Auto-Response Setup

// Check if currently open before sending auto-response
const { isOpen, nextChange } = await trpc.businessHours.isCurrentlyOpen.query()

if (!isOpen) {
  // Send "We're currently closed" auto-response
  const message = `Thanks for reaching out! We're currently closed and will respond when we reopen at ${nextChange.time} on ${nextChange.date}.`
}

SLA Pause During Off-Hours

Business hours automatically affect SLA calculations. When enabled is true:

• SLA timers pause outside business hours
• Holiday dates are excluded from SLA calculations

Error Codes