Shortcuts and campaigns

以下のパスは Public API base URL からの相対パスです。各リクエストに X-Api-Key、JSON を送る書き込みには Content-Type: application/json を付けます。スコープのない旧キーでは利用できません。

Shortcuts とカテゴリ

Shortcut は、繰り返し使う回答を既存のカテゴリに保存する機能です。カテゴリのエンドポイントが返す ID を使ってください。ID は認証されたストアに属します。

Shortcut の操作は成功時にすべて 200 を返します。以下の読み取り例では、日時など一部の保存項目を省略しています。GET と DELETE のリクエストに本文は不要です。

Shortcut の書き込みには name、answer、categoryId を指定できます。作成時には categoryId が必要です。更新で省略したフィールドは維持されます。カテゴリを変更する場合は、同じストア内に存在するカテゴリを指定してください。カテゴリを削除しても、その中の Shortcut は削除されません。参照先がなくなることを避けるには、先に Shortcut を移動または削除してください。

GET /shortcuts は、完全一致の name、URL エンコードした JSON 配列の categoryIds、sortOrder に対応しています。一覧では limit（既定値 20）、after（前ページの最後の ID）、before（次ページの先頭の ID）を使用します。pagination.hasNext と pagination.hasPre は前後のページの有無を示します。hasCount=true を指定すると total と pagination.totalPage が追加されます。一覧には各 Shortcut の shortcutId とカテゴリのデータも含まれます。

curl --get 'https://app.chatty.net/v1/shortcuts' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  --data-urlencode 'categoryIds=["category_123"]' \
  --data-urlencode 'limit=20'

Campaigns

まず下書きを作成し、内容を確認してから明示的な確認付きで公開してください。status: "active" を指定した保存は拒否されます。公開用の操作を使用してください。

GET は 200 を返します。Campaign のオブジェクト例には関連するフィールドだけを示しています。作成時には優先順位、カウンター、日時が追加されます。上記の作成例は最小限の非アクティブな下書きです。公開前に内容と表示対象を設定してください。

変更できるフィールドは status、templateId、name、priority、condition、trigger、message、appearance、contentMessageType、quickQuestions です。テンプレート固有のラベルとして、viewSimilarButton、askAboutItButton、viewProductButton、shopNowButton、subscribeButton、skipButton、headerText、itemsInCartText、viewCartButton、completeOrderButton も指定できます。対象テンプレートの入れ子のオブジェクトは GET /campaigns/{id} で取得し、変更可能なフィールドをコピーして必要な箇所を編集してください。入れ子のオブジェクトは送信した形で保存されます。一部だけ送った場合に、同階層のほかの値が必ず維持されるとは限りません。

テンプレート ID は welcome_message、search_page、subscribe_newsletter、product_recommendation、cart_booster、cart_remove_item、abandoned_cart_reminder、browser_collection_page、smart_product_page、view_cart です。trigger.displayOn を変更すると、テンプレートに合う値か検証されます。現行料金体系で Cart booster、Abandoned cart reminder、View cart を公開するには Pro 以上、Browser collection page には有料プランが必要です。旧プランの継続利用条件は維持されます。

Campaign の一覧は status、sort、limit、after、before、hasCount に対応しています。既定では優先順位の昇順です。search を指定すると検索用の処理になるため、同じカーソル形式とは決めつけず、返されたページネーション情報を使用してください。各行には triggered、interacted、addToCart、revenue のカウンターも含まれます。

curl -X POST 'https://app.chatty.net/v1/campaigns/campaign_123/publish' \
  -H 'X-Api-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -H 'Content-Type: application/json' \
  -d '{"confirm":true}'

公開すると Campaign がアクティブになり、ストアフロントの公開済み Campaign が更新されます。リクエストを送る前に下書きを確認してください。

priority は有限の数値である必要があり、数値が小さいほど先に表示されます。POST /campaigns/reorder は、最大 200 件の Campaign の優先順位を一度に設定します。すべての ID がストアに属している必要があり、そうでない場合は何も変更されず、ルートは 400 VALIDATION_FAILED と Invalid campaign を返します。保存されるのは id と priority だけです。

POST /campaigns/defaults は、現在のプランの既定の Campaign のうちストアにまだないものを、既存の Campaign の後ろに作成します。ids には作成したものが入り、不足がなかった場合は空になります。再度呼び出しても重複は作成されません。既定の Campaign は、すべてのプランで welcome_message、product_recommendation、search_page、Basic 以上で browser_collection_page、Pro 以上で cart_booster と abandoned_cart_reminder です。

エラーと書き込み結果

レスポンスの外側の形式はリソースごとに異なり、すべてが error.code を返すわけではありません。Shortcut の保存操作とすべての Campaign の書き込み（失敗した試行を含む）では、認証された実行者が監査記録に残ります。ただし、書き込みが冪等になるわけではありません。作成を繰り返すと別のリソースができる場合があります。

MCP の読み取りには get_shortcuts と get_campaigns、変更には manage_shortcuts と manage_campaigns を使用します。各 action の入力と認証方式別の利用可否は MCP tool reference をご覧ください。