Shortcuts and campaigns

All paths below are relative to the Public API base URL. Send X-Api-Key on every request and Content-Type: application/json on JSON writes. Legacy unscoped keys cannot use these routes.

Shortcuts and categories

A shortcut stores a reusable answer in an existing category. Use the category ID returned by the category endpoint; IDs belong to your authenticated store.

All successful shortcut operations return 200. Read examples below omit timestamps and other stored fields. GET and DELETE requests have no body.

Shortcut writes accept name, answer, and categoryId. Creating one requires categoryId; updates preserve omitted fields. A category change must point to an existing category in this store. Deleting a category does not delete its shortcuts: move or remove them first if you do not want orphaned category references.

GET /shortcuts supports exact name, categoryIds as a URL-encoded JSON array, and sortOrder. Lists use limit (default 20), after (the last ID from the preceding page), or before (the first ID from the following page). pagination.hasNext and pagination.hasPre indicate available pages. hasCount=true adds total and pagination.totalPage. The list also includes each shortcut's shortcutId and category data.

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

Campaigns

Create a draft, inspect it, then publish with explicit confirmation. Saving with status: "active" is rejected; use the publish operation instead.

GET responses use 200. Campaign object examples show only the relevant fields. Creation adds priority, counters, and timestamps; the create request above is a minimal inactive draft. Configure its content and targeting before publishing.

Writable campaign fields are status, templateId, name, priority, condition, trigger, message, appearance, contentMessageType, and quickQuestions, plus template-specific labels: viewSimilarButton, askAboutItButton, viewProductButton, shopNowButton, subscribeButton, skipButton, headerText, itemsInCartText, viewCartButton, and completeOrderButton. Start from GET /campaigns/{id} for the desired template's nested objects, copy the writable fields, and change only what you intend to save. Nested objects are stored as supplied; do not assume a partial nested patch preserves every sibling.

Template IDs are welcome_message, search_page, subscribe_newsletter, product_recommendation, cart_booster, cart_remove_item, abandoned_cart_reminder, browser_collection_page, smart_product_page, and view_cart. Changed trigger.displayOn values are validated against the template. Publishing Cart booster, Abandoned cart reminder, or View cart requires Pro or above on current pricing; Browser collection page requires a paid plan. Existing grandfathered plans keep their entitlement.

Campaign lists support status, sort, limit, after, before, and hasCount. The default order is priority ascending. search selects the campaign search path; keep its returned pagination rather than assuming it has the same cursor shape. List rows include triggered, interacted, addToCart, and revenue counters.

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

Publishing activates the campaign and updates the storefront's published campaigns. Review the draft before sending this request.

priority must be a finite number; a lower number comes first. POST /campaigns/reorder sets the priority of up to 200 campaigns at once. Every ID must belong to your store, or nothing changes and the route returns 400 VALIDATION_FAILED with Invalid campaign. Only id and priority are saved.

POST /campaigns/defaults creates the default campaigns of your current plan that the store does not have yet, after the existing ones. ids lists what it created, or is empty when nothing was missing; calling it again does not create duplicates. The defaults are welcome_message, product_recommendation and search_page on every plan, plus browser_collection_page from Basic, plus cart_booster and abandoned_cart_reminder from Pro.

Errors and write outcomes

These endpoints retain their resource-specific envelopes; they do not all use error.code. Shortcut persistence and every campaign write, including failed attempts, record the authenticated actor in the audit trail. This does not make writes idempotent: repeating a create can create another resource.

MCP exposes reads through get_shortcuts and get_campaigns, and writes through manage_shortcuts and manage_campaigns. Use the MCP tool reference for action inputs and server availability.