Product Agents settings¶

Read and change a website's Product Agent setup: the shared tone of voice, the test email addresses, and each agent's state, channels, prompt, price-drop thresholds and product filters. These are the same settings the Product Agents pages edit, so validation and audit logging behave identically.

Channels themselves — creating a Klaviyo connection, renaming one, wiring webhooks, deleting — stay in my.helloretail.com. Here you point an agent at a channel by its id, which you get from productAgents_getChannels. Nearly every website has a single channel that every agent sends through, so in practice there's one id to use.

Tips & tricks

Read the settings first — the response tells you which agents exist, what state they're in and which channel ids they use.

Show me the Product Agent settings for my website, and which agents are active.

Every update is a patch. Only the arguments you pass change, so you can adjust one thing without restating the rest.

Set the tone of voice for my Product Agents to friendly and concise, but keep everything else as it is.

Turning an agent on needs a channel that already has that agent's flow wired up in Klaviyo. You don't have to name the channel. With only one on the website, your assistant looks up the id itself.

Turn on the Replenishment Reminder agent on my website.

Agents¶

An agent is identified by its messageType. There are seven, in two categories:

`messageType`	Name	Category
`REPLENISHMENT_REMINDER`	Replenishment Reminder	`POST_CONVERSION`
`SIMILAR_PRODUCT_RECOMMENDATIONS`	Alternative Picks	`POST_CONVERSION`
`ACCESSORY_RELATED_PRODUCT_UPSELL`	Recommended Addons	`POST_CONVERSION`
`PRICE_DROP_VIEWED_PRODUCT`	Viewed Product	`PRICE_DROP`
`PRICE_DROP_PURCHASED_REPLENISHMENT`	Purchased Replenishment	`PRICE_DROP`
`PRICE_DROP_ALTERNATIVE_PRODUCT`	Alternative Product	`PRICE_DROP`
`PRICE_DROP_COMPLEMENTARY_PRODUCT`	Complementary Product	`PRICE_DROP`

minPctDrop and minAbsoluteDrop only apply to the PRICE_DROP category; on the others they come back null. An agent that has never been configured is reported as DISABLED with empty channels and no prompt.

productAgents_getSettings¶

Read a customer website's Product Agent settings: the shared tone of voice, the test email addresses, and one row per agent (message type) with its state, the channels it sends through, its custom prompt, whether follow-ups are allowed, its price-drop thresholds and its global product filters. availableProductFilters lists the product fields a global filter may be built on. Resolve channel ids to names with productAgents_getChannels.

Name	Type	Required	Description
`websiteUuid`	string	Yes	The UUID of the customer's website in Hello Retail. Use `website_getInfo` to look up available websites, or find it in my.helloretail.com under Settings → Website Settings → Website Unique Id.

Example request & response

Example requestReturns

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "productAgents_getSettings",
    "arguments": {
      "websiteUuid": "{website uuid}"
    }
  }
}

{
  "toneOfVoice": "<string>",
  "testEmailAddresses": ["<string>"],
  "agents": [
    {
      "messageType": "REPLENISHMENT_REMINDER",
      "displayName": "Replenishment Reminder",
      "category": "POST_CONVERSION",
      "state": "ACTIVE",
      "enabledChannelIds": ["<string>"],
      "customPrompt": "<string>",
      "allowFollowups": true,
      "minPctDrop": null,
      "minAbsoluteDrop": null,
      "globalFilters": [
        {
          "key": "<string>",
          "operator": "IN",
          "value": "<string>"
        }
      ]
    }
  ],
  "availableProductFilters": ["<string>"]
}

productAgents_updateSettings¶

Write operation

This tool changes the settings shared by every agent on the website. Your assistant will ask for confirmation before this runs.

Update a customer website's shared Product Agent settings — the tone of voice used when generating message copy, and the addresses test messages are sent to. Only the arguments you pass are changed. Per-agent settings are changed with productAgents_updateAgent. Returns the full settings afterwards, in the same shape as productAgents_getSettings.

Name	Type	Required	Description
`websiteUuid`	string	Yes	The UUID of the customer's website in Hello Retail. Use `website_getInfo` to look up available websites, or find it in my.helloretail.com under Settings → Website Settings → Website Unique Id.
`toneOfVoice`	string	No	Tone of voice for generated message copy, as free text. Omit to keep the current value.
`testEmailAddresses`	array of string	No	The full list of test email addresses, replacing the stored one. Pass an empty list to remove all of them. Omit to keep the current list. An invalid or duplicated address rejects the whole call.

Example request & response

Example requestReturns

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "productAgents_updateSettings",
    "arguments": {
      "websiteUuid": "{website uuid}",
      "toneOfVoice": "Friendly and concise, never pushy.",
      "testEmailAddresses": ["{test email}"]
    }
  }
}

{
  "toneOfVoice": "Friendly and concise, never pushy.",
  "testEmailAddresses": ["{test email}"],
  "agents": [],
  "availableProductFilters": ["<string>"]
}

productAgents_updateAgent¶

Write operation

This tool turns agents on and off and changes what they send. Activating an agent means live messages start going out. Your assistant will ask for confirmation before this runs.

Update one Product Agent (message type) on a customer website: turn it on or off, choose the channels it sends through, set its custom prompt, allow or block follow-up messages, set its price-drop thresholds, or replace its global product filters. Only the arguments you pass are changed. Returns the full settings afterwards, in the same shape as productAgents_getSettings.

Activating an agent requires at least one ACTIVE channel that has the agent's flow wired up; otherwise the call is rejected with the reason.

Name	Type	Required	Description
`websiteUuid`	string	Yes	The UUID of the customer's website in Hello Retail. Use `website_getInfo` to look up available websites, or find it in my.helloretail.com under Settings → Website Settings → Website Unique Id.
`messageType`	string	Yes	The agent to update — one of the seven values in Agents.
`state`	string	No	`ACTIVE` turns the agent on, `DISABLED` turns it off. Omit to keep the current state.
`enabledChannelIds`	array of string	No	The full list of channel ids this agent sends through, replacing the stored one. Every id must be an ACTIVE channel, from `productAgents_getChannels`. On a single-channel website that list is that one id. Omit to keep the current channels, though an agent that has never been configured has none, so activating it the first time means passing one.
`customPrompt`	string	No	Extra prompt text for this agent, overriding the shared tone of voice. Pass an empty string to clear it. Omit to keep the current prompt.
`allowFollowups`	boolean	No	Whether this agent may send follow-up messages. Omit to keep the current value.
`minPctDrop`	integer	No	Price-drop agents only: the smallest price drop that triggers a message, in percent — a whole number between 2 and 80. Omit to keep the current value.
`minAbsoluteDrop`	number	No	Price-drop agents only: the smallest price drop that triggers a message, as an absolute amount in the website's currency (zero or greater). Omit to keep the current value.
`globalFilters`	array of object	No	The full list of global product filters for this agent, replacing the stored one. Each filter is `{"key", "operator", "value"}`; keys come from `availableProductFilters` and the operator is one of `EQUALS`, `NOT_EQUALS`, `GREATER_THAN`, `LESS_THAN`, `IN`, `NOT_IN`, `ALL`. Pass an empty list to remove all filters. Omit to keep the current filters.

Example request & response

Turn an agent onThresholds and filtersReturns

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "productAgents_updateAgent",
    "arguments": {
      "websiteUuid": "{website uuid}",
      "messageType": "REPLENISHMENT_REMINDER",
      "state": "ACTIVE",
      "enabledChannelIds": ["{channel id}"]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "productAgents_updateAgent",
    "arguments": {
      "websiteUuid": "{website uuid}",
      "messageType": "PRICE_DROP_VIEWED_PRODUCT",
      "minPctDrop": 15,
      "globalFilters": [
        {
          "key": "brand",
          "operator": "IN",
          "value": "Nike,Adidas"
        }
      ]
    }
  }
}

{
  "toneOfVoice": "<string>",
  "testEmailAddresses": ["<string>"],
  "agents": [
    {
      "messageType": "REPLENISHMENT_REMINDER",
      "displayName": "Replenishment Reminder",
      "category": "POST_CONVERSION",
      "state": "ACTIVE",
      "enabledChannelIds": ["{channel id}"],
      "customPrompt": null,
      "allowFollowups": true,
      "minPctDrop": null,
      "minAbsoluteDrop": null,
      "globalFilters": []
    }
  ],
  "availableProductFilters": ["<string>"]
}