Hotel Booking AI

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.

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

Function	Path
Search regions / hotels	/skill/search_location
Search hotel list	/skill/search_hotels
Query room types and rates	/skill/query_room_rates
Verify price & lock room	/skill/check_room_availability
Create booking	/skill/create_booking
Query booking	/skill/query_booking
Cancel booking	/skill/cancel_booking
Initiate payment	/skill/pay_order

Response Format

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

Calling Examples (curl)

bash

# 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

Parameter	Type	Description
user_key	string	Read from {baseDir}/user_key.txt
keyword	string	Search keyword (city name, landmark, hotel name, etc.)

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

/skill/search_hotels

Parameter	Type	Description
user_key	string	Read from {baseDir}/user_key.txt
region_id	string	Region ID (must be passed as a string, e.g. "3263")
check_in_date	string	Check-in date in YYYY-MM-DD
check_out_date	string	Check-out date in YYYY-MM-DD
adults	int	Number of adults per room
lowest_price	int	Minimum price (CNY, optional)
highest_price	int	Maximum price (CNY, optional)

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

/skill/query_room_rates

Parameter	Type	Description
user_key	string	Read from {baseDir}/user_key.txt
hotel_id	string	Hotel ID
check_in_date	string	Check-in date
check_out_date	string	Check-out date
adults	int	Number of adults per room
room_count	int	Number of rooms (default 1)

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

/skill/check_room_availability

Parameter	Type	Description
user_key	string	Read from {baseDir}/user_key.txt
hotel_id	string	Hotel ID
rate_code	string	The rate_code returned by query_room_rates
check_in_date	string	Check-in date
check_out_date	string	Check-out date
adults	int	Number of adults per room
room_count	int	Number of rooms (default 1)

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

Parameter	Type	Description
user_key	string	Read from {baseDir}/user_key.txt
hotel_id	string	Hotel ID
rate_code	string	The rate_code returned by check_room_availability
check_in_date	string	Check-in date
check_out_date	string	Check-out date
guest_name	string	Guest name (the system parses Chinese / English names automatically)
adults	int	Number of adults per room
room_count	int	Number of rooms (default 1)
currency	string	Currency, default CNY
total_price	float	Total price returned by check_room_availability

Returns data.agent_ref_id (booking reference).

/skill/query_booking

Parameter	Type	Description
user_key	string	Read from {baseDir}/user_key.txt
agent_ref_id	string	Booking reference returned by create_booking

/skill/cancel_booking

Parameter	Type	Description
user_key	string	Read from {baseDir}/user_key.txt
agent_ref_id	string	Booking reference returned by create_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

Parameter	Type	Description
user_key	string	Read from {baseDir}/user_key.txt
agent_ref_id	string	Booking reference
payment_type	int	11 = WeChat Pay, 12 = Alipay
return_url	string	Redirect URL after payment (optional)

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

---

Booking Workflow

text

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