Settings and features

Read your store's settings, discover writable fields, and apply a small patch. These endpoints use the Public API base URL, without the /chat prefix.

Shared request and response rules

Send JSON with Content-Type: application/json on writes. Successful requests return HTTP 200. GET requests have no body. Read responses use data, except the field catalog, which returns fields and total. Settings PATCH responses return changed, an array of actual differences:

{
  "changed": [
    {"field": "enableLiveChat", "before": false, "after": true}
  ]
}

An unchanged patch returns {"changed":[]}. A field that was not stored can omit before. Settings PATCH requests accept at most 50 fields. Use the field catalog to check types, enum values, ranges, and write permissions before sending a patch. Do not send an entire GET response as a widget patch.

The error table at the end applies to all endpoints below. All routes in this page use the Pro / Plus API-key access described above.

Widget settings

Read examples show a subset of stored fields. /settings returns public widget settings only; the collection endpoints below return the other settings. Missing stored fields are omitted rather than filled with catalog defaults.

Supported widget domains are root, appearance, aiAgent, availability, prechatContact, tracking, and internalFlags (inbox, team and email options). ai-agent and prechat-contact are accepted aliases. An unknown domain returns {"data":{}}.

Use flat V2 field paths for widget writes:

curl -X PATCH 'https://app.chatty.net/v1/settings' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"aiAgent.persona.name":"Store assistant"}'

{
  "changed": [
    {"field": "aiAgent.persona.name", "before": "Assistant", "after": "Store assistant"}
  ]
}

Object-valued fields are merged into the stored object: sending only {"aiAgent.storeAvailability":{"outOfStockMessage":"Ask us about stock"}} keeps the stored enabled value. Arrays inside them, and top-level arrays, are replaced.

Some widget fields have extra rules:

Enabling enableAIAssistant also enables enableLiveChat. Disabling enableLiveChat also disables the AI assistant. A patch that enables the AI assistant while disabling live chat fails with COUPLING_CONFLICT. The response includes coupled fields that actually changed.

Discover fields

GET /settings/fields — scope settings:read, Pro / Plus. Optional query parameters:

For example, request /settings/fields?collection=similarMatchingSettings with no body:

{
  "fields": [
    {
      "collection": "similarMatchingSettings",
      "domain": "shop",
      "path": "similarMatchingSettings.forceSimilarByTags",
      "type": "boolean",
      "default": false,
      "description": "Limits similar-product matching to configured priority tags.",
      "affects": "agent-behavior",
      "writeScope": "settings.shop:write",
      "public": true
    }
  ],
  "total": 1
}

The catalog lists 257 fields. A filter with no matches returns {"fields":[],"total":0}. A field without a writeScope is read-only. The catalog also contains fields owned by other resources; use the matching resource endpoint, not /settings, to write them.

Collection settings

Each GET below requires settings:read. Each PATCH requires its own scope. All use Pro / Plus. Read examples and object-valued before/after examples are excerpts: retain existing values when editing object settings.

Collection writes accept the nested shape inside the GET response's data, or dotted catalog field names. Do not include the data wrapper. Do not supply the same field in both forms; that fails validation.

Arrays replace the previous array. In particular, an empty shopSettings.markets clears the market list, and an empty notification emails array clears recipients. Read first and send the complete intended array. Notification and satisfaction settings are object-valued catalog fields; their changed entries compare the whole stored object, including stored metadata. Object fields are merged into the stored object, as for widget writes.

• Product quiz needs the store on Pro or higher, or the PATCH returns 403 PLAN_LIMIT. Writable fields are enabled, collectionScope ({"type":"all"} or {"type":"specific","collectionIds":[...]}), maxQuestions (3, 5 or 7), numRecommendations (1, 2 or 3) and intentTriggers (phrases that offer the quiz).
• FAQ page accepts its content and appearance fields, such as header, description, the color fields, theme, layout, banner fields and faqPageCustomCss, as well as customUrl and SEO fields. contactUs takes header and url (up to 500 characters), description (up to 1,000), action (chatbox or anotherTab) and display. A change is translated into your languages and published to the storefront.
• Similar matching also accepts similarityPriorityTags, a list of tags that is trimmed and kept to the first 50. Unset fields read as their defaults.

Use the field catalog for the full list of paths, types and defaults.

Shop preferences and store locations

Shop preferences hold store-wide email and widget options. PATCH accepts any of these fields, and at least one:

GET also returns emailSender, which is read-only. An empty body, an unknown field or a wrong type returns 400 VALIDATION_FAILED.

The locations route lists the store's active Shopify locations, so you can pick them for the AI agent's store availability answers (aiAgent.storeAvailability). city appears when the address has one. The list is cached for 10 minutes. If Shopify cannot be reached, the route returns 502 UPSTREAM_ERROR; retry later.

Market overrides

Use overrides to give a Shopify market a different AI name or shop name. Only aiAgent.persona.name and appearance.shopName can be overridden. Other settings continue to use their store-wide values.

All three routes use Pro / Plus. GET returns the markets, current overrides, and supported fields. Example excerpt:

{
  "data": {
    "markets": [{"marketId":"market_123","handle":"international","name":"International","primary":false}],
    "overrides": [],
    "overridableFields": ["aiAgent.persona.name", "appearance.shopName"]
  }
}

Replace market_123 with a marketId returned by GET. PUT merges the supplied fields into that market's existing override and leaves other markets unchanged:

PUT /settings/market-overrides/market_123
X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json
 
{"aiAgent.persona.name":"Store assistant"}

{"success":true,"marketId":"market_123","updatedFields":["aiAgent.persona.name"]}

PUT requires a known market and a nonempty patch. It returns MARKET_NOT_FOUND if the market is missing or the stored market list needs to be refreshed. Refresh the shop's market configuration before retrying.

DELETE /settings/market-overrides/market_123 removes that override so the market uses store-wide settings again:

{"success":true,"marketId":"market_123","removed":true}

Deleting an absent override succeeds with removed: false.

Product recommendations

Recommendations tell the AI which products to suggest for given search terms. These routes use knowledge:read for reads and knowledge:write for writes, with a Pro / Plus key. Bodies and queries are strict: an unknown field returns 400 VALIDATION_FAILED.

Examples are excerpts.

• Create and update. title is required on creation (1–500 characters). searchTerms holds up to 50 terms. products and collections are lists of up to 1,000 IDs; they are stored in conditions.productIds and conditions.collectionIds. PATCH needs at least one field and merges conditions with the stored value.
• List. limit is 1–100 (default 20). sort is updatedAt, createdAt or title with _asc or _desc (default updatedAt_desc). Page with after (the last ID of this page) or before. hasCount=true adds total and pagination.totalPage. Only your own recommendations are listed.
• Templates. special_occasions and sale_promotion are built-in templates. GET returns the template until you save it; PATCH saves it with your changes; DELETE hides it.
• Toggle. Turns up to 200 recommendations, templates or meta tags on or off at once. If any ID is unknown, nothing changes and the route returns 404 NOT_FOUND.
• Meta tags. best_selling and newest are the two supported tags; any other value returns 404 NOT_FOUND. A tag that was never saved starts with enabled and smartSyncEnabled set to true; reading it saves those defaults.
• Shopify settings. enableRelated and enableComplementary turn Shopify's related and complementary product suggestions on or off. Unset values read as true.

An unknown or foreign recommendation ID returns 404 NOT_FOUND. Every write is recorded in the audit log.

Feature toggles

Features group the setting fields needed for one capability. Use these endpoints when you want to turn a capability on or off without assembling its patch yourself.

All four routes use Pro / Plus. Available keys:

GET /features/live_chat returns:

{"data":{"key":"live_chat","enabled":false,"fields":["enableLiveChat"],"settings":{"enableLiveChat":false}}}

GET /features returns data as an array of these objects, one per key. A multi-field feature is enabled only when all of its fields are true.

POST /features/live_chat/enable, when live chat was off, returns:

{"changed":[{"field":"enableLiveChat","before":false,"after":true}]}

POST /features/live_chat/disable, when live chat was on and the AI assistant was already off, returns:

{"changed":[{"field":"enableLiveChat","before":true,"after":false}]}

The AI/live-chat coupling described above also applies to these actions. ai_mode changes the shop field enableAiMode and returns the same changed format. An unknown key returns 404 NOT_FOUND.

Errors

Error responses use {"error":{"code":"…","message":"…"}}, optionally with details. See Errors and rate limits for shared version and rate-limit behavior.

A validation error can identify each rejected field:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "One or more settings fields are invalid",
    "details": {
      "fields": [{"field":"enableLiveChat","code":"INVALID_TYPE","expected":"boolean"}]
    }
  }
}

MCP and audit records

MCP exposes widget patches through update_settings, collection updates through update_settings_resource, shop preferences through update_shop_preferences, market overrides through manage_market_overrides, feature changes through set_feature, and recommendations through manage_recommendations. get_settings_resource reads shop preferences (shop_preferences) and store locations (store_availability_locations). Each tool/action enforces the same scope as its REST operation. Settings, preference, override and recommendation writes carry the authenticated actor into mutation audit records, including failed attempts; clients do not supply their own actor identity. See MCP tool reference for inputs and authentication availability.