AI Chat (Preview)

cURL

curl --request POST \
  --url 'https://api.obvlo.com/v2/orgs/{orgId}/chat?key=' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "",
  "action": "chat"
}
'

import requests

url = "https://api.obvlo.com/v2/orgs/{orgId}/chat?key="

payload = {
    "message": "",
    "action": "chat"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({message: '', action: 'chat'})
};

fetch('https://api.obvlo.com/v2/orgs/{orgId}/chat?key=', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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>"
    }
  ],
  "hostInterests": [
    {
      "id": "<string>",
      "name": "<string>",
      "travellerTypes": [
        "<string>"
      ]
    }
  ],
  "itinerary": {
    "name": "<string>",
    "durationDays": 123,
    "days": [
      {
        "dayNumber": 123,
        "activities": [
          {
            "activityType": "<string>",
            "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>"
  }
}

POST

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"
}
'

import requests

url = "https://api.obvlo.com/v2/orgs/{orgId}/chat?key="

payload = {
    "message": "",
    "action": "chat"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({message: '', action: 'chat'})
};

fetch('https://api.obvlo.com/v2/orgs/{orgId}/chat?key=', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "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>"
    }
  ],
  "hostInterests": [
    {
      "id": "<string>",
      "name": "<string>",
      "travellerTypes": [
        "<string>"
      ]
    }
  ],
  "itinerary": {
    "name": "<string>",
    "durationDays": 123,
    "days": [
      {
        "dayNumber": 123,
        "activities": [
          {
            "activityType": "<string>",
            "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.

`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

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[]

Show child attributes

preferences

object

Show child attributes

sessionId

string

fingerprintId

string

isInitialSearch

boolean

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

Show child attributes

guides

object[]

required

Show child attributes

toolUsed

boolean

required

actions

object[]

Show child attributes

hostInterests

object[]

Show child attributes

itinerary

object

Show child attributes

Language Reference

Get v2orgs chat

⌘I

Getting started

API

API reference

Widget implementation

Microsite implementation

Infrastructure guides

Language support

Preview

Overview

Base route

Preview notes

POST action modes

Required path and query parameters

Common request fields

Example requests

Chat for recommendations

Create an itinerary

Send itinerary by email

Example chat response

Guide listings example

Guide listings response

Authorizations

Path Parameters

Body

Response

​Overview

​Base route

​Preview notes

​POST action modes

​Required path and query parameters

​Common request fields

​Example requests

​Chat for recommendations

​Create an itinerary

​Send itinerary by email

​Example chat response

​Related GET route for guide cards

​Guide listings example

​Guide listings response

Authorizations

Path Parameters

Body

Response

Overview

Base route

Preview notes

POST action modes

Required path and query parameters

Common request fields

Example requests

Chat for recommendations

Create an itinerary

Send itinerary by email

Example chat response

Related GET route for guide cards

Guide listings example

Guide listings response