Booking integration attributes

These attributes configure how your AI Employee connects to an external booking system, covering the API path, request schemas, authentication headers, and the availability checking pipeline. They are hidden from the standard Attributes page and only appear when the Show Hidden toggle is enabled.

Quick reference

Booking configuration

project_attributes_setting_booking_type

This attribute defines which integration path the AI Employee uses to submit booking requests and process results.

Possible values:

• default — Uses the built-in default booking logic. For restaurant booking this includes a new schema-based approach and an optional legacy fallback path.
• endpoint — Submits the booking payload to your configured booking URL via HTTP request.
• intercom — Uses the Intercom actor-event booking branch.
• project — Uses a project-side system event (book_slot) for booking execution.
• custom — Reserved for advanced custom setups; currently follows the endpoint-style HTTP branch unless extended by project-side logic.

::: 🗒️ NOTE

Match this value to your actual booking backend. Required prerequisites differ per type — for example, endpoint requires project_attributes_setting_booking_url and project_attributes_setting_booking_payload_schema_template, while intercom and project use their respective actor or system event flows. :::

project_attributes_setting_booking_fallback_processing_type

This attribute controls what the AI Employee does when a booking attempt fails.

Possible values:

• default — Keeps the built-in fallback behavior. In default restaurant booking, this allows the runtime to retry through the legacy restaurant approach when an attempt in the new approach fails.
• custom — Emits a process_booking_fallback_custom system event with payload metadata and skips the built-in fallback branch entirely.

::: ⚠️ CAUTION

Use custom only if your project has a listener configured to consume the process_booking_fallback_custom event. Without that handler, failed bookings will not have a fallback path and may silently drop. :::

project_attributes_setting_booking_email

This attribute defines the base email address used when generating booking payloads. The runtime derives a booking-specific address from this base by combining the local part, the user's phone number, and the domain.

Set this to a dedicated booking mailbox on your own domain so provider-side booking requests remain traceable.

Example value: [email protected]

::: 🗒️ NOTE

If this field is empty or invalid, the runtime falls back to a generic default email format and still derives booking-specific addresses from available phone data. On retry, a random suffix is appended to the local part to avoid duplicate-email rejections from the provider. :::

project_attributes_setting_booking_check_availability_max_days_in_advance

This attribute limits how far into the future the AI Employee will process availability-check requests. Requests targeting a date beyond this window are rejected before any availability request is dispatched, and the AI Employee asks the user for a closer date.

Set this to match the real booking horizon enforced by your booking provider and internal operations (for example, staffing and inventory planning horizons).

project_attributes_setting_booking_meta_fields_schema_template

This attribute defines the schema for booking meta fields that are generated alongside the booking payload. The primary supported field is smsBodyText, which lets you control the wording of booking-related SMS confirmations.

Example (restaurant):

{
  "type": "object",
  "properties": {
    "smsBodyText": {
      "type": "string",
      "description": "Generate the SMS with booking confirmation using the following template: [[project_business_name]] booking confirmation. Congratulations! Your booking for [number of people] on [date] at [time] has been successfully submitted."
    }
  },
  "required": ["smsBodyText"]
}

::: 🗒️ NOTE

This schema is merged with project_attributes_setting_booking_payload_schema_template during schema preparation. If this attribute is empty, the runtime uses a minimal default meta-fields schema so booking generation can still proceed. The smsBodyText field is only sent as an SMS when project_attributes_setting_booking_success_notification_on_sms_enabled is also enabled. :::

project_attributes_setting_booking_request_headers

This attribute defines the HTTP headers attached to booking API requests. Provide a JSON object where each key is a header name and each value is a header value.

Include only the headers required by your endpoint — typically an auth/API key header and a content-type declaration. Keep your token rotation strategy in sync with this configuration.

Example:

{ "X-API-KEY": "<REPLACE_WITH_API_KEY>", "Content-Type": "application/json" }

::: 🗒️ NOTE

These headers apply only to the HTTP booking branch (endpoint type). Intercom and project booking branches do not use them. The runtime does not validate header presence — invalid or missing headers fail at the endpoint or integration layer. :::

project_attributes_setting_booking_payload_schema_template

This attribute defines the JSON payload schema the AI Employee uses to build booking requests from conversation context. It controls which fields are extracted and what format they must be in before the booking is submitted.

Keep required fields strict and minimal, and write explicit field descriptions to make payload generation deterministic and easier to validate.

This attribute supports templating — you can insert values from other attributes using [[attribute_name]] placeholders.

Example (restaurant):

{
  "type": "object",
  "properties": {
    "dateTime": {
      "type": "string",
      "description": "Date and time of the reservation (YYYY-MM-DD HH:MM). Example: 2024-02-15 14:00"
    },
    "timeFormatted": {
      "type": "string",
      "description": "Time of the reservation in 12 hour format (hh:mm A). Example: 02:00 PM"
    },
    "partySize": {
      "type": "integer",
      "description": "Number of people for the reservation"
    },
    "firstName": {
      "type": "string",
      "description": "Guest first name."
    },
    "lastName": {
      "type": "string",
      "description": "Guest last name. If not provided, set the same as firstName."
    },
    "phoneNumber": {
      "type": "string",
      "description": "Customer's phone number in E.164 format"
    },
    "place": {
      "type": "string",
      "description": "Location or area within the restaurant (e.g., Patio). Set to one of the seating options."
    }
  },
  "required": [
    "dateTime",
    "timeFormatted",
    "partySize",
    "firstName",
    "lastName",
    "phoneNumber",
    "place"
  ]
}

::: 🗒️ NOTE

This schema is combined with project_attributes_setting_booking_meta_fields_schema_template during preparation to form the runtime booking-generation schema. If this attribute is empty when a schema-based booking branch is active, the runtime blocks dispatch and logs a configuration warning. Re-publishing regenerates compiled schema artifacts from this template. :::

project_attributes_setting_booking_cancellation_type

This attribute controls which execution path the AI Employee uses when cancelling existing bookings.

Possible values:

• default — Uses a manage-link flow. The AI Employee sends an SMS containing the booking-management URL from the booking record. Only bookings that have a manage_booking_url are considered valid under this mode.
• endpoint — Performs direct cancellation via HTTP DELETE request to the configured cancellation URL. The booking ID is injected into the URL before the request is sent. All future bookings are considered valid under this mode.
• project — Emits a convo_agent_cancel_booking system event with the selected booking payload.

::: ⚠️ CAUTION

Keep default until your direct-cancellation integration is fully configured and tested end-to-end. Switching to endpoint or project without the corresponding URL or event handler in place will break the cancellation flow. :::

Check availability configuration

project_attributes_setting_booking_check_availability_type

This attribute defines which integration path the AI Employee uses when checking availability.

Possible values:

• default — Uses the built-in provider-specific route. For restaurants this uses the native provider path; for hospitality this uses a dedicated event path.
• endpoint — Sends HTTP requests to your configured availability endpoint using the method defined in project_attributes_setting_booking_check_availability_request_http_method.
• intercom — Sends availability requests through the Intercom actor-event path (get_booking_windows).
• project — Sends a get_available_slots system event.

::: ⚠️ CAUTION

A mismatch between this type and your endpoint or event configuration will cause failed availability checks. Keep this aligned with your actual integration setup. :::

project_attributes_setting_booking_check_availability_processing_type

This attribute controls how the AI Employee interprets the response after an availability-check request is sent.

Possible values:

• formatted_response — Processes structured response fields directly. Use this when your integration returns a predictable structured payload.
• use_llm — Parses the raw response content using LLM-based post-processing. Use this only when the response format is unstable or non-standard.
• custom — Default post-processing is skipped so custom project-side handling can take over.

For formatted_response, your integration response must be compatible with the following schema:

{
  "type": "object",
  "title": "Availability Response Schema",
  "additionalProperties": true,
  "description": "Universal schema for availability across all industries",
  "required": ["availability"],
  "properties": {
    "range": {
      "type": "string",
      "description": "Human-readable time range (e.g., 'from 01:00 PM to 03:00 PM'). Optional for date-grouped responses."
    },
    "resourceType": {
      "type": "string",
      "description": "Type of resource being scheduled (optional, inferred if not provided). Examples: location, doctor."
    },
    "availability": {
      "type": "array",
      "description": "List of resources with their available time slots",
      "items": {
        "type": "object",
        "required": ["availableTimeSlots"],
        "properties": {
          "resource": {
            "type": "string",
            "description": "Name/identifier of the resource (e.g., 'Dr. Smith', 'Patio', '2025-11-08')"
          },
          "availableTimeSlots": {
            "type": "array",
            "description": "List of available time slots in hh:mm AM/PM format. Examples: 09:00 AM, 05:00 PM",
            "items": {
              "type": "string"
            }
          }
        }
      }
    },
    "targetAction": {
      "type": "string",
      "description": "Optional action identifier for workflow routing. Example: check_availability"
    }
  }
}

::: 🗒️ NOTE

custom mode assumes external or custom logic will complete the user-facing handling. If no such handler exists, the availability response will not be surfaced to the user. :::

project_attributes_setting_booking_check_availability_request_http_method

This attribute defines which HTTP method the AI Employee uses when calling your availability endpoint. This applies when project_attributes_setting_booking_check_availability_type is set to endpoint.

Possible values:

• POST — The AI Employee sends the generated availability payload in the request body.
• GET — The AI Employee builds query parameters from the availability payload schema and appends them to the availability URL.

Use POST unless your provider explicitly requires GET.

project_attributes_setting_booking_check_availability_request_headers

This attribute defines HTTP headers attached to availability-check API requests. Provide a JSON object where each key is a header name and each value is a header value.

Include only the headers required by your endpoint. Avoid embedding short-lived tokens unless your update process refreshes them reliably.

Example:

{ "X-API-KEY": "<REPLACE_WITH_API_KEY>", "Content-Type": "application/json" }

::: 🗒️ NOTE

These headers are used for both GET and POST request branches in the HTTP availability path. They are not consumed by project or intercom availability branches. The runtime does not validate header presence — missing or invalid headers fail at the integration layer. :::

project_attributes_setting_booking_check_availability_payload_schema_template

This attribute defines the payload schema the AI Employee uses to build availability-check requests from conversation context. How the schema is used depends on the HTTP method:

• For POST, the runtime sends a request body built from this schema.
• For GET, the runtime builds queryParams from this schema and appends them to the configured availability URL.

Keep required fields minimal and explicit. Field descriptions should be strict so payload generation remains deterministic.

This attribute supports templating — you can insert values from other attributes using [[attribute_name]] placeholders.

Example (restaurant):

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "description": "User's preferred date for the reservation in format YYYY-MM-DD. Example: 2024-09-28"
    },
    "time": {
      "type": "string",
      "description": "User's preferred time for the reservation in format HH:MM (24 hours). Example: 20:00. If not provided, default to 19:00",
      "default": "19:00"
    },
    "dateTime": {
      "type": "string",
      "description": "User's preferred date and time for the reservation in format YYYY-MM-DD HH:MM. Combine date and time in the format. Example: 2024-09-28 20:00"
    },
    "partySize": {
      "type": "string",
      "description": "Only one number, the number of people for the reservation. If a range is provided, set to maximum. Example: 6"
    },
    "timeZone": {
      "type": "string",
      "enum": ["[[project_business_time_zone]]"]
    },
    "restaurantId": {
      "type": "string",
      "enum": ["[[project_attributes_private_dynamic_restaurant_google_restaurant_id]]"]
    },
    "timeFormat": {
      "type": "string",
      "enum": ["12"]
    }
  },
  "required": ["date", "time", "dateTime", "partySize", "timeZone", "restaurantId", "timeFormat"]
}

::: ❗❗ IMPORTANT

If this attribute is empty at runtime, availability validation fails and the system logs a configuration warning instead of sending a request. Re-publishing regenerates runtime schema artifacts from this template. :::

project_attributes_setting_booking_check_availability_validation_schema_template

This attribute defines validation rules that the AI Employee applies before sending an availability-check request. If validation fails, the AI Employee does not proceed with the request and instead asks the user to correct the missing or invalid details.

Use clear boolean validation fields with descriptions that explain the condition to verify and how the AI Employee should interpret failures.

Example (restaurant):

{
  "type": "object",
  "properties": {
    "regularGroup": {
      "type": "boolean",
      "description": "Set to true if persons < [[project_attributes_restaurant_large_group_reservation_minimum_party_size]]."
    }
  },
  "required": ["regularGroup"]
}

::: 🗒️ NOTE

This schema is combined with project_attributes_setting_booking_check_availability_payload_schema_template during schema preparation. When empty, the runtime applies a default permissive validation schema so request generation can still proceed. Re-publishing regenerates runtime validation artifacts from this template. :::

project_attributes_setting_booking_check_availability_window

This attribute defines a configurable window value used by schema-driven availability flows. It only takes effect when your availability payload schema references it via the [[project_attributes_setting_booking_check_availability_window]] placeholder.

Keep this aligned with your provider's search horizon or window constraints. If your schema does not reference this setting, changing it has no runtime impact on schema-generated payload fields.

::: 🗒️ NOTE

Some project-specific booking integrations may also read this value directly for date-range calculations, even when the payload schema does not include the placeholder. :::

project_attributes_setting_booking_check_availability_working_hours_status

This attribute controls whether the AI Employee validates the requested slot time against business working hours before sending an availability request.

Behavior by value:

• Enabled (True): The AI Employee blocks out-of-hours requests and asks the user for a different day or time before proceeding to the availability source.
• Disabled (False): The AI Employee skips this gate and proceeds directly to the availability request flow. Downstream provider responses then determine whether the slot is available.

::: 🗒️ NOTE

Keep this enabled if your business must strictly avoid off-hours booking checks. When enabled, working-hours status is evaluated from the structured schedule defined in project_business_working_hours. If that schedule object is empty at runtime, the working-hours resolver falls back to LLM evaluation. :::