Early access — Phase 2

AI

The AI module provides RAG-grounded chat completions, intent detection, and conversation threading for property-specific guest interactions. Every response is grounded in your property's knowledge base — menus, policies, FAQs, and SOPs indexed via the Knowledge Base module.

How a chat turn works

1. Receive — User message arrives via POST /v1/ai/chat.
2. Retrieve — Last user message is embedded and matched against the property's Pinecone namespace. Top-k chunks selected.
3. Ground — Retrieved chunks are injected into the system prompt as structured property context.
4. Generate — GPT-4o-mini completes the turn with grounded, property-specific knowledge.
5. Detect — Intent classification runs on the user message. Detected intents are stored and trigger webhooks.
6. Persist — Turn stored to conversation thread. Sources returned in response.

Endpoints

POST/v1/ai/chatRAG-grounded chat completion

Submit a conversation turn. Returns an assistant message grounded in the property knowledge base, with detected intent and source citations.

Request Body

messagesChatMessage[]requiredFull conversation history. Last message must be role=user.

guest_idstringAssociate this turn with a known guest (gst_...). Optional.

conversation_idstringContinue an existing thread. Omit to start a new conversation.

channelstringOrigin channel: web_chat, voice, widget, api. Default: api.

use_knowledgebooleanQuery the knowledge base to ground the response. Default: true.

top_kintegerNumber of knowledge chunks to inject. Range 1–10. Default: 4.

First turn

curl -X POST https://api.escapelife.ai/v1/ai/chat \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "What spa treatments do you offer, and what is the price for a deep tissue massage?" }
    ],
    "channel": "web_chat"
  }'

Response

{
  "conversation_id": "cvs_9xk2mp7q",
  "message_id": "msg_r4t5y6u7",
  "role": "assistant",
  "content": "We offer a range of spa treatments at Grand Sunset Resort. Our Deep Tissue Massage runs 90 minutes and is priced at $200 — it's ideal for targeting chronic muscle tension. We also offer a Swedish Massage (60 min, $150), Hot Stone Therapy (75 min, $175), and a Couples Retreat in our private suite (90 min, $320 per couple). Would you like to schedule an appointment?",
  "intent": {
    "intent": "upsell",
    "confidence": 0.80
  },
  "sources": [
    {
      "source_id": "ks_abc123",
      "source_name": "Spa Treatment Menu — Spring 2026",
      "source_type": "menu",
      "score": 0.94
    }
  ],
  "created_at": "2026-03-15T10:00:01Z"
}

Continue the thread (pass conversation_id)

curl -X POST https://api.escapelife.ai/v1/ai/chat \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_id": "cvs_9xk2mp7q",
    "messages": [
      { "role": "user", "content": "What spa treatments do you offer?" },
      { "role": "assistant", "content": "We offer a Deep Tissue Massage (90 min, $200)..." },
      { "role": "user", "content": "Can I book the couples retreat for tomorrow evening?" }
    ],
    "guest_id": "gst_a1b2c3d4e5f6"
  }'

GET/v1/ai/conversations/{conversation_id}Get a conversation

Retrieve conversation metadata — channel, status, guest association, and timestamps.

Path / Query Parameters

conversation_idstringrequiredConversation ID (cvs_...).

GET/v1/ai/conversations/{conversation_id}/messagesList conversation messages

Return all turns in a conversation thread, ordered chronologically. Includes source citations on assistant messages.

Path / Query Parameters

conversation_idstringrequiredConversation ID (cvs_...).

Intent detection

Intent is detected automatically on every user message. When a non-general intent is detected, a GuestIntent record is persisted and a guest.intent.created webhook is fired.

booking

book, reserve, check-in, availability, dates

service_request

need, request, bring, fix, broken, housekeeping

complaint

disappointed, problem, issue, unacceptable

upsell

upgrade, spa, dinner, experience, add-on

itinerary

what should I do, schedule, plan, recommend

local_recommendation

restaurant, bar, beach, hike, nearby, local

general

everything else (no webhook fired)

Model configuration

Completion modelgpt-4o-mini

Embedding modeltext-embedding-3-small

Max output tokens800

Temperature0.4

Knowledge chunks injectedtop_k (default 4)

Namespace isolationPer property_id — cross-property retrieval is blocked

Webhooks fired by this module

guest.intent.created

A non-general intent was detected from a conversation turn.

conversation.closed

A conversation thread was marked closed.