Settings と機能

ストアの設定を取得し、書き込み可能なフィールドを確認して、必要な項目だけ更新できます。これらのエンドポイントは Public API のベース URL を使用します。/chat は付けません。

リクエストとレスポンスの共通ルール

書き込み時は Content-Type: application/json を指定し、JSON を送信します。成功時は HTTP 200 を返します。GET リクエストにボディは不要です。読み取り結果は data に入りますが、フィールドカタログは fields と total を返します。設定の PATCH は、実際に変わった内容を changed 配列で返します。

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

変更がなければ {"changed":[]} を返します。保存されていなかったフィールドでは before が省略されることがあります。設定の PATCH で指定できるのは最大 50 フィールドです。送信前にフィールドカタログで型、列挙値、範囲、書き込み権限を確認してください。ウィジェットの更新には GET レスポンス全体を送らないでください。

ページ末尾のエラー一覧は、以下のすべてのエンドポイントに適用されます。このページのすべてのルートでは、上記の Pro / Plus の API キーを使用します。

ウィジェット設定

読み取り例は保存済みフィールドの一部です。/settings は公開対象のウィジェット設定のみを返します。その他の設定は、以下のコレクション用エンドポイントで取得します。未保存のフィールドは省略され、カタログのデフォルト値では補完されません。

ウィジェットで指定できるドメインは root、appearance、aiAgent、availability、prechatContact、tracking、internalFlags（受信トレイ、チーム、メールのオプション）です。別名の ai-agent と prechat-contact も使用できます。存在しないドメインは {"data":{}} を返します。

ウィジェットの更新には、フラットな V2 フィールドパスを使用します。

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

オブジェクト型のフィールドは、保存済みのオブジェクトにマージされます。例えば {"aiAgent.storeAvailability":{"outOfStockMessage":"Ask us about stock"}} だけを送信しても、保存済みの enabled の値は保持されます。その中の配列や最上位の配列は置き換えられます。

一部のウィジェットフィールドには追加のルールがあります。

enableAIAssistant を有効にすると enableLiveChat も有効になります。enableLiveChat を無効にすると AI アシスタントも無効になります。AI アシスタントを有効にしながらライブチャットを無効にする更新は、COUPLING_CONFLICT で失敗します。レスポンスには、連動して実際に変わったフィールドも含まれます。

フィールドを確認する

GET /settings/fields — スコープは settings:read、プランは Pro / Plus です。以下のクエリパラメーターは任意です。

例えば、ボディなしで /settings/fields?collection=similarMatchingSettings をリクエストします。

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

カタログには 257 個のフィールドがあります。一致する項目がない場合は {"fields":[],"total":0} を返します。writeScope がないフィールドは読み取り専用です。カタログには他のリソースのフィールドも含まれます。それらを更新する場合は、/settings ではなく対応するリソースのエンドポイントを使用してください。

コレクション設定

以下の GET には settings:read が必要です。PATCH には各設定の書き込みスコープが必要です。すべて Pro / Plus で利用できます。読み取り例とオブジェクトの before/after の例は抜粋です。オブジェクト設定を編集する際は、既存の値を保持してください。

コレクションの更新では、GET レスポンスの data 内と同じネスト形式、またはカタログのドット区切りのフィールド名を使用できます。data のラッパーは含めません。同じフィールドを両方の形式で送ると検証エラーになります。

配列は以前の配列全体を置き換えます。特に shopSettings.markets を空にするとマーケット一覧が削除され、通知の emails 配列を空にすると宛先が削除されます。先に読み取り、保持する要素をすべて含めて送信してください。通知と満足度調査の設定は、カタログ上ではオブジェクト型のフィールドです。変更の比較対象には、保存済みメタデータを含むオブジェクト全体が使われます。オブジェクト型のフィールドは、ウィジェットの書き込みと同様に、保存済みのオブジェクトにマージされます。

• Product quiz にはストアが Pro 以上のプランであることが必要で、そうでない場合 PATCH は 403 PLAN_LIMIT を返します。書き込み可能なフィールドは enabled、collectionScope（{"type":"all"} または {"type":"specific","collectionIds":[...]}）、maxQuestions（3、5、7）、numRecommendations（1、2、3）、intentTriggers（クイズを提案するフレーズ）です。
• FAQ page は、header、description、カラーフィールド、theme、layout、バナーフィールド、faqPageCustomCss などのコンテンツと外観のフィールドに加え、customUrl と SEO フィールドを受け付けます。contactUs には header と url（500 文字まで）、description（1,000 文字まで）、action（chatbox または anotherTab）、display を指定できます。変更は使用している言語に翻訳され、ストアフロントに公開されます。
• Similar matching は similarityPriorityTags も受け付けます。これはタグのリストで、前後の空白を除去し、先頭の 50 個までが保持されます。未設定のフィールドはデフォルト値として読み取られます。

パス、型、デフォルト値の完全な一覧は、フィールドカタログで確認してください。

ショップの環境設定とストアの所在地

ショップの環境設定には、ストア全体のメールとウィジェットのオプションが含まれます。PATCH では次のフィールドのうち少なくとも 1 つを指定でき、複数も指定できます。

GET は読み取り専用の emailSender も返します。ボディが空、未知のフィールド、または型が誤っている場合は 400 VALIDATION_FAILED を返します。

所在地のルートは、ストアで有効な Shopify のロケーションを一覧します。AI エージェントの店舗在庫の回答（aiAgent.storeAvailability）で選択するために使えます。住所に市区町村がある場合は city が含まれます。一覧は 10 分間キャッシュされます。Shopify に接続できない場合は 502 UPSTREAM_ERROR を返すため、後で再試行してください。

マーケット別の設定

Shopify のマーケットごとに、AI 名やショップ名を変更できます。上書きできるのは aiAgent.persona.name と appearance.shopName のみです。その他の設定にはストア共通の値が使われます。

3 つのルートすべてが Pro / Plus で利用できます。GET はマーケット、現在の上書き設定、対応するフィールドを返します。以下はレスポンスの抜粋です。

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

market_123 は GET が返す marketId に置き換えてください。PUT は指定したフィールドをそのマーケットの既存設定にマージします。他のマーケットは変更しません。

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 には登録済みのマーケットと、空ではない更新内容が必要です。マーケットが存在しない場合や、保存済みのマーケット一覧を更新する必要がある場合は MARKET_NOT_FOUND を返します。ストアのマーケット設定を更新してから再試行してください。

DELETE /settings/market-overrides/market_123 はそのマーケットの上書き設定を削除し、ストア共通の設定に戻します。

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

上書き設定が存在しない場合も成功し、removed: false を返します。

商品レコメンド

レコメンドは、特定の検索語に対して AI がどの商品を提案するかを指定します。これらのルートは、読み取りに knowledge:read、書き込みに knowledge:write を使い、Pro / Plus のキーが必要です。ボディとクエリは厳格で、未知のフィールドは 400 VALIDATION_FAILED を返します。

例は抜粋です。

• 作成と更新。 作成時は title が必須です（1～500 文字）。searchTerms は最大 50 個です。products と collections は最大 1,000 個の ID のリストで、conditions.productIds と conditions.collectionIds に保存されます。PATCH には少なくとも 1 つのフィールドが必要で、conditions は保存済みの値とマージされます。
• 一覧。 limit は 1～100（デフォルト 20）です。sort は updatedAt、createdAt、title のいずれかに _asc または _desc を付けたもの（デフォルト updatedAt_desc）です。ページングには after（このページの最後の ID）または before を使います。hasCount=true を付けると total と pagination.totalPage が追加されます。一覧されるのは自分のレコメンドだけです。
• テンプレート。 special_occasions と sale_promotion は組み込みのテンプレートです。GET は保存するまでテンプレートをそのまま返し、PATCH は変更内容を付けて保存し、DELETE は非表示にします。
• 切り替え。 最大 200 件のレコメンド、テンプレート、メタタグを一度にオンまたはオフにします。未知の ID が 1 つでもあると何も変更されず、404 NOT_FOUND を返します。
• メタタグ。 サポートされるタグは best_selling と newest の 2 つで、それ以外の値は 404 NOT_FOUND を返します。一度も保存されていないタグは enabled と smartSyncEnabled がともに true で始まり、読み取るとそのデフォルトが保存されます。
• Shopify 設定。 enableRelated と enableComplementary は、Shopify の関連商品と補完商品の提案をオンまたはオフにします。未設定の値は true として読み取られます。

未知の、または他のストアのレコメンド ID は 404 NOT_FOUND を返します。すべての書き込みは監査ログに記録されます。

機能の有効化と無効化

機能ごとに、必要な設定フィールドがまとめられています。更新するフィールドを個別に組み立てずに機能を有効・無効にしたい場合は、これらのエンドポイントを使用します。

4 つのルートすべてが Pro / Plus で利用できます。使用できるキーは以下のとおりです。

GET /features/live_chat のレスポンス例：

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

GET /features は、キーごとにこの形式のオブジェクトを data 配列に入れて返します。複数のフィールドを持つ機能は、すべてのフィールドが true の場合のみ有効と判定されます。

ライブチャットが無効だった場合、POST /features/live_chat/enable は次のように返します。

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

ライブチャットが有効で、AI アシスタントがすでに無効だった場合、POST /features/live_chat/disable は次のように返します。

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

これらの操作にも、上記の AI とライブチャットの連動ルールが適用されます。ai_mode はショップのフィールド enableAiMode を変更し、同じ changed 形式で返します。存在しないキーは 404 NOT_FOUND を返します。

エラー

エラーレスポンスは {"error":{"code":"…","message":"…"}} 形式で、必要に応じて details が付加されます。バージョンとレート制限の共通ルールは Errors and rate limits をご覧ください。

検証エラーには、拒否されたフィールドごとの情報が含まれる場合があります。

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

MCP と監査記録

MCP では、Widget の変更に update_settings、コレクションの更新に update_settings_resource、ショップの環境設定に update_shop_preferences、マーケット別設定に manage_market_overrides、機能の切り替えに set_feature、レコメンドに manage_recommendations を使用します。get_settings_resource は、ショップの環境設定（shop_preferences）とストアの所在地（store_availability_locations）を読み取ります。各ツール・action には対応する REST 操作と同じスコープが必要です。設定、環境設定、マーケット別設定、レコメンドの書き込みでは、失敗した試行も含めて、認証された実行者が変更の監査記録に渡されます。クライアントが独自の実行者情報を指定するものではありません。入力と認証方式別の利用可否は MCP tool reference をご覧ください。