---

name: hotel-booking-ai version: 0.2.4 description: 'Book hotels with live prices and availability. Search destinations or hotel names, compare room rates, verify rooms before booking, create reservations, check or cancel orders, and pay with WeChat Pay or Alipay. Use only when the user explicitly asks to book a hotel, query room rates, manage a booking, or start payment; collect location, check-in date, check-out date, and guest count before API calls.' metadata.openclaw: {"emoji": "🏨", "primaryEnv": "user_key.txt"}

Hotel Booking AI

A hotel booking assistant for live hotel search, room-rate comparison, availability checks, reservations, order lookup, cancellation, and payment.

When to Use

Use this skill only when the user explicitly asks to book a hotel, query room rates, check an existing booking, cancel a booking, or start payment for a booking.

Do not trigger it for general travel planning, directions, itinerary ideas, or attraction recommendations. Before any API call, confirm the four required inputs: location, check-in date, check-out date, and number of guests.

⚠️ Critical Rules (Must Follow)

1. Never fabricate hotels, room types, or prices from training data or memory. All hotel-related data MUST come exclusively from the live HTTP API responses. If an API call fails and retries do not help, tell the user the exact error — never answer from memory or recommend alternatives on your own.
2. When the API returns HTTP 401 or {"ok": false, "error": "unauthorized: ..."}, the user_key is invalid or expired. Stop the workflow immediately: delete {baseDir}/user_key.txt and ask the user to visit the AgentAuth Dashboard to obtain a new user_key before continuing.
3. Interpret the cancellation policy field cancelPolicyInfos correctly. refundable: true means the rate IS refundable / cancellable — never interpret it as "non-cancellable". For refundable rates, startDateTime is the free-cancellation deadline: cancelling before it is free, cancelling after it incurs the amount as a cancellation fee. amount > 0 does NOT mean the rate is non-cancellable.

API

Base URL: http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028

All endpoints are POST and require a user_key field in the request body.

Endpoint List

Response Format

Success: {"ok": true, "data": {...}}
Failure: {"ok": false, "error": "error description"}

Calling Examples (curl)

# Search regions
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/search_location" \
  -d '{"user_key": "<user_key>", "keyword": "Tokyo"}'

# Search hotels
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/search_hotels" \
  -d '{"user_key": "<user_key>", "region_id": "3263", "check_in_date": "2026-05-01", "check_out_date": "2026-05-03", "adults": 2}'

# Query room types
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/query_room_rates" \
  -d '{"user_key": "<user_key>", "hotel_id": "12345", "check_in_date": "2026-05-01", "check_out_date": "2026-05-03", "adults": 2, "room_count": 1}'

# Verify price
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/check_room_availability" \
  -d '{"user_key": "<user_key>", "hotel_id": "12345", "rate_code": "xxx", "check_in_date": "2026-05-01", "check_out_date": "2026-05-03", "adults": 2, "room_count": 1}'

# Create booking
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/create_booking" \
  -d '{"user_key": "<user_key>", "hotel_id": "12345", "rate_code": "xxx", "check_in_date": "2026-05-01", "check_out_date": "2026-05-03", "guest_name": "John Smith", "adults": 2, "room_count": 1, "total_price": 1260.00}'

# Query booking
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/query_booking" \
  -d '{"user_key": "<user_key>", "agent_ref_id": "TM20260501001"}'

# Cancel booking
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/cancel_booking" \
  -d '{"user_key": "<user_key>", "agent_ref_id": "TM20260501001"}'

# Pay
curl -s -X POST -H "Content-Type: application/json" \
  "http://nlb-3psfnp4wzcgnlw0fe0.cn-shenzhen.nlb.aliyuncsslb.com:19028/skill/pay_order" \
  -d '{"user_key": "<user_key>", "agent_ref_id": "TM20260501001", "payment_type": 11}'

---

Setup

Before calling any API, the user must be authenticated.

Step 1 — User Key

1. Read {baseDir}/user_key.txt.
2. If the file does not exist or is empty — do NOT call any API. Tell the user:

   "Before we start, I need to verify your identity. Please visit https://aauth-170125614655.asia-northeast1.run.app/dashboard, sign in with Google, copy your user_key (format: uk_xxxxxxxx), and paste it here." When the user provides it, save it to {baseDir}/user_key.txt and continue.

3. If the file exists and has content — use it directly; do NOT ask the user again.
4. If the API returns 401 or an error containing unauthorized — delete {baseDir}/user_key.txt and repeat step 2.

---

Endpoint Parameters

/skill/search_location

Returns data.regions (region list with region_id) and data.hotels (hotel list with hotel_id).

/skill/search_hotels

Returns data.hotels — at most the 3 cheapest hotels.

/skill/query_room_rates

Returns data.room_types. Each room type contains rate_code, total_price, currency_code, meal_info, refundable, cancelPolicyInfos.

/skill/check_room_availability

Returns data.room_types with the verified live price and rate_code (which may differ from the one returned earlier), plus cancelPolicyInfos.

/skill/create_booking

Returns data.agent_ref_id (booking reference).

/skill/query_booking

/skill/cancel_booking

Returns data.status, data.cancel_fee, data.refund_amount (if any), data.currency. Always confirm the booking reference with the user before cancelling.

/skill/pay_order

Returns data.pay_url — share this link with the user to complete the payment.

---

Booking Workflow

0. Search region (if needed)  → search_location to get region_id
1. Search hotels              → search_hotels
2. Query room rates           → query_room_rates
3. Verify price & lock room   → check_room_availability
4. Create booking             → create_booking (no phone or email required)
5. Initiate payment           → ask the user for payment method, then pay_order
6. Query booking              → query_booking (any time)
7. Cancel booking             → only after the user explicitly asks AND confirms the booking reference, then cancel_booking

---

Notes

• All dates must be in YYYY-MM-DD format.
• region_id and hotel_id MUST be passed as strings (e.g. "3263", not 3263).
• total_price MUST use the value returned by check_room_availability, not the one from query_room_rates.
• Do not proactively collect phone numbers or emails — the booking flow does not need them.
• After create_booking, ask for the payment method before calling pay_order.
• Always confirm the booking reference with the user before calling cancel_booking.
• Reading the cancellation policy: refundable: true = refundable / cancellable; startDateTime = free-cancellation deadline; amount = cancellation fee charged after that deadline — it does NOT mean non-cancellable.
• When showing room types for multiple hotels, the data for each hotel MUST come strictly from that hotel's query_room_rates response. Never mix data across hotels. If a hotel returns room_types: None or total: 0, only show "No rooms available for this hotel" — never fill in data from other hotels.
• When an API call fails, report the exact error to the user — do not fabricate data or recommend alternatives.

For detailed parameter reference, region IDs, currency codes, and troubleshooting, see references/parameter_guide.md