Timeplex K-Beauty Booking

{'type': 'object', 'required': ['slug'], 'properties': {'lang': {'type': 'string', 'description': 'Customer language (optional): ko|en|ja|zh|th. Defaults to the original text (ko).'}, 'slug': {'type': 'string', 'description': 'Shop slug returned by search_shops'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['shop', 'services'], 'properties': {'lang': {'type': 'string'}, 'note': {'type': 'string'}, 'shop': {'type': 'object', 'properties': {'name': {'type': 'string'}, 'slug': {'type': 'string'}, 'address': {'type': 'string'}, 'map_url': {'type': 'string'}, 'business_type': {'type': ['string', 'null']}, 'business_hours': {'type': ['array', 'null'], 'items': {'type': 'object', 'properties': {'open': {'type': ['string', 'null']}, 'close': {'type': ['string', 'null']}, 'closed': {'type': 'boolean', 'description': 'true = closed that weekday'}}}, 'description': 'Weekly hours, index 0 = Sunday: [{open:"10:30", close:"21:00", closed:false} Ã\x97 7]'}}}, 'services': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string', 'description': 'Pass as items[].service_id to search_availability / start_booking'}, 'name': {'type': 'string'}, 'price': {'type': ['number', 'string', 'null']}, 'currency': {'type': 'string'}, 'duration_min': {'type': ['integer', 'null']}}}}, 'resources': {'type': 'array', 'items': {'type': 'object', 'properties': {'id': {'type': 'string'}, 'name': {'type': 'string'}, 'service_ids': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Services this staff/seat handles. Empty = handles every service. Pass this resource only for a service in this list.'}}}, 'description': 'Staff to designate (designated-staff shops) or seats (capacity-based shops).'}, 'booking_model': {'type': ['string', 'null'], 'description': "How this shop books: 'designated' â\x80\x94 pass items as [{service_id, resource_id}]; 'capacity' â\x80\x94 pass items as [{service_id, qty}]. Use this for search_availability and start_booking."}}}

{'type': 'object', 'required': ['venue_name'], 'properties': {'lang': {'type': 'string', 'maxLength': 10, 'description': 'Customer language (optional)'}, 'venue_name': {'type': 'string', 'maxLength': 255, 'description': 'Name of the shop the customer wants to book'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['recorded', 'next_step_url'], 'properties': {'recorded': {'type': 'boolean', 'description': 'true â\x80\x94 the demand was logged'}, 'link_label': {'type': 'string'}, 'instruction': {'type': 'string'}, 'link_markdown': {'type': 'string', 'description': 'Put this into the reply as-is (never expose the raw URL)'}, 'next_step_url': {'type': 'string', 'description': 'Concierge chat where the customer completes the request'}}}

{'type': 'object', 'required': ['slug', 'date', 'items'], 'properties': {'date': {'type': 'string', 'description': 'YYYY-MM-DD (Asia/Seoul)'}, 'slug': {'type': 'string', 'description': 'Shop slug returned by search_shops.'}, 'time': {'type': 'string', 'description': 'Optional requested appointment time (HH:MM). If provided, check whether that exact time is available and return nearby available alternatives if unavailable.'}, 'items': {'type': 'array', 'items': {'type': 'object', 'properties': {'qty': {'type': 'integer'}, 'service_id': {'type': 'string'}, 'resource_id': {'type': 'string'}}, 'additionalProperties': False}, 'description': 'Booking items. Follow the booking_model returned by get_shop_services: use resource_id for designated-staff shops and qty for capacity-based shops. designated (hair salons, plus some beauty shops such as body scrub): [{service_id, resource_id}]. capacity (most massage, spa, etc.): [{service_id, qty}] where qty is the number of guests (party size).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['date', 'slots'], 'properties': {'date': {'type': 'string'}, 'mode': {'type': 'string', 'description': 'Slot mode the shop operates in'}, 'note': {'type': 'string'}, 'slots': {'type': 'array', 'items': {'type': 'object', 'properties': {'time': {'type': 'string'}, 'available': {'type': 'boolean'}}}}, 'blocked': {'type': 'string', 'description': "Present when online booking is blocked (e.g. 'inquiry_only')"}, 'timezone': {'type': 'string'}, 'next_step': {'type': 'string'}, 'alternatives': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Nearby bookable times when the requested time is not available'}, 'requested_time': {'type': 'object', 'properties': {'time': {'type': 'string'}, 'available': {'type': 'boolean'}}, 'description': 'Verdict for the exact time asked, when time was given.'}}}

{'type': 'object', 'properties': {'query': {'type': 'string', 'description': 'Free-text user request or a specific shop name (optional), in any language. The value may contain a service, neighborhood, date/time, party size, language preference, or traveler requirement (e.g. "foreigner-friendly head spa in Gangnam tomorrow for 2 people"). Recognized service and location terms are extracted before shop-name matching; the value is treated as a shop name only when the remaining words closely match a registered shop.'}, 'location': {'type': 'string', 'description': 'Area (optional; overrides an area found in query), in English, Korean, Japanese, Chinese or Russian â\x80\x94 "Seoul", "Gangnam", "Myeongdong", "Hongdae", "Seongsu", "Busan", "ê°\x95ë\x82¨", "æ\x98\x8eæ´\x9e", "СеÑ\x83л"â\x80¦ If no shop is in that area, the search widens to the surrounding city (relaxed). Newly joined shops with no address yet are appended with area_match=false.'}, 'service_type': {'type': 'string', 'description': 'Service (optional; overrides a service found in query). Available on TimePlex now: massage, head spa / scalp treatment, hair salon, spa, Korean body scrub (seshin, akasuri), makeup, semi-permanent makeup (PMU, microblading, brow tattoo) â\x80\x94 in English, Korean, Japanese, Chinese or Russian (ã\x83\x9eã\x83\x83ã\x82µã\x83¼ã\x82¸, ã\x83\x98ã\x83\x83ã\x83\x89ã\x82¹ã\x83\x91, ã\x82¢ã\x82«ã\x82¹ã\x83ª, æ\x8c\x89æ\x91©, æ\x90\x93澡, маÑ\x81Ñ\x81аж, Ñ\x81еÑ\x81инâ\x80¦). Other services (nail, lash, facial, personal color) are recognized but may return unsupported_service. Leave empty to search all.'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['shops', 'count'], 'properties': {'note': {'type': 'string', 'description': 'Follow-up guidance for the agent'}, 'count': {'type': 'integer'}, 'shops': {'type': 'array', 'items': {'type': 'object', 'properties': {'name': {'type': 'string'}, 'slug': {'type': 'string', 'description': 'Shop id for the other tools'}, 'address': {'type': ['string', 'null'], 'description': 'null = newly joined shop that has not registered an address yet'}, 'bookable': {'type': 'boolean', 'description': 'true = bookable via this MCP; false = use request_booking'}, 'category': {'enum': ['hair', 'beauty'], 'type': 'string'}, 'area_match': {'type': 'boolean', 'description': 'Present only when a location filter was applied: true = address matched the area; false = no address registered yet (newly onboarding) â\x80\x94 confirm the area with the shop'}, 'business_type': {'type': ['string', 'null'], 'description': 'Filter code. Use business_type_label when naming the shop to the user.'}, 'matched_services': {'type': 'array', 'items': {'type': 'string'}, 'description': 'Present when the shop matched through its menu: the menu items (original names) that matched the request. Pick the service from these in get_shop_services.'}, 'business_type_label': {'type': ['object', 'null'], 'properties': {'en': {'type': 'string'}, 'ko': {'type': 'string'}}, 'description': 'Display label the shop selected (spa = ì\x8a¤í\x8c\x8c·í\x97¤ë\x93\x9cì\x8a¤í\x8c\x8c / spa & head spa). null when unset.'}}}, 'description': 'Matching shops.'}, 'relaxed': {'type': ['object', 'null'], 'description': 'Set when no shop was in the requested area and the search widened: {area:{from,to}}.'}, 'categories': {'type': 'array', 'items': {'type': 'string'}}, 'interpreted': {'type': 'object', 'description': 'How the request was read: service (massage|headspa|hair|spa|scrub|makeup|â\x80¦), area, foreigner_friendly, date (YYYY-MM-DD, KST), time, time_range, time_of_day, party_size, gender, attributes, name_query (leftover words treated as a shop name), ignored_terms. Use date/time/party_size for search_availability (party_size â\x86\x92 qty).'}, 'reply_header': {'type': 'string'}, 'filter_applied': {'type': 'object', 'description': 'How the inputs were interpreted (category/service_type/location/query)'}, 'reply_header_usage': {'type': 'string'}, 'shop_name_not_found': {'type': ['string', 'null'], 'description': 'Set when the user named a specific shop that is not registered on Timeplex. Tell the user that shop is not on Timeplex â\x80\x94 do not treat it as a category with zero results, and do not submit it with request_booking.'}, 'unsupported_service': {'type': ['string', 'null'], 'description': 'A recognized service that is not on TimePlex yet (e.g. nail, lash, facial, personal_color).'}, 'available_service_types': {'type': 'array', 'items': {'type': 'string'}, 'description': 'business_type values currently registered'}}}

{'type': 'object', 'required': ['slug'], 'properties': {'date': {'type': 'string', 'description': 'YYYY-MM-DD (Asia/Seoul). Optional â\x80\x94 omit if the customer has not picked a date; they choose it on the booking page.'}, 'lang': {'type': 'string', 'description': 'Customer language (optional): ko|en|ja|zh. Defaults to en. Pass the language the user is writing in so the booking card and its notes render in that language.'}, 'slug': {'type': 'string', 'description': 'Shop slug returned by search_shops.'}, 'time': {'type': 'string', 'description': 'HH:MM. Optional â\x80\x94 omit if the customer has not picked a time.'}, 'items': {'type': 'array', 'items': {'type': 'object', 'properties': {'qty': {'type': 'integer'}, 'service_id': {'type': 'string'}, 'resource_id': {'type': 'string'}}, 'additionalProperties': False}, 'description': 'Optional â\x80\x94 omit if no service is chosen yet. Follow the booking_model returned by get_shop_services: use resource_id for designated-staff shops and qty for capacity-based shops. designated: [{service_id, resource_id}] â\x80\x94 **exactly one** (these shops book one service at a time). capacity: [{service_id, qty}] â\x80\x94 multiple allowed (several services and several people at once).'}}, 'additionalProperties': False}

{'type': 'object', 'required': ['booking_url', 'link_markdown', 'confirmed'], 'properties': {'lang': {'type': 'string', 'description': 'Language the card content is rendered in (echo of input lang; en fallback). The widget uses it to localize its own labels.'}, 'note': {'type': 'string', 'description': 'How the slot is secured and finally confirmed â\x80\x94 mention this to the customer'}, 'summary': {'type': 'object', 'properties': {'shop': {'type': 'string'}, 'when': {'type': ['string', 'null']}, 'items': {'type': 'array', 'items': {'type': 'object', 'properties': {'qty': {'type': 'integer'}, 'price': {'type': ['number', 'string', 'null']}, 'staff': {'type': ['string', 'null']}, 'service': {'type': ['string', 'null']}, 'currency': {'type': 'string'}, 'duration_min': {'type': ['integer', 'null']}}}}, 'currency': {'type': 'string'}, 'timezone': {'type': 'string'}, 'total_price': {'type': 'number'}}, 'description': 'What is preselected on the booking page.'}, 'guidance': {'type': 'string', 'description': 'Customer-facing summary of the remaining steps â\x80\x94 keep it light and pass it on'}, 'confirmed': {'type': 'boolean', 'description': 'Always false â\x80\x94 nothing is booked by this tool'}, 'link_label': {'type': 'string'}, 'next_steps': {'type': 'array', 'items': {'type': 'string'}, 'description': 'What the customer does after opening the link (contact info, payment, shop-owner approval)'}, 'booking_url': {'type': 'string', 'description': 'Prefilled booking page (customer completes contact info + payment there)'}, 'reply_header': {'type': 'string'}, 'link_markdown': {'type': 'string', 'description': 'Put this into the reply as-is (never expose the raw URL)'}, 'reply_header_usage': {'type': 'string'}}}