Skip to main content
POST
/
v2
/
orgs
/
{orgId}
/
chat
cURL
curl --request POST \
  --url 'https://api.obvlo.com/v2/orgs/{orgId}/chat?key=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "",
  "action": "chat"
}
'
{
  "message": "<string>",
  "listings": [
    {
      "id": "<string>",
      "name": "<string>",
      "category": "<string>",
      "address": "<string>",
      "geoDistance": 123,
      "googleRating": 123,
      "priceLevel": 123,
      "openNow": true,
      "photo": {
        "url": "<string>"
      },
      "googleMapsUrl": "<string>"
    }
  ],
  "guides": [
    {
      "id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "coverImage": {
        "url": "<string>"
      },
      "listingCount": 123,
      "geoDistance": 123
    }
  ],
  "toolUsed": true,
  "actions": [
    {
      "id": "<string>",
      "label": "<string>",
      "value": "<string>",
      "type": "query"
    }
  ],
  "hostInterests": [
    {
      "id": "<string>",
      "name": "<string>",
      "travellerTypes": [
        "<string>"
      ]
    }
  ],
  "itinerary": {
    "name": "<string>",
    "durationDays": 123,
    "days": [
      {
        "dayNumber": 123,
        "activities": [
          {
            "timeOfDay": "morning",
            "activityType": "<string>",
            "placeType": "listing",
            "placeId": "<string>",
            "placeName": "<string>",
            "rationale": "<string>",
            "placePhoto": "<string>",
            "travelTime": 123,
            "listing": {
              "id": "<string>",
              "name": "<string>",
              "category": "<string>",
              "address": "<string>",
              "geoDistance": 123,
              "googleRating": 123,
              "priceLevel": 123,
              "openNow": true,
              "photo": {
                "url": "<string>"
              },
              "googleMapsUrl": "<string>"
            },
            "location": {
              "id": "<string>",
              "name": "<string>",
              "address": "<string>",
              "description": "<string>",
              "geoDistance": 123,
              "photo": {
                "url": "<string>"
              },
              "googleMapsUrl": "<string>"
            }
          }
        ],
        "summary": "<string>"
      }
    ],
    "summary": "<string>"
  }
}
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

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.
actionPurpose
chatDefault conversational search and recommendation flow.
createItineraryBuilds a day-by-day itinerary from the active profile and preferences.
sendEmailSends a previously generated itinerary to an email address.

​
Required path and query parameters

ParameterInTypeDescription
orgIdpathstringOrganisation ID for the request.
keyquerystringPublic API key for the organisation.

​
Common request fields

FieldTypeDescription
messagestringUser message for the chat turn. Use "" when triggering a non-text action.
profileIdstringOptional host profile context for search and itinerary generation. Required for createItinerary.
langstringOptional BCP-47 language code for response content.
latlngstringOptional lat,lng user location override.
conversationHistoryarrayPrior user and assistant messages.
preferencesobjectOptional guided-discovery preferences: tripType, userCategory, interests.
sessionIdstringOptional client session identifier for tracking.
fingerprintIdstringOptional end-user fingerprint identifier for tracking.
isInitialSearchbooleanOptional hint to randomise initial recommendation ranking.

​
Example requests

​
Chat for recommendations

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

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

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

{
  "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
}
Guide cards in the chat UI can lazy-load their associated listings through the companion route below: 
GET /v2/orgs/{orgId}/chat?guideId={guideId}&lang={lang}

​
Guide listings example

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

{
  "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"
    }
  ]
}

Authorizations

​
key
string
query
required

Path Parameters

​
orgId
string
required

Organization Account Number

Body

application/json

Chat request payload.

​
message
string
default:""
required
​
action
enum<string>
default:chat
required
Available options:
chat,
createItinerary,
sendEmail
​
orgId
string
​
lang
string
​
location
string
​
latlng
string
​
profileId
string
​
conversationHistory
object[]
​
preferences
object
​
sessionId
string
​
fingerprintId
string
​
isInitialSearch
boolean
​
email
string<email>
Pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
​
itinerary
any
​
durationDays
number
Required range: 1 <= x <= 7

Response

Success

​
message
string
required
​
listings
object[]
required
​
guides
object[]
required
​
toolUsed
boolean
required
​
actions
object[]
​
hostInterests
object[]
​
itinerary
object