Personyze

Open a page of the account's site with a campaign forced on — its staging version, as a first-time visitor, no staging IP needed — and check what its actions rendered: whether each appeared and how fast, where it sits (inside/after which element), its size, heading, how many items and pictures it shows, whether pictures are broken, whether it overflows the screen, errors from the tag, and whether the site elements it should replace ("hidden") are really hidden — on a desktop and on a phone, with a picture of each widget. USE THIS AFTER BUILDING OR CHANGING an in-page widget, before telling the person it is done, and on a product page that should show it. slow: true adds a run as a mid-range phone on a poor connection — where a placement that races the site's own rendering fails. Takes 30-60 seconds per device (more when slow) — say so before calling.

check_widget_on_site

What a recommendation widget on this account will run into, measured on its catalog — call it BEFORE building one, and tell the person what it finds. Works for a PRODUCT catalog and for a CONTENT catalog (articles, blog posts, pages), and says which this account has. Reports: WHAT A FILTER CAN BE WRITTEN ON — every catalog column and every field the feed adds, with how much of the catalog has a value and, where there are few, which values (a filter on a field nothing carries matches nothing, silently, which is how two widgets on our own account showed nothing for months); which image column is actually filled, because the templates default to image_big_url and it is often not the best one; how much of the catalog is in stock, priced and linked; whether sizes or variants are stored as separate products (the same product twice, and a size in every name — with the exact name function that removes it); how many items each algorithm has data for, which decides the fallback order; and real page addresses to test on. Large catalogs are sampled and it says so.

check_catalog_for_recommendations

What this account counts as a conversion, and whether each one is switched on. Read this before answering anything about conversion rate or value: an account with no goals has no conversion numbers at all, and saying "your conversion rate is 0%" when the truth is "nothing is being measured" is the wrong answer. Also read it before create_goal — there is a ceiling of 12, and a goal that already exists under another name should be reused.

list_goals

Create a new campaign in STAGING MODE. Call it "staging mode", which is what the panel calls it — saying "draft" sends people looking for a draft screen that does not exist. It is shown only to visitors arriving from a staging IP — real traffic keeps seeing whatever is live now, and the person has to publish it in the panel themselves. Say that plainly when you report back, and ALWAYS give them the returned url so they can open it — a campaign they cannot find is one they cannot publish. Optionally give targeting in plain words ("visitors on the pricing page who have not bought") and it is compiled into real rules — always read the compiled targeting back to the person, because a rule that says something slightly different from what they asked for looks identical from the outside. Ask before calling this. Creating things is not a read-only lookup.

create_campaign_draft

Create a new audience (user segment). Returns the new audience id.

create_audience

Create or update a visitor (user) profile. Provide "fields" with at least internal_id or email so the profile can be matched/deduplicated; other fields (first_name, last_name, phone, custom columns...) are merged into the existing profile (patch semantics). Returns the numeric user_id.

save_visitor

Turn the page types found by a deep site reading (rescan_site with "deep") into real page groups, so campaigns can target "the pricing page" as an object rather than as a sentence. Each group's URL rule is derived ONLY from addresses that were actually read: one observed page becomes an exact rule, several sharing a directory become a prefix rule, and a page type whose addresses have nothing in common is skipped rather than guessed at. Say which you are creating and what rule each carries before calling this. Creating a group changes nothing a visitor sees — nothing references it until an action does — but it does write to the account, so ask first. Already-named groups are left alone, so calling it twice is safe.

create_page_groups

Create a placeholder — a named page location (matched by a CSS selector) where personalization actions can render. Returns the new placeholder id. "place" decides where an action goes relative to that element, and two of its values DELETE page content: "inside" replaces everything already inside the element, and "replace" removes the element itself. For an element that already shows something — a header, a main column, a product section, a shelf — use "after" or "before", which add a sibling and remove nothing. Use "inside" only for an empty element the site added for this purpose. When unsure, "after".

create_placeholder

Turn the conversions found by a deep site reading (rescan_site with "deep") into real goals, so campaigns can be judged on outcomes instead of clicks. This is the highest-value thing to set up on an account with none. Each goal watches either a URL path the crawl actually reached or a CSS selector observed in the markup — nothing invented — and one this account already measures is skipped, so calling it twice is safe. There is a ceiling of 12 goals and this will not exceed it; it creates as many as there are slots for. Conversions are counted from the moment a goal exists and are not backfilled. Use create_goal instead when the person describes a conversion themselves. Say which you are creating first.

create_goals_from_reading

Turn the content locations found by a deep site reading (rescan_site with "deep") into real placeholders, so an action has somewhere to render other than a floating popup. Every selector was checked against the page's actual markup when the reading was stored — nothing here is composed — and a placement whose selector or name this account already has is skipped, so calling it twice is safe. Creating a placeholder changes nothing a visitor sees: it is inert until an action names it. Use create_placeholder instead when the person names a location themselves. Say which you are creating first.

create_placeholders_from_reading

Delete an audience (user segment) by id. This removes the audience definition; visitor profiles are not deleted. Returns the number of rows deleted.

delete_audience

Hide a discovered audience from the suggestions. It stays dismissed even if later passes find it again.

dismiss_discovered_audience

Copy an existing campaign, including its targeting rules, into a NEW campaign in staging mode. Works on any campaign, live or staging — the copy is always staging, so duplicating a live campaign is safe. This is the way to answer "make one like that but for X": duplicate, then use update_campaign_draft to change the name or retarget it. actions='copy' gives the new campaign its own actions to edit independently; actions='link' shares the originals, so editing one changes both — say which you used. Ask before calling. Give the person the returned url. SLOW: copying a campaign takes roughly 15-30 seconds, because every action is duplicated. Tell them it will take a moment BEFORE you call it, so the silence is expected rather than a hang, and do not call it a second time while the first is still running — that makes two copies.

duplicate_campaign

Rename a staging-mode campaign, switch it on or off, or replace its targeting rules. Only works on campaigns still in staging mode — a live one is refused, and the refusal says so. Give the person the returned url. Give targeting in plain words and it is recompiled; the compiled result comes back so you can read it to the person. Ask before calling this.

update_campaign_draft

The copy-paste HTML that puts a recommendation ACTION into an email or an external banner — the panel's Get-Code step, as a tool. This is NOT the site tracking code: when someone asks for "the email code" or "the embed code" of a campaign, this is the tool. It works for the external-media action types ("Offline email", per-item recommendation designs — the ones create_action_from_template says render per recommended item). The snippet is per-slot <a><img> tags whose images are rendered per recipient by the platform; recipients are identified by the email platform's merge tag spliced into the URLs. Pass email_platform so the tag arrives filled in; without it the snippet carries an {INSERT EMAIL HERE} placeholder and you must SAY it needs replacing. An unknown recipient gets the account's fallback items, never a broken image. This is also the flow where going live is safe: an external-media action renders nowhere until this code is pasted somewhere, so publishing its campaign changes nothing on the site.

get_email_embed_code

Every field a visitor profile can hold in this account — the built-in ones and any custom fields added here. Read this BEFORE save_visitor: that tool can only write fields that already exist, so a value sent to a field nobody defined is silently nowhere. "built_in: false" means somebody added it for this account.

list_visitor_fields

Fetch one personalization action with its editable HTML content (content_begin/content_end) and presenting rules. For a Popup Builder (canvas) design it also returns "texts": every visible text in the design (headline, subtitle, button labels, coupon code, captions) exactly as stored - those are the "find" values replace_action_text takes to put agreed copy into the design.

get_action_content

Add one web page or one piece of pasted text to the chat's knowledge, and read it immediately — the assistant can answer from it as soon as this returns. Use "url" for a page on their site (a returns policy, a delivery page, an FAQ) and "text" for something they typed or pasted at you. For a whole site use crawl_site_for_chat instead — this is one thing at a time. A page that cannot be fetched is still stored, with the reason: check "status" in the answer and say so, because a source that failed silently is a knowledge base missing a chunk of itself with nothing on screen to say so.

add_chat_knowledge

The whole state of this account's visitor chat in one answer: whether it is configured and switched on, how it is told to behave, what it has been given to read (and which of those failed to read), which campaigns put it in front of a visitor, and how much of the conversation allowance is spent. READ THIS FIRST before changing anything about the chat, and read the "note" — it names the ONE thing standing between this account and a working chat, which is usually "switched on but no campaign carries it" rather than anything in the settings. "next_steps" is the rest of the job in order, each step naming the tool that does it: work it to the end rather than stopping at the first success, because a chat that is switched on but unplaced and with nothing to read is indistinguishable from a broken one. A step with "tool": null is a screen, not something you can do — say so and link it. Answers for an account that has never set the chat up too: "configured": false is a normal state, not an error.

get_chat_setup

What tells us that a visitor looked at a product, put one in the cart, bought one, or read an article — and what is MISSING. Everything downstream rests on it: recommendations learn from views, cart targeting needs cart events, "visitors who looked at X" needs views, and a catalog nothing arrives against matches nobody. Read it before promising any of those, and before adding a source, so a second source does not start counting the same event twice. Read-only.

list_tracking_sources

Whether the tracker is actually reporting, per domain. This is what answers "I installed it, did it work" and "why is my campaign not showing" — a campaign on a domain with no traffic is not a targeting problem. "ever_tracked" is the account-level fact: false means no visit has EVER been recorded, which is a missing or broken install rather than a quiet day. The per-domain figures come from the live visit table, so they cover the last day only — a busy site that shows zero there is worth investigating, a brand-new one is not. Read-only.

check_tracking_status

Save an action's design into this account's own template gallery, so the next campaign can start from it instead of being written again. It appears in list_action_templates beside the stock designs, marked as the account's own, and create_action_from_template builds from it. Worth doing when something has been tuned until the person is happy with it and they will want it again — a house banner style, a promo strip, a form they like. Not worth doing for one-off content: a gallery of near-identical designs is worse than none, so check list_action_templates for one of theirs that already covers it and say so rather than adding another. It copies the design as it is now; later edits to the action do not reach the template, and editing the template does not touch the campaigns already built from it. Nothing a visitor sees changes. Ask before calling, and tell them the name you are saving it under.

save_action_as_template

The account's campaigns, newest first, with enough about each to FIND one from a partial memory: when it was made, who last edited it, whether it is live, and a plain-English summary of who it targets. "Copy the discount campaign Sara built in June" is answerable from this without asking them for an id. Pass "search" to match the name loosely — it is a substring match, so a remembered fragment is enough, and the summary and editor name are searched too. Offer the candidates back with their dates and targeting and let the person pick; do NOT guess between two similar names, because the wrong campaign duplicated is indistinguishable from the right one until they open it. The id matches "campaign_id" in get_campaign_performance and duplicate_campaign.

list_campaigns

List visitor user_ids that belong to an audience. Returns [{user_list_id, user_id}]. Use get_visitors with "where"="user_id:<ids>" to fetch the profiles.

list_audience_members

List the account's audiences (user segments). Returns [{id, name}]. Audience ids are used by the audience-membership tools.

list_audiences

The audiences Audience Discovery found in this account's own data: short rules that pick out visitors who reach an outcome (purchase, goal, intent, campaign click, return visit, engaged session) far more - or far less - often than average. Every number is measured on visitors the rule was not fitted on. Returns [{id, outcome, direction, rule, conditions, visitors_in_window, rate, average_rate, lift, extra_outcomes, share_of_all_converters, confidence, weeks_held, status, list_id, live_targetable}]. Use create_list_from_discovered_audience to turn one into an audience list; in the campaign editor a card can be targeted directly. Empty when the module is not switched on for the account.

list_discovered_audiences

List personalization actions (banners, popups, recommendations, email widgets, etc.). Available columns: id, name, version_tag ("production" or "testing"), type_id, placeholders (placeholder ids the action renders into), placeholder_order (its rank among the actions sharing a placeholder; null = last), content_type, content_param, content_begin, content_end (editable HTML content), presenting_rules, libs_app. Filter syntax (same as the Personyze REST API "where" path parameter): "column=value" (equals), "column!=value", "column>value", "column<value", "column>=value", "column<=value", "column:v1,v2,v3" (IN), "column!:v1,v2" (NOT IN). Join conditions with "&" for AND and "|" for OR (AND binds tighter). Values must be URL-encoded (encodeURIComponent). FOR ONE CAMPAIGN pass campaign_id instead (there is no campaign column to filter on): you get its variant groups, each group's share of traffic and split key, the actions in each group and whether they are switched on, and how much traffic is left as the control that sees nothing. That is where the actiongroup_id values set_traffic_split and add_goal_to_action need come from. TO FIND ACTIONS BY NAME OR KIND ("which recommendation widgets are running", "the newsletter bar") pass search - the where syntax has no "contains" - optionally with only_live: true.

list_actions

List placeholders — named page locations where personalization actions can render. Returns [{id, name, html_id, units_count_max}].

list_placeholders

Open a page of this account's own website in a real browser — on a desktop and on a phone — and describe it as it renders: the page's blocks as an outline, each with a CSS selector that was checked to match (and how many elements it matches), where it sits, whether its children repeat (a product shelf, a grid), and whether it was already in the server HTML; plus the framework, the data-layer events the page fired while loading, a screenshot of each device's first screen, and a close look (with a picture) at any selectors you ask about. USE THIS BEFORE CHOOSING WHERE AN IN-PAGE ACTION GOES, and before create_placeholder: selectors from the site reading come from the page source, which on React/VTEX/Next.js stores misses whole sections and the entire phone layout. Ask about candidate selectors with "focus" to confirm each matches exactly one element on both devices. Only the account's own domains can be opened. Takes 15-40 seconds per device — say so before calling.

inspect_page

The sessions of ONE visitor, newest first — how they arrived each time (source, medium, campaign, search word, referrer), where they landed, how long they stayed, and what they converted. This is the tool for "what did this visitor do before they converted", "where did this lead come from" and "how many times had they been back". Get the user_id from get_visitors (search by email or internal_id first if that is all the person has). Returns [{session_start_time, session_counter, url_host_port, url_path, referrer_type, referrer_host_port, search_word, ad_source, ad_medium, ad_campaign, total_visits, time_total, total_n_goals, total_goal_value, country_code, city}] — empty values are omitted, so a session with no ad_source simply has no ad_source. Times are Unix timestamps. An empty list means the visitor has no archived sessions yet, not that the id is wrong.

get_visitor_activity

Open a support ticket with the human support team, and get its number back. Offer this when you genuinely cannot help: a question about something outside the account data you can read, something that looks broken, billing, or an answer you are not confident in. Offering a ticket is a better answer than a guess — but ask before opening one, and never open one silently. Write the message yourself, in the person's own terms: what they were trying to do, what happened, and anything you already checked and ruled out, so support does not start from nothing. Say afterwards that support replies in the panel under Support Tickets.

open_support_ticket

The named sets of pages this account has defined — "Pricing pages", "Articles" — and the URL rule behind each. A page group is how "which pages" is expressed here: an action carries one, and the tracker then renders it only on pages in that group. It is NOT the same question as a placeholder, which says where ON a page something goes and cannot be attached to a page at all. Read this before suggesting that something run "only on the pricing page" — if a group already says that, use it rather than describing it in words. Returns [{id, name, rule}].

list_page_groups

Switch ONE personalization action on or off inside its campaign. Unlike the draft tools, this takes effect for real visitors as soon as the account's JS rebuilds — pausing stops that action being shown, resuming starts it again. Nothing else about the campaign changes, and it is fully reversible by calling this again. ALWAYS confirm before calling it, and confirm in concrete terms: name the action, name the campaign it is in, and say plainly that live visitors stop (or start) seeing it. "Shall I pause it?" is not enough — the person should be able to tell from your question exactly what will change on their site. One action per call. If asked to pause several, confirm and call it once per action, naming each; never treat "pause the campaign" as licence to switch off everything in it without saying so first. Use list_actions to find the action, and get_campaign_performance if asked to pick by results.

set_action_active

Call any Personyze REST API object directly, for anything the dedicated tools don't cover. Objects: ab_test, account, actions, articles, conditions, containers_grab_variable, current_notification, events, forms, goals, placeholders, products, products_interactions, products_stats_1day, products_stats_2day, products_stats_4day, products_stats_week, products_stats_recent, products_stats_all, sessions_archive, summary_actions, tracker_code, user_interests, user_list_users, user_lists, users, users_columns. "path" is the URL part after /rest/<object>/ — key/value segments like "where/<filter>/columns/<c1,c2>/order_by/<col>/limit/<n>" or a bare numeric id. Filter syntax (same as the Personyze REST API "where" path parameter): "column=value" (equals), "column!=value", "column>value", "column<value", "column>=value", "column<=value", "column:v1,v2,v3" (IN), "column!:v1,v2" (NOT IN). Join conditions with "&" for AND and "|" for OR (AND binds tighter). Values must be URL-encoded (encodeURIComponent). "body" is the JSON payload for post/put. Docs for each object: https://personyze.com/wiki/rest:start

personyze_api

Per-product counters — how often each product was viewed, delivered in a recommendation, favourited, and how often it reached its goal (a purchase, on most accounts). Use this for "best sellers", "most viewed products" and similar. Counters come from fixed rolling windows, not an arbitrary date range: choose the closest one and say which you used. Returns internal_id (the product id in your catalog) plus n_viewed, n_delivered, n_extra, n_favorite, n_goal. Join to product names with the "products" object via personyze_api when needed.

get_product_stats

What visitors asked that the assistant had to say it did not know, grouped by question and counted. The best input there is for deciding what to add to the knowledge base, because it is the customers' own words rather than a guess at what might be missing. A natural follow-up is add_chat_knowledge for whatever answers the most-asked of them.

list_chat_gaps

Queue every page source to be fetched again, so the knowledge tracks a site whose content changed. Pasted text and uploaded files are left alone — they have no source to re-read from. Also the way to retry pages that failed: a source in error is re-queued along with the rest.

refresh_chat_knowledge

Look at the account's own website again and refresh what we know about it: which of our integrations it already runs, and its brand colours and font. Use this when someone asks to re-check their site, says their site has changed or been redesigned, or when a recommendation about their site looks out of date. Fields the customer has set by hand are never overwritten — say so if they ask. Takes several seconds; tell them it is running before you call it. Set "analyze" to also READ the page and work out what the business is, who it sells to and what it runs on — do that when somebody asks what we know about their site, or when you need to suggest something specific to their business rather than to software in general. It spends AI allowance; the plain scan does not. Set "deep" to follow the home page's own links and read up to five pages instead of one — the pricing page, a product page, the signup page. That is what produces a MAP of the site: what each page is for, CSS positions where content could actually go, and what would be worth counting as a conversion. Slower (around half a minute) and it spends more allowance, so say what it will do before calling it; but on a site whose home page is a poster, a login wall or a language chooser it is the difference between a reading and a guess. Afterwards, call list_recommendations again: the findings change what is worth suggesting.

rescan_site

The settings of an action built from a gallery template — every control its editor sidebar has (colours, CSS style slots, switches, texts, layout, badges, buttons, which catalog column feeds each field) with its current value, and for a recommendation widget its algorithm, fallbacks, filters, item count and the title shown per algorithm. Read this before change_widget_settings. With no section or find it returns an outline: one line per control, "key: Name = value" (values cut at 40 characters). Pass "find" (words from a control's name, e.g. "badge style") or "section" for full values, choices and descriptions — best match first. Names the widget's heading control, whatever the template calls it, and for a recommendation with a filter says how many items of the catalog that filter keeps (a sample: it is how a widget that shows nothing is spotted without opening the site). Pass algorithms: true for the recommendation algorithms this widget can use, with their options.

get_widget_settings

Find the pages of a site — from its sitemap where there is one, from the home page's links where there is not — and queue them for the chat to read. The fastest way to make a new chat useful. QUEUED, NOT READ: discovery is immediate but each page is fetched afterwards by a background job, so report it as "queued N pages, readable over the next few minutes" and use get_chat_setup to see how many are still pending. Up to 200 pages, 40 by default. Ask before calling: it opens a lot of connections to somebody's web server.

crawl_site_for_chat