> ## Documentation Index > Fetch the complete documentation index at: https://docs.obvlo.com/llms.txt > Use this file to discover all available pages before exploring further. # AI Chat (Preview) > Preview conversational endpoint for recommendations, guide card listings, itinerary generation, and itinerary email delivery. This endpoint is in preview. Request and response shapes may change faster than the stable search and host endpoints. ## Overview The AI Chat endpoint powers conversational discovery in Obvlo experiences. It can: * answer chat queries with curated guide and listing cards * return guide-card listings for detail views * generate itineraries * send generated itineraries by email ## Base route ```http theme={null} POST /v2/orgs/{orgId}/chat ``` Authentication uses the standard `key` query parameter. ## Preview notes * Treat this endpoint as beta or preview in production clients. * Conversation-oriented fields such as `actions`, `hostInterests`, and itinerary payloads may evolve. * Use stable search endpoints when you need fixed, non-conversational retrieval contracts. ## POST action modes The `action` field controls how the endpoint behaves. | `action` | Purpose | | ----------------- | ---------------------------------------------------------------------- | | `chat` | Default conversational search and recommendation flow. | | `createItinerary` | Builds a day-by-day itinerary from the active profile and preferences. | | `sendEmail` | Sends a previously generated itinerary to an email address. | ## Required path and query parameters | Parameter | In | Type | Description | | --------- | ----- | ------ | ------------------------------------ | | `orgId` | path | string | Organisation ID for the request. | | `key` | query | string | Public API key for the organisation. | ## Common request fields | Field | Type | Description | | --------------------- | ------- | -------------------------------------------------------------------------------------------------- | | `message` | string | User message for the chat turn. Use `""` when triggering a non-text action. | | `profileId` | string | Optional host profile context for search and itinerary generation. Required for `createItinerary`. | | `lang` | string | Optional BCP-47 language code for response content. | | `latlng` | string | Optional `lat,lng` user location override. | | `conversationHistory` | array | Prior user and assistant messages. | | `preferences` | object | Optional guided-discovery preferences: `tripType`, `userCategory`, `interests`. | | `sessionId` | string | Optional client session identifier for tracking. | | `fingerprintId` | string | Optional end-user fingerprint identifier for tracking. | | `isInitialSearch` | boolean | Optional hint to randomise initial recommendation ranking. | ## Example requests ### Chat for recommendations ```bash theme={null} curl --request POST \ --url 'https://api.obvlo.com/v2/orgs/YOUR_ORG_ID/chat?key=YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "message": "Find great cocktail bars nearby", "profileId": "YOUR_HOST_ID", "lang": "en-GB", "action": "chat" }' ``` ### Create an itinerary ```bash theme={null} curl --request POST \ --url 'https://api.obvlo.com/v2/orgs/YOUR_ORG_ID/chat?key=YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "message": "", "action": "createItinerary", "profileId": "YOUR_HOST_ID", "durationDays": 3, "preferences": { "tripType": "leisure", "userCategory": "couple", "interests": ["food", "culture"] } }' ``` ### Send itinerary by email ```bash theme={null} curl --request POST \ --url 'https://api.obvlo.com/v2/orgs/YOUR_ORG_ID/chat?key=YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "message": "", "action": "sendEmail", "email": "guest@example.com", "itinerary": { "name": "Weekend in London", "durationDays": 2, "days": [] } }' ``` ## Example chat response ```json theme={null} { "message": "Here are a few cocktail bars worth trying tonight.", "listings": [ { "id": "listing-1", "name": "Swift Soho", "category": "bar", "address": "12 Old Compton Street, London", "geoDistance": 420, "googleRating": 4.7, "priceLevel": 2, "openNow": true, "photo": { "url": "https://cdn.example.com/swift.jpg" }, "googleMapsUrl": "https://maps.google.com/?q=swift+soho" } ], "guides": [ { "id": "guide-1", "name": "Best Cocktail Bars", "description": "A curated shortlist of standout bars.", "coverImage": { "url": "https://cdn.example.com/guide.jpg" }, "listingCount": 8, "geoDistance": 380 } ], "toolUsed": true } ``` ## Related GET route for guide cards Guide cards in the chat UI can lazy-load their associated listings through the companion route below: ```http theme={null} GET /v2/orgs/{orgId}/chat?guideId={guideId}&lang={lang} ``` ### Guide listings example ```bash theme={null} curl --request GET \ --url 'https://api.obvlo.com/v2/orgs/YOUR_ORG_ID/chat?key=YOUR_API_KEY&guideId=YOUR_GUIDE_ID&lang=en-GB' \ --header 'accept: application/json' ``` ### Guide listings response ```json theme={null} { "listings": [ { "id": "listing-1", "name": "Bar Termini", "category": "bar", "address": "7 Old Compton Street, London", "geoDistance": 0, "googleRating": 4.6, "priceLevel": 2, "openNow": null, "photo": { "url": "https://cdn.example.com/bar-termini.jpg" }, "googleMapsUrl": "https://maps.google.com/?q=bar+termini" } ] } ``` ## OpenAPI ````yaml POST /v2/orgs/{orgId}/chat openapi: 3.0.3 info: title: Obvlo Content Engine description: Obvlo Content Engine API version: 4.0.0 servers: - url: https://api.obvlo.com security: [] paths: /v2/orgs/{orgId}/chat: post: tags: - AI Chat description: >- Conversational AI endpoint for destination recommendations, itinerary generation, and itinerary email delivery. operationId: v2Chat parameters: - name: orgId in: path required: true description: Organization Account Number schema: type: string requestBody: required: true description: Chat request payload. content: application/json: schema: type: object properties: message: default: '' type: string orgId: type: string lang: type: string location: type: string latlng: type: string profileId: type: string conversationHistory: type: array items: type: object properties: role: type: string enum: - user - assistant content: type: string required: - role - content additionalProperties: false action: default: chat type: string enum: - chat - createItinerary - sendEmail preferences: type: object properties: tripType: type: string userCategory: type: string interests: type: array items: type: string additionalProperties: false sessionId: type: string fingerprintId: type: string isInitialSearch: type: boolean email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ itinerary: {} durationDays: type: number minimum: 1 maximum: 7 required: - message - action additionalProperties: false responses: '200': description: Success content: application/json: schema: type: object properties: message: type: string listings: type: array items: type: object properties: id: type: string name: type: string category: type: string address: type: string geoDistance: type: number googleRating: type: number priceLevel: type: number openNow: type: boolean nullable: true photo: type: object properties: url: type: string required: - url additionalProperties: false nullable: true googleMapsUrl: type: string required: - id - name - category - address - geoDistance - googleRating - priceLevel - openNow - photo - googleMapsUrl additionalProperties: false guides: type: array items: type: object properties: id: type: string name: type: string description: type: string coverImage: type: object properties: url: type: string required: - url additionalProperties: false nullable: true listingCount: type: number geoDistance: type: number required: - id - name - description - coverImage - listingCount - geoDistance additionalProperties: false toolUsed: type: boolean actions: type: array items: type: object properties: id: type: string label: type: string value: type: string type: type: string enum: - query - tripType - userCategory - interest - confirm - email required: - id - label - value - type additionalProperties: false hostInterests: type: array items: type: object properties: id: type: string name: type: string travellerTypes: type: array items: type: string required: - id - name - travellerTypes additionalProperties: false itinerary: type: object properties: name: type: string durationDays: type: number summary: type: string days: type: array items: type: object properties: dayNumber: type: number summary: type: string activities: type: array items: type: object properties: timeOfDay: type: string enum: - morning - afternoon - evening - night activityType: type: string placeType: type: string enum: - listing - location placeId: type: string placeName: type: string rationale: type: string placePhoto: type: string travelTime: type: number listing: type: object properties: id: type: string name: type: string category: type: string address: type: string geoDistance: type: number googleRating: type: number priceLevel: type: number openNow: type: boolean nullable: true photo: type: object properties: url: type: string required: - url additionalProperties: false nullable: true googleMapsUrl: type: string required: - id - name - category - address - geoDistance - googleRating - priceLevel - openNow - photo - googleMapsUrl additionalProperties: false location: type: object properties: id: type: string name: type: string address: type: string description: type: string geoDistance: type: number photo: type: object properties: url: type: string required: - url additionalProperties: false nullable: true googleMapsUrl: type: string required: - id - name - address - description - geoDistance - photo - googleMapsUrl additionalProperties: false required: - timeOfDay - activityType - placeType - placeId - placeName additionalProperties: false required: - dayNumber - activities additionalProperties: false required: - name - durationDays - days additionalProperties: false required: - message - listings - guides - toolUsed additionalProperties: false '400': description: No matches security: - api_key: [] components: securitySchemes: api_key: type: apiKey name: key in: query ````