Skip to main content

​
Get Calendar Settings

curl https://your-domain.com/api/get-calendar-settings.php
Retrieves calendar configuration including timezone, business hours, and booking constraints.

​
Response

​
timezone
string
PHP timezone identifier (e.g., "America/Bogota", "UTC")Default: "America/Bogota"
​
default_duration_minutes
integer
Default meeting duration in minutesDefault: 60
​
max_events_per_day
integer
Maximum number of events that can be booked per dayDefault: 10
​
min_advance_hours
integer
Minimum hours in advance required for bookingDefault: 1
​
business_hours
object
Operating hours for each day of the week
​
monday
object
​
enabled
boolean
Whether appointments are available on Monday
​
start
string
Opening time in 24-hour format (e.g., "09:00")
​
end
string
Closing time in 24-hour format (e.g., "18:00")
​
tuesday
object
Same structure as Monday
​
wednesday
object
Same structure as Monday
​
thursday
object
Same structure as Monday
​
friday
object
Same structure as Monday
​
saturday
object
Same structure as Monday
​
sunday
object
Same structure as Monday

​
Success Response Example

{
  "timezone": "America/Bogota",
  "default_duration_minutes": 60,
  "max_events_per_day": 10,
  "min_advance_hours": 1,
  "business_hours": {
    "monday": {
      "enabled": true,
      "start": "09:00",
      "end": "18:00"
    },
    "tuesday": {
      "enabled": true,
      "start": "09:00",
      "end": "18:00"
    },
    "wednesday": {
      "enabled": true,
      "start": "09:00",
      "end": "18:00"
    },
    "thursday": {
      "enabled": true,
      "start": "09:00",
      "end": "18:00"
    },
    "friday": {
      "enabled": true,
      "start": "09:00",
      "end": "18:00"
    },
    "saturday": {
      "enabled": true,
      "start": "10:00",
      "end": "14:00"
    },
    "sunday": {
      "enabled": false,
      "start": "09:00",
      "end": "18:00"
    }
  }
}

​
Save Calendar Settings

curl -X POST https://your-domain.com/api/save-calendar-settings.php \
  -H "Content-Type: application/json" \
  -d '{
    "timezone": "America/New_York",
    "default_duration_minutes": 30,
    "max_events_per_day": 8,
    "min_advance_hours": 2,
    "business_hours": {
      "monday": {
        "enabled": true,
        "start": "08:00",
        "end": "17:00"
      }
    }
  }'
Updates calendar settings. All fields are optional - only provided fields will be updated.

​
Request

​
timezone
string
Valid PHP timezone identifier (validated against DateTimeZone::listIdentifiers())
​
default_duration_minutes
integer
Default meeting duration in minutes (must be > 0)
​
max_events_per_day
integer
Maximum bookable events per day (must be > 0)
​
min_advance_hours
integer
Minimum advance notice required in hours (must be >= 0)
​
business_hours
object
Weekly schedule configuration
​
monday
object
​
enabled
boolean
Whether appointments are available
​
start
string
Opening time in HH:MM format (24-hour)
​
end
string
Closing time in HH:MM format (must be after start time)
​
tuesday
object
Same structure as Monday
​
wednesday
object
Same structure as Monday
​
thursday
object
Same structure as Monday
​
friday
object
Same structure as Monday
​
saturday
object
Same structure as Monday
​
sunday
object
Same structure as Monday

​
Validation Rules

Duration: Must be greater than 0 minutes
Max Events: Must be greater than 0
Min Advance: Must be 0 or positive
Time Format: Must be HH:MM (24-hour format)
Time Range: End time must be after start time
Business Days: At least one day must be enabled
Timezone: Must be a valid PHP timezone identifier

​
Response

​
success
boolean
Indicates if settings were saved successfully
​
message
string
Confirmation message
​
error
string
Validation or system error message (only present on failure)

​
Success Response Example

{
  "success": true,
  "message": "Configuración guardada exitosamente"
}

​
Error Response Examples

Validation Error
{
  "error": "Monday: la hora de fin debe ser posterior a la hora de inicio"
}
Multiple Validation Errors
{
  "error": "La duración debe ser mayor a 0 minutos, Monday: formato de hora inicio inválido (debe ser HH:MM)"
}
No Business Days
{
  "error": "Debe haber al menos un día de la semana abierto"
}
Invalid Timezone
{
  "error": "Zona horaria inválida"
}

​
Error Handling

Status CodeDescription
200Settings saved successfully
400Validation error (check error message for details)
405Method not allowed (POST required for save)
500Internal server error

​
Implementation Details

The save endpoint:
  1. Validates all numeric constraints
  2. Validates time formats using App\Helpers\TimeValidator
  3. Ensures at least one business day is enabled
  4. Uses database transactions for atomicity
  5. Stores business hours as JSON per day
  6. Logs changes for audit purposes
Source:
  • GET: api/get-calendar-settings.php:10-62
  • POST: api/save-calendar-settings.php:28-145

​
Notes

These settings only take effect when calendar integration is enabled in the main bot settings (calendarEnabled: true).
Changing business hours does not affect already-booked appointments. Only new bookings will respect the updated schedule.

Build docs developers (and LLMs) love

Get started for freeTalk to us