---
title: "Chat"
method: POST
path: "/v1/chat"
tags: ["Hotels"]
---

# Chat

`POST /v1/chat`

## Request

- Base URL: `https://api.vistalink.com`
- URL: `https://api.vistalink.com/v1/chat`
- Auth: HTTP bearer

Conversational hotel search via the supervisor pipeline.

Send a natural-language message; the supervisor searches, reasons, and replies.
Hotels that match the query are returned in ``hotels[]`` alongside the assistant
``message``.

### Images

Each hotel in ``hotels[]`` carries two image fields:

- **``hero_image_url``** — use this as the card thumbnail. The system selects
  the image that best matches the query intent (e.g. a "hotel with pool" search
  returns a pool photo, not a generic exterior). Always render this field as the
  primary hotel image; do **not** fall back to ``images[0]`` — they may differ.
  ``null`` only when the hotel has no images.

- **``images[]``** — ordered gallery, up to 5 images per hotel. Use for a
  lightbox or carousel. Each entry has a ``url`` (fully-qualified CDN URL) and
  an optional ``label`` (e.g. ``"swimming pool indoor"``, ``"room"``).
  Empty list when the hotel has no images.

`/v1/hotels/{id}` returns the same two fields but with up to 50 gallery images.

## Request body

- ChatRequest: POST /v1/chat request body.
  - `guest_id` string, uuid, nullable: Guest profile ID
  - `session_id` string, uuid, nullable: Existing session to continue
  - `message` string, required: User message
  - `currency` string, nullable
  - `locale` string, nullable
  - `context` object, nullable: Extra structured context
  - `clarification_id` string, nullable: The clarification_id echoed back from a previous response
  - `clarification_option_id` string, nullable: The id of the option the user selected (set with clarification_id)
  - `user_location` UserLocationContext: Caller-supplied GPS coordinates for location-sensitive queries. Clients can supply this to skip the supervisor's GPS-collection round-trip on queries like "hotels near me". Lat/lng are validated to ensure they are physically meaningful before being injected into structured_context.
    - `lat` number, required: Latitude
    - `lng` number, required: Longitude
    - `accuracy` number, nullable: Accuracy in meters

## Response `200`

Successful Response

- ChatResponse: POST /v1/chat response body.
  - `session_id` string, uuid, required
  - `message` string, required: Assistant reply text
  - `hotels` HotelCard[]
    - `hotel_id` string, required
    - `name` string, required
    - `city` string, nullable
    - `country` string, nullable
    - `address` string, nullable
    - `star_rating` number, nullable
    - `review_score` number, nullable
    - `review_count` integer, nullable
    - `latitude` number, nullable
    - `longitude` number, nullable
    - `website_url` string, nullable
    - `parley_url` string, nullable: Public hotel page on Parley (meetparley.ai) with the stay's dates; send users here to view or book the hotel.
    - `amenities` string[]
    - `price` union
      - StayPrice: The price of one specific stay. Only present when the request carried both ``check_in`` and ``check_out``. Always the all-inclusive total (taxes and fees included) for the whole stay, in ``currency``, for one room and ``adults`` guests, from a scrape no older than 72 hours.
        - `total` number, required: All-inclusive total for the whole stay, in `currency`.
        - `currency` string, required: ISO 4217 currency of `total` (the requested currency).
        - `includes_taxes_and_fees` boolean: Always true: totals with an unknown tax basis are never returned.
        - `check_in` string, date, required
        - `check_out` string, date, required
        - `nights` integer, required
        - `adults` integer
        - `rooms` integer
        - `source_total` number, nullable: The same total in the currency it was observed in.
        - `source_currency` string, nullable
        - `observed_at` string, date-time, nullable: When this price was observed.
      - object
    - `images` HotelImageCard[]: Ordered gallery of hotel images (up to 5 on /v1/chat and /v1/search; up to 50 on /v1/hotels/{id}). Use for lightbox/carousel — not as the card thumbnail. Empty list when the hotel has no images.
      - `url` string, required: Fully-qualified CDN URL of the image.
      - `label` string, nullable: Image category label (e.g. 'swimming pool indoor', 'building', 'room'). Null when unclassified.
    - `review_highlight` string, nullable
    - `guest_insights` GuestInsights: Aggregated guest insights for a hotel.
      - `highlights` string[]
      - `aspects` GuestInsightAspect[]
        - `type` string, required
        - `summary` string, required
        - `sentiment` number, nullable
        - `quote` string, nullable
    - `description` string, nullable
    - `hotel_type` string, nullable
    - `rates` RoomRate[], nullable
      - `room_name` string
      - `amenities` string[]
      - `room_size_sqm` number, nullable
      - `room_description` string, nullable
      - `offers` RoomOffer[]
        - `price` number, nullable
        - `currency` string
        - `includes_taxes_and_fees` boolean, nullable
        - `has_breakfast` boolean
        - `has_free_cancellation` boolean
    - `hero_image_url` string, nullable: Intent-aware thumbnail URL. Pre-selected to match the query context (e.g. a pool search returns a pool photo). Always use this field as the card thumbnail — do not substitute images[0]. Null only when the hotel has no images.
    - `hero_image_label` string, nullable: Category label of the hero image (e.g. 'swimming pool indoor', 'building'). Null when unclassified.
    - `explanation` string, nullable
    - `explanation_factors` ExplanationFactor[]
      - `factor_type` string, required
      - `human_readable` string, required
      - `contribution` number, required
    - `poi_distances` object
    - `routes_to_pois` object
  - `pois` object[]
  - `routes` object[]
  - `references` Reference[]
    - `url` string, required
    - `title` string, nullable
    - `domain` string, nullable
    - `index` integer, nullable
  - `usage` UsageInfo: Per-request usage info attached to responses. Surfaces cost and latency — the metrics API clients need for budgeting and performance monitoring. Token-level detail is recorded internally but not exposed here (billing is per-call, not per-token).
    - `latency_ms` integer, nullable
    - `cost_usd` number, nullable
  - `clarification_pending` ClarificationPending: Phase 52.5: Clarification request surfaced to MCP clients when the supervisor needs the user to pick one of 2-4 interpretations before committing to expensive work. Mirrors the SSE ``clarification_request`` event payload.
    - `clarification_id` string, required
    - `question` string, required
    - `options` ClarificationOptionCard[]
      - `id` string, required
      - `label` string, required
      - `description` string, nullable
      - `image_url` string, nullable
      - `distance_meters` integer, nullable
    - `context_hint` string, nullable
    - `allow_free_text` boolean
    - `display_mode` 'inline' | 'panel'
  - `segments` Segment[]
    - `type` 'text' | 'hotel_ref' | 'trip_suggestion', required
    - `id` string, required
    - `content` string, nullable
    - `hotel_id` string, nullable
    - `hotel_ids` string[], nullable
  - `calls` CallHandle[]: Voice calls initiated or updated during this turn. Use call_id with /v1/call/{call_id}/status to follow up.
    - `call_id` string, required
    - `tool` string, nullable: Which voice tool produced this handle
    - `status` string, nullable
    - `success` boolean, nullable
    - `ui_call_id` string, nullable
    - `hotel_name` string, nullable
    - `hotel_id` string, nullable
    - `scheduled_time` string, nullable
    - `queue_position` integer, nullable
    - `error` string, nullable

## Other responses

- `401`: Unauthorized
- `422`: Validation Error
- `429`: Too Many Requests

---

[API](https://skmtc.dev/vistalink/apis/vistalink-hotels-api.md) · [All operations](https://skmtc.dev/vistalink/apis/vistalink-hotels-api/llms.txt) · [OpenAPI document](https://skmtc.dev/vistalink/apis/vistalink-hotels-api/revisions/a5bb847f45c2?raw)