# Your Account Source: https://docs.getchatads.com/guides/account-management Profile, sign-in, personal data export, and account deletion Team-wide settings (widget configuration, billing, members) live with your [team](/guides/team-management); the **Account** page holds what's personal to you. To open it, click the **gear icon** in the top-right of the dashboard and choose **Account**. ## Profile & Sign-In The **Profile Information** card holds your display name. Your email address is your sign-in identity and can't be edited from the dashboard; if you need to change it, [contact support](mailto:team@getchatads.com). ChatAds uses **passwordless sign-in**: there's no password to set or reset. Enter your email on the sign-in page and click the magic link we send you. ## MCP Data Connector Key MCP Data Connector Key card showing a masked personal key with show, copy, and reset controls Your **MCP Data Connector Key** (`uk_...`) is a personal, read-only credential for pulling your widget's usage, conversations, and click data into Claude or any MCP client - see the [MCP Data Connector](/guides/mcp-data-connector) guide for setup. It's tied to you, not the team, so each teammate uses their own. Treat it like a password. If it leaks, click **Reset Key**: the old key stops working immediately and a new one is issued. ## Support User ID The **Support User ID** card shows the identifier for your individual login. Include it (or your [Team ID](/guides/team-management#team-name--team-id)) when contacting support so we can locate your account without back-and-forth. ## Exporting Your Personal Data The **Data Export** card downloads everything ChatAds stores about you personally - your profile, team memberships, and activity history - as a JSON file, per GDPR's data-portability right (Article 20). Team-level data has its own export on the [Team page](/guides/team-management#exporting-team-data). ## Deleting Your Account Delete Account card explaining that deletion removes you from all teams, deletes personal data within 30 days, and cancels subscriptions Deleting your account removes you from all teams and deletes your profile and personal data, per GDPR's right to erasure (Article 17). You'll be asked to type your email address to confirm. Teams you belonged to keep running for their remaining members. Two things to know before you click: * **You can't delete your account while you're the only owner of a team.** Promote another teammate to Owner first, or [delete the team](/guides/team-management#deleting-your-team). * **There's a 30-day grace period.** Your account is scheduled for deletion rather than wiped instantly; if you change your mind, log back in and click **Restore My Account** on the banner. After 30 days, deletion is permanent. If you just want to leave a specific team while keeping your account, ask a team owner or admin to remove you from the members table. # Affiliate Disclosure & Compliance Source: https://docs.getchatads.com/guides/affiliate-disclosure What ChatAds does for affiliate compliance automatically, and what stays your responsibility Affiliate links carry disclosure obligations - from the FTC (in the US), from Google's link-spam guidelines, and from the affiliate programs themselves. ChatAds handles the technical layer automatically; site-level disclosure remains yours. ## What ChatAds Does Automatically * **`rel="sponsored"` on paid links.** Every ChatAds-inserted Amazon link and every scraped on-page affiliate link is written with `rel="noopener sponsored"`, which is exactly what Google asks for on compensated links. Non-affiliate page links get plain `rel="noopener"`. * **A visible "Sponsored" label.** Sponsored links show a "Sponsored" label on hover, so readers can tell a compensated link from an editorial one. * **A standing notice in the widget.** When enabled, the chat panel footer reads "Links may include affiliate offers". * **No dark patterns.** Links are inserted in-line around the product phrase the AI already wrote; ChatAds never injects standalone ads, popups, or links the AI didn't naturally mention. ## What Stays Your Responsibility 1. **A site-level affiliate disclosure.** The FTC expects a clear and conspicuous disclosure near affiliate content. Most publishers add a short notice on pages that contain affiliate links, for example: > *This site contains affiliate links. We may earn a commission when you purchase through these links, at no extra cost to you.* 2. **Amazon's Operating Agreement.** If you use Amazon monetization, Amazon requires Associates to identify themselves on their site, typically with the statement: > *As an Amazon Associate I earn from qualifying purchases.* Review the [Operating Agreement](https://affiliate-program.amazon.com/help/operating/agreement) for the current requirements - it's your Associates account and your relationship with Amazon. 3. **Your privacy policy.** Disclose the chat assistant itself - see [Privacy & Data](/guides/privacy-and-data#what-your-privacy-policy-should-mention). This page is practical guidance, not legal advice. Disclosure rules vary by country and program; when in doubt, check with the program or a professional. # Analytics & Conversations Source: https://docs.getchatads.com/guides/analytics Usage charts, the click log export, and conversation transcripts ChatAds tracks widget activity in two dashboard tabs: **Usage** (aggregate metrics and the click log) and **Conversations** (full chat transcripts). ## Usage The Usage tab shows: * **Daily pacing** - today's message count against your plan's daily limit, with a progress bar. * **Usage chart** - page loads, messages, and affiliate link clicks over time, with day or month granularity and preset timeframes (today through year-to-date). Widget usage chart with page loads, messages, and clicks series over a 30-day range ## Click Log Export The Usage tab also offers a CSV export with one row per link click inside AI replies, covering the last 90 days (up to 10,000 rows, newest first). Use it to reconcile ChatAds clicks against your affiliate network reporting. | Column | What it is | | ------------------ | -------------------------------------------------------------------------------- | | `created_at` | When the link was clicked (UTC) | | `page_url` | Page the reader was chatting on | | `anchor_text` | The link text inside the AI reply | | `href` | Destination URL of the link | | `sponsored` | `true` for ChatAds sponsored links, `false` for your own scraped affiliate links | | `source` | Affiliate source, derived from the link URL (Amazon, Skimlinks, CJ, etc.) | | `country` | Reader country (ISO code, derived from IP - the raw IP is not stored) | | `browser_language` | Reader browser language (Accept-Language) | | `session_id` | Chat session the click came from | ## Conversations The Conversations tab shows full transcripts of what visitors asked and how the AI answered, grouped into sessions, newest first. You can search across them or expand any conversation to read the whole back-and-forth. Expanded conversation showing reader questions and AI answers with affiliate links Use transcripts to see what your readers actually ask, spot content gaps, and tune your [starter questions](/guides/customization#starter-questions) or [custom prompt](/guides/customization#custom-prompt). ### Logging, Retention, and Export * Logging is on by default. Turn it off with the "Log conversations" toggle at the top of the tab - new messages stop being stored immediately. * Visitor messages are PII-stripped before storage (emails, phone numbers, and similar are removed). * The list shows the latest 100 conversations; search covers the latest 1,000 messages. * A "Download CSV" button exports up to 10,000 messages from the last 90 days. * Logs are retained for 90 days, then deleted automatically - export the CSV if you want to keep them long-term. See [Privacy & Data](/guides/privacy-and-data) for the full picture of what ChatAds stores and for how long. ## Query It from an MCP Client Everything above is also queryable in plain language from Claude, Cursor, or any MCP client via the read-only [MCP Data Connector](/guides/mcp-data-connector). # Plans & Billing Source: https://docs.getchatads.com/guides/chatads-billing ChatAds widget tiers, daily message limits, and how billing works ## Plans ChatAds has three plans, managed from the **Plan & Billing** tab in the dashboard. The main differences are the daily message limit, how much of each page the assistant reads, and widget branding: | Plan | Price | Messages / Day | Page Context | Widget Branding | | -------- | ------- | -------------- | ------------ | -------------------------- | | Free | \$0 | 100 | 1,000 words | "Powered by ChatAds" shown | | Pro | \$29/mo | 500 | 1,500 words | "Powered by ChatAds" shown | | Business | \$59/mo | 1,500 | 2,000 words | Branding removed | Plan comparison showing Free, Pro, and Business tiers with messages per day and branding differences All plans include the full feature set: customization, page context, conversation logs, usage analytics, and built-in product monetization - paid plans just read more of each page. You keep 100% of any affiliate commissions on every plan. The daily message limit is a team-wide cap on widget chats, enforced server-side and reset at midnight UTC. See [Rate Limits & Screening](/guides/rate-limits) for what visitors see when the limit is reached. Need more than 1,500 messages/day? [Contact us](mailto:team@getchatads.com?subject=ChatAds%20Enterprise) about an enterprise plan. ## How Billing Works Paid plans are billed monthly, in advance, on the 1st of each month (UTC). Only the team **owner** can change plans or payment methods - see [Team & Roles](/guides/team-management#roles--permissions). ### Upgrading Upgrades take effect immediately. You're charged a prorated amount for the remainder of the current month, then the full plan price on the 1st. If the prorated amount comes to less than \$1, we skip the immediate charge and simply bill you on the 1st. If you upgrade on the 1st itself before that day's renewal has billed, you're instead charged the full new-plan price right away, and no separate renewal charge follows. If the upgrade payment fails, your plan is not changed - update your card on file and try again. ### Downgrading or Canceling Downgrades and cancellations are scheduled, not immediate: your current plan stays active through the end of the month, and the new (lower or free) plan starts on the 1st. You won't be charged again in the meantime. A pending scheduled change is shown on the Plan & Billing tab, and you can cancel it any time before it takes effect. ### Payment Method Cards are processed by Stripe; ChatAds never stores your card details. If you remove your card, your paid plan stays active through the end of the month and then switches to Free. ### Invoices Every charge generates an invoice you can download as a PDF from the Plan & Billing tab. If a payment fails, the invoice is marked unpaid and a Retry button appears - fix your card and retry from there. # Monetization Source: https://docs.getchatads.com/guides/chatads-monetization How ChatAds turns chat replies into affiliate revenue, and every control that shapes it ChatAds offers two independent, opt-in ways to monetize chat. You can enable either, both, or neither from the **Monetize** tab: * **Amazon Affiliate Links** ("Enable ChatAds to Find Amazon Affiliate Links for You") - ChatAds scans AI responses for product mentions, finds a matching Amazon product, and inserts the link (wrapped around the product phrase) as the AI types. Requires an Amazon Associates tag. * **Affiliate Link Scraping** ("Enable On-Page Affiliate Link Scraping") - ChatAds reuses the affiliate links *already on your page*. When the AI mentions a product one of your existing on-page affiliate links points to, that link is inserted in-line. No Amazon tag required. Monetize tab showing the on-page affiliate link scraping toggle and the Amazon affiliate links toggle Monetization is opt-in. If you enable neither, ChatAds still works as a content-aware site chat widget. Either way, adding in-text product links is free and you keep 100% of any affiliate commissions. Here's what a monetized reply looks like - the product phrase becomes an in-line link, marked "Sponsored" on hover: Widget reply recommending a Lodge cast iron grill pan with an in-line affiliate link ## Amazon Affiliate Links To enable Amazon monetization, open the **Monetize** tab and toggle on **Enable ChatAds to Find Amazon Affiliate Links for You**, then add your Amazon Associates tag. Without a tag, no links are inserted, and the dashboard shows a warning until you add one. See [Amazon Associates Setup](/partners/amazon-affiliates) for a step-by-step walkthrough, including creating an account from scratch. Sponsored links currently point to Amazon US, so your US tag is the one that matters: `.com` links use the US tag. UK and other marketplaces are planned. Create a dedicated tracking ID for ChatAds traffic (e.g. `mystore-chatads-20`) so you can attribute conversions separately in your Associates reporting. Turning this toggle on automatically creates a linked ChatAds API key (named "ChatAds Monetization") behind the scenes. It powers the Amazon link lookups and requires no setup from you. If that key is ever deleted or revoked, monetization is disabled automatically and the Monetize tab shows a "Monetization disabled" notice with a one-click Re-enable button. ## Affiliate Link Scraping Affiliate Link Scraping reuses the affiliate links that already exist on your page instead of generating new ones. When the AI's reply mentions a product that one of your on-page affiliate links points to, ChatAds inserts that link in-line - you keep 100% of the commission, and no Amazon Associates tag is required. Recognized affiliate link types include: * **Amazon** - Associate-tagged product links * **Affiliate networks** - direct inline-redirect links from CJ, Awin, ShareASale, Impact, Rakuten, Pepperjam, Geniuslink, Avantlink, Howl, Affilizz, GeoRiot, Partnerize, Next2, Kickbooster, and Target's and Walmart's own affiliate redirects * **Page-level redirect tools** - pre-wrapped links from Skimlinks, VigLink, and Sovrn * **`rel="sponsored"` links** - any anchor you've marked with the `sponsored` rel attribute * **Tracked links** - links carrying common affiliate tracking parameters (e.g. `clickref`, `aff_id`, `subid`, `ranMID`) * **Cloaked links** - first-party redirect paths like `/go/`, `/recommends/`, or `/out/`, as created by plugins such as ThirstyAffiliates, Pretty Links, Lasso, and AAWP Using an affiliate partner we don't yet recognize? [Let us know](mailto:team@getchatads.com?subject=Affiliate%20Partner%20Scraping%20Request) and we'll add it. Turning scraping on also lets ChatAds surface external (off-site) product links found on the page, but only when a page-level affiliate redirect tool (Skimlinks, VigLink, or Sovrn) is detected - without one, an external link earns nothing, so only same-site links insert. Links to domains that never monetize (Reddit, Wikipedia, YouTube, and other social/reference sites) are always skipped. See [Page Links](#page-links) below for exactly which links insert under each toggle combination. ## Ad Controls Product pushiness, brand pushiness, daily ad frequency cap, and sponsored links per reply settings ### Product Pushiness Controls how often the AI works product mentions into its replies. Appears once either monetization toggle is on, and applies to both Amazon links and scraped page links. * `low` - mentions products only when the visitor asks about finding or buying something * `medium` (default) - mentions a product whenever it would genuinely help the answer * `high` - proactively works a relevant product into answers whenever the topic allows ### Brand Pushiness Separately from *how often* a product is mentioned, this controls *how assertively* the assistant names a specific brand versus a generic product phrase. * `standard` (default) - names a specific brand only when a visitor is clearly buying; stays generic while they explore * `high` - leads with a specific real brand and model even while a visitor is just exploring; still never invents a model it isn't sure exists ### Sponsored Links per Reply How many ChatAds sponsored links can appear in a single reply: 1 (the default) or 2. Applies only to ChatAds-sourced Amazon links, not to scraped page links. ### Daily Ad Frequency Cap Limits how many monetized replies the same visitor sees in a day (1 to 50; no cap by default; tracked in the visitor's browser, resets daily). For example, set a cap of 5 to make sure regular readers aren't shown sponsored links all day. Scraped page links and your own internal links are not affected - the cap counts ChatAds sponsored links only. ## Offer Quality Controls Allowed and excluded offer categories plus minimum price, review, and star rating filters ### Category Inclusion / Exclusion Set rules for which product categories are allowed to appear: 1. An automotive content site might set Allowed Categories to just "Automotive", ensuring only automotive products are shown. 2. If affiliate links are incorrectly matching pet items, add "Pet Supplies" as an excluded category. Excluding categories is more permissive than defining an allowed list. Our AI may auto-populate your excluded categories over time to improve performance. ### Product Quality Filters ChatAds only recommends products with a price of \$20+, a review count of 10+, and a star rating of 3.5+. Cheap, poorly-reviewed products make bad affiliate offers, so these floors maximize commissions. You can raise (never lower) the thresholds from the Monetize tab: minimum price up to $50/$100/\$500, minimum reviews up to 500, and minimum rating up to 4.0 or 4.5 stars. ### Auto-Blocked Categories Independent of your own rules, ChatAds automatically excludes categories that tend to be low-value or noisy for affiliate revenue: Accessories, Apps & Games, Books, Collectibles, Digital & Physical Media, Gift Cards, Grocery, Scientific & Industrial, Software, and Tobacco, Alcohol, & Other Sensitive Products. The full list is shown at the bottom of the Monetize tab. These cannot be re-enabled. ## Country & Language Targeting Country targeting toggle for the US marketplace, English-only language targeting, and auto-blocked category chips Sponsored Amazon links currently support the **Amazon US** marketplace, and ads are shown for **English-language** text only. Traffic from other countries and non-English requests is automatically filtered out; on-page scraped links continue to insert regardless. Support for the UK and additional marketplaces and languages is planned. ## Page Links Beyond affiliate links, ChatAds also surfaces regular product links already on your page - for example, internal review links - when the AI mentions a matching product phrase. These insert in addition to ChatAds offers, not instead of them. Behavior by toggle state: 1. **Both ON:** ChatAds Amazon offers insert first, then up to 10 matching page links - your on-page affiliate links take priority, then external page product links (only when a page-level redirect tool is present), then internal page product links. Each product phrase is linked at most once, highest priority wins. 2. **Amazon ON, Scraping OFF:** ChatAds Amazon offers insert. Your own internal page product links still insert for matched product phrases. On-page affiliate links and external page product links are skipped. 3. **Amazon OFF, Scraping ON:** No ChatAds offers. Your on-page affiliate links and internal page product links insert for matched phrases (up to 10 per reply); external page product links insert only when a page-level redirect tool is detected. 4. **Both OFF:** ChatAds still links to products on your own site when they appear in the AI's response (internal page product links only, up to 10 per reply). On-page affiliate links, external links, and ChatAds offers are all skipped. How page links are labeled depends on their type: * **Scraped affiliate links** (your on-page Amazon and affiliate network links) are treated like ad units: they show a "Sponsored" label on hover and their clicks are tracked in your usage charts, the same as ChatAds offers. * **Page product links** (your own internal or external non-affiliate links) are styled as normal links - no "Sponsored" label and no click tracking. Neither type counts against your daily ad cap - only ChatAds offers do. ## Tracking Your Earnings ChatAds never takes a cut of commissions, so earnings live in your affiliate accounts (e.g. Amazon Associates reporting). On the ChatAds side, the [Usage tab](/guides/analytics) tracks every inline link click and offers a per-click CSV export you can reconcile against your affiliate network reporting. # Installation Source: https://docs.getchatads.com/guides/chatads-setup Install the ChatAds widget on any platform in minutes ChatAds installs with a single script tag. You add it once, and everything else - appearance, monetization, page rules - is managed server-side from the [dashboard](https://app.getchatads.com), so you never have to touch your site's code again. ## Step 1: Get Your Widget Key ChatAds authenticates your widget with a key that starts with `cwk_`. New accounts already have one waiting for you, so you just need to copy it. 1. Log into [app.getchatads.com](https://app.getchatads.com) 2. Open the **Settings** tab 3. Copy your widget key and embed snippet Embed Snippet card in the ChatAds dashboard with a copyable script tag ## Step 2: Add the Snippet to Your Site Paste the snippet into your site's HTML, ideally just before the closing `` tag: ```html theme={null} ``` The script also works with the `defer` or `async` attribute if you prefer to load it from the ``. See [Performance](/guides/performance) for load-behavior details. The easiest route is the official [ChatAds plugin](https://wordpress.org/plugins/chatads/) - you paste your widget key instead of the snippet, and there's nothing to keep in sync when new widget features ship. **Option A: Official ChatAds plugin (recommended)** 1. In your WordPress admin, go to **Plugins > Add New**, search for **ChatAds**, and install it 2. Activate the plugin 3. Go to **Settings > ChatAds**, paste your widget key (starts with `cwk_`), and save **Option B: Code-insertion plugin** 1. Install a header/footer script plugin, e.g. [WPCode](https://wordpress.org/plugins/insert-headers-and-footers/) 2. Go to the plugin's header/footer settings screen 3. Paste the snippet into the **Footer** field and save **Option C: Google Tag Manager** If GTM is already installed on the site, use the **Google Tag Manager** tab in this guide instead - no plugin needed. Pasting the snippet directly into `footer.php` via Appearance > Theme File Editor also works, but theme updates or switching themes can wipe it out. The plugin or GTM route survives theme changes. 1. In your site admin, go to **Settings > Advanced > Code Injection** 2. Paste the snippet into the **Footer** field 3. Save Code injection requires a Squarespace Business plan or higher. 1. Open **Site Settings > Custom Code** 2. Paste the snippet into the **Footer Code** field 3. Save and publish Custom code requires a paid Webflow site plan. 1. Go to **Settings > Custom Code** in your site dashboard 2. Click **Add Custom Code**, paste the snippet 3. Set it to load on **All pages**, placed in **Body - end** 4. Apply Custom code requires a Wix premium plan with a connected domain. 1. Go to **Settings > Code injection** 2. Paste the snippet into **Site footer** 3. Save 1. Create a new **Custom HTML** tag 2. Paste the snippet as the tag's HTML 3. Set the trigger to **All Pages** 4. Publish the container If you only want the widget on articles, use ChatAds [page rules](/guides/widget-configuration#page-rules) rather than GTM triggers - rules update instantly without republishing your container. ## Step 3: Verify It's Working 1. Open any page on your site. The launcher pill (default label "Ask AI") appears in the bottom corner within a moment of the page finishing loading. 2. Open the widget and send a test question. 3. Check the **Usage** tab in the dashboard - your message and click appear immediately; page loads are batched, so give them a minute or two to show up in the daily counts. If the launcher doesn't appear, the widget is deliberately hiding itself: the most common causes are an Allowed Domains list that doesn't include the site, page rules that exclude the current path, or the English-browsers-only setting. [Why isn't the widget showing?](/guides/widget-messages#why-isnt-the-widget-showing-at-all) walks through every case. ## Step 4: Lock It Down Before going live, add your production domain(s) to **Allowed Domains** on the Settings tab. With an empty allowlist, any site can embed your widget key and consume your daily message allowance. See [Widget Configuration](/guides/widget-configuration) for domains, page rules, and visitor limits. ## Managing Your Widget Key You can reset your key from the Settings tab if it is ever misused. Regenerating the key invalidates your current embed snippet immediately - your widget stops working until you deploy the new snippet, so update your site right away. Widget keys are visible in your page source by design (like any client-side analytics or chat tag). The key only works on domains in your allowlist, is limited to widget chat, and cannot read your account data or settings. ## Next Steps Allowed domains, page rules, mobile and language controls, visitor limits. Colors, welcome message, starter questions, and the AI's behavior. Amazon affiliate links, on-page link scraping, or both. Daily message caps, burst protection, and message screening. # Commerce Extract MCP Source: https://docs.getchatads.com/guides/commerce-extract Extract scored product and purchase-intent mentions from any text over one MCP tool ## Overview Commerce Extract MCP is an **extraction-only** MCP tool. Give it any block of text - an AI reply, an article, a support thread - and it returns the product and purchase-intent mentions it found, each with a brand label when one was named, a confidence score, and the exact character offsets of the phrase. It's the same extraction engine that powers the ChatAds widget, exposed on its own for builders who already have their own chat, agent, or commerce stack. `find_commerce_opportunities` resolves nothing: no affiliate offers, no product pages, no prices, no catalog lookups - you get the signal and decide what to do with it. When you want a phrase turned into a shoppable listing, that's the companion tool on the same server: [Commerce Match](/guides/commerce-match). Want both steps done for you on a full AI reply, offers and all? That's [Commerce Insert](/guides/commerce-insert). **English only.** The extraction engine is built and tuned for English text. Non-English content generally returns few or no opportunities, so don't rely on it for other languages. This is a **different server** from the [MCP Data Connector](/guides/mcp-data-connector). That one is read-only access to your own widget data with a `uk_` user key. This one takes a `cak_` team access key and analyzes text you send it. ## Get Your Access Key Commerce Extract MCP authenticates with a team **access key** (`cak_...`) in the `x-api-key` header. 1. Log into [app.getchatads.com](https://app.getchatads.com) 2. Open **Commerce Extract** 3. In the **Access Keys** card, click **Create Key** Access Keys card in its empty state, with a Create Key button and a note that keys are stored using PGP encryption You can hold as many access keys as you have clients - one per MCP client is a good default, so you can revoke them independently. Widget keys (`cwk_...`) and user keys (`uk_...`) do not work here. ## Connect In Claude Code it's one command. Most other clients (Claude Desktop, Cursor, Windsurf, etc.) take the JSON block - drop the `transport` field if your client rejects it: ```bash Claude Code theme={null} claude mcp add --transport http chatads-commerce https://api.getchatads.com/tools/mcp/mcp --header "x-api-key: cak_your_access_key" ``` ```json JSON config theme={null} { "mcpServers": { "chatads-commerce": { "url": "https://api.getchatads.com/tools/mcp/mcp", "transport": "http", "headers": { "x-api-key": "cak_your_access_key" } } } } ``` It's a Streamable HTTP MCP server, so there's nothing to install locally and no Node or Python dependency - one URL in a config file. Restart your client and `find_commerce_opportunities` is available. The same server also carries [`find_product_matches`](/guides/commerce-match) and [`insert_product_links`](/guides/commerce-insert), so one entry gets you all three tools. ## Tool | Tool | Params | What it returns | | ----------------------------- | --------------------------------------- | --------------------------------------------------------------------- | | `find_commerce_opportunities` | `message` (required) - the text to scan | An `opportunities` array of detected product mentions, plus a `count` | Each opportunity: | Field | Type | Description | | ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `product` | string | The extracted product phrase, taken verbatim from your text | | `branded` | boolean | Whether the product phrase itself names the brand (or directly abuts it in your text) | | `brand` | string | The brand we can attach to this mention. Can be present when `branded` is `false` - see below | | `confidence` | number | Purchase-intent / extraction score from `0` to `1` - how strong a real, buy-relevant product mention this is. This is **not** a catalog match or relevance score; nothing is resolved in this mode | | `span` | array | `[start, end]` offsets of the phrase in the text you sent, counted in Unicode code points (not UTF-16 units - matters if your text has emoji or other characters outside the Basic Multilingual Plane), for inline highlighting or linking. When a product is mentioned more than once, the span points to the first occurrence. Omitted when unavailable | ### Example Calling the tool with: ```json theme={null} { "message": "The Bose QuietComfort Ultra earbuds are great for commuting, but a good laptop stand matters more for posture." } ``` returns: ```json theme={null} { "data": { "opportunities": [ { "product": "Bose QuietComfort Ultra earbuds", "branded": true, "brand": "Bose", "confidence": 0.87, "span": [4, 35] }, { "product": "laptop stand", "branded": false, "confidence": 0.43, "span": [72, 84] } ], "count": 2 }, "meta": { "request_id": "60556e82-ec0b-425b-8289-b95395db8943" } } ``` The JSON above is the text response. Clients that support MCP structured tool output also receive the `data` payload directly as structured content - the bare `{"opportunities": [...], "count": n}` object, matching the tool's declared output schema. Text with no detected purchase intent returns `"opportunities": []` with `"count": 0` - that's a success, not an error. Opportunities come back **strongest first** - ordered by internal score, not by where they appear in the text - so the first item is the best pick, not the earliest mention. Each distinct product appears once; repeated mentions are collapsed into a single opportunity. ## What `branded` and `brand` Mean They answer different questions, so you can get a `brand` without `branded`. * `branded` asks: does the phrase in `product` carry its own brand, or sit directly against it? * `brand` asks: whose product is this? A phrase that names its own brand sets both: ```text theme={null} "The Bose QuietComfort Ultra earbuds are great for commuting." { "product": "Bose QuietComfort Ultra earbuds", "branded": true, "brand": "Bose" } ``` A generic phrase the text attributes to a brand sets only `brand`: ```text theme={null} "You want a stand mixer like the KitchenAid, it lasts forever." { "product": "stand mixer", "branded": false, "brand": "KitchenAid" } ``` `product` is always verbatim from your text, so `span` keeps pointing at real characters - we never rewrite it to "KitchenAid stand mixer." If you're highlighting mentions inline, use `product` and `span`. If you're picking a link or a catalog, use `brand` and ignore `branded`. A brand mentioned merely nearby sets neither: ```text theme={null} "Just get the Ninja Creami. If you want cheaper, an immersion blender does 80% of the job." { "product": "immersion blender", "branded": false } ``` The immersion blender is the alternative to the Creami, not a Creami. Read a missing `brand` as "we have no brand claim for this phrase," not as "no brand appears nearby." ## What Gets Extracted Some rules decide what's eligible before scoring runs, so you don't have to filter for them yourself: * **Everything returned is at least two words.** Single-word mentions ("blender", "headphones") are dropped outright - too ambiguous to act on. A one-word product only comes back inside a longer phrase ("Vitamix A3500 blender"). * **Bare brand names are removed.** "Trader Joe's", "Nike", and "Costco" on their own return nothing. A brand survives only when it's attached to a product ("Patagonia Nano Puff jacket") - which is also when you get a `brand` label. * **Non-product phrases are filtered.** Service names, vague trailing phrases, and mentions in negative context ("I wouldn't buy...") are dropped before scoring. Together with the confidence floor below, that's why text full of shopping talk can still return `"count": 0`. ## Casing Is a Signal Capitalization isn't cosmetic here - it feeds both the phrase boundaries we extract and the score the mention gets. Send text cased the way a person would actually write it: * **Capitalize brand and product names.** A brand that isn't already in our brand data is recognized mostly by its casing pattern: two or more capitalized words in a row, or one capitalized word sitting next to a model number ("Kobo Clara BW", "Anker 737"). Written lowercase, the same phrase reads as generic prose and scores well below a branded mention - often under the confidence floor. * **Don't capitalize words that aren't names.** Title Case prose ("Best Wireless Headphones For Running") can read as a brand and drag a generic phrase into branded territory. * **A capital at the start of a sentence is ignored.** That's a sentence-case artifact, not a name, so a brand in that position needs a second capitalized word or a model number beside it. * **ALL CAPS and all-lowercase text carry no casing signal at all.** Headline-cased, shouty, or lowercased input returns fewer opportunities at lower confidence. Normalize it before sending if you can. ## Confidence Scores `confidence` is a proprietary score from `0` to `1`. Treat it as directionally accurate rather than a calibrated probability - it's built for ranking and thresholding mentions against each other, not for reading as "87% likely to convert." Anything below roughly **0.40** is dropped before it reaches you, so you shouldn't need your own junk filter on top. An empty `opportunities` array means nothing on the page cleared that bar. What moves the score: * **Branded vs generic.** A mention naming a real brand ("Bose QuietComfort Ultra earbuds") scores well above a bare category noun ("earbuds"). * **Proximity to a purchase-intent signal.** Recommendation language near the mention ("I'd go with", "worth buying") lifts it; a passing reference in unrelated prose doesn't. * **Location in the text.** Mentions early in the message, or set off structurally - a bullet, a numbered list, a bolded pick - score higher than ones buried mid-paragraph. * **Length and specificity.** Multi-word phrases with real modifiers beat one-word generics, which are actively penalized. * Plus a range of other signals in the scoring model. Scores move as we tune the model, so if you gate on a threshold of your own, pick one, watch your outcomes, and revisit it. Don't hardcode a value and forget it. ## Limits * **Message length:** 10,000 characters per call. * **Requests:** the free tier includes 500 requests per month. Every call counts, including ones that return zero opportunities. [Get in touch](https://www.getchatads.com/contact) to raise your cap - tell us roughly what volume you're expecting. * Commerce Extract shares one usage pool with [Commerce Match](/guides/commerce-match), [Commerce Insert](/guides/commerce-insert), and the rest of your team's API usage, and the same per-minute burst limit. Your current month's usage is shown at the top of all three tabs - same team-wide figure either way. * Your team's blocked-keyword and language content rules still apply. A message that trips one returns an empty `opportunities` array rather than an error. ## Troubleshooting ### "This tool requires a cak\_ API key" You connected with a user key (`uk_...`). Commerce Extract MCP takes a team access key (`cak_...`) - create one on the **Commerce Extract**, **Commerce Match**, or **Commerce Insert** tab. ### "Message is required" The `message` argument was missing, empty, or whitespace only. An empty message is a client error, not an empty-opportunities success. ### "Message exceeds max length" The text was over 10,000 characters. Split it and call the tool once per chunk - the `span` offsets are relative to whatever you sent, so track your own chunk offsets if you're highlighting against the full document. ### "Extraction backend temporarily unavailable - please retry" A `SERVICE_UNAVAILABLE` error means the extraction service didn't respond. It's deliberately surfaced as an error rather than silently returning zero opportunities, so a retry is safe and correct here. ### "Daily request limit exceeded" / "Monthly request limit exceeded" You've used your plan's allowance. See [Limits](#limits). ### Text clearly mentions products but returns `"count": 0` Check the casing first. Lowercased or ALL CAPS text strips the brand signal the engine leans on, and Title Case prose can push a generic phrase the wrong way - see [Casing Is a Signal](#casing-is-a-signal). After that, check [What Gets Extracted](#what-gets-extracted): single-word mentions and bare brand names are dropped by design, and anything under roughly 0.40 confidence is filtered out before you see it. ### Tool not appearing in your MCP client 1. Verify the URL is exactly: `https://api.getchatads.com/tools/mcp/mcp` 2. If your client's config uses a `transport` field, it should be `"http"` 3. Confirm the key in `x-api-key` starts with `cak_` 4. Restart your MCP client completely 5. Ask: "What tools do you have access to?" # Commerce Insert MCP Source: https://docs.getchatads.com/guides/commerce-insert The free MCP for monetizing AI-generated text with affiliate links ## Overview **The free MCP for monetizing AI-generated text with affiliate links.** Commerce Insert MCP is a **resolution + placement** MCP tool. Give `insert_product_links` a piece of AI-generated text and it returns affiliate offers to insert into it - the exact anchor text to hyperlink, its character offsets in the text you sent, and the product URL to point it at. Your text comes back unchanged; your app does the substitution. It doesn't have to be a chat reply. Anything your model wrote is fair game: * **Generated articles and roundups** - a programmatic "best running shoes" post, a buyer's guide, a product comparison * **Newsletters and email copy** - a weekly digest that names a few products * **Social posts and captions** - short-form copy with a product mention in it * **Chat and assistant replies** - the classic case: your assistant recommends something, you link it * **Product descriptions, summaries, scripts** - any generated prose where a real product gets named **Send generated text, not the prompt that produced it.** This is the single most common integration mistake. `message` is the model's *output* - the sentence that names a product - not the instruction or user question that asked for it. "Write me a post about running shoes" has nothing in it to link. It's the third tool on the same server as [Commerce Extract](/guides/commerce-extract) and [Commerce Match](/guides/commerce-match): Extract finds product mentions with no offers attached, Match turns a single phrase you already picked into a shoppable listing, and Insert does both steps end-to-end on a full passage - find the mention, resolve it, and hand back a ready-to-insert link. All three tools live on the same server behind the same `cak_` access key, so connecting once gets you all three. Unlike Commerce Match, which returns untagged URLs, Commerce Insert applies your team's own Amazon Associates tag - you earn on the links it returns. See [Set Your Amazon Affiliate Tag](#set-your-amazon-affiliate-tag). **Amazon US is the catalog live today.** There is no marketplace parameter on the tool - the catalog comes from your team's settings. This is a **different server** from the [MCP Data Connector](/guides/mcp-data-connector). That one is read-only access to your own widget data with a `uk_` user key. This one takes a `cak_` team access key and analyzes text you send it. ## Get Your Access Key Commerce Insert MCP authenticates with a team **access key** (`cak_...`) in the `x-api-key` header - the same key type Commerce Extract and Commerce Match use. If you already hold one, reuse it. 1. Log into [app.getchatads.com](https://app.getchatads.com) 2. Open **Commerce Insert** 3. In the **Access Keys** card, click **Create Key** You can hold as many access keys as you have clients - one per MCP client is a good default, so you can revoke them independently. Widget keys (`cwk_...`) and user keys (`uk_...`) do not work here. ## Set Your Amazon Affiliate Tag Insert is the one commerce tool that returns commission-bearing links, so the tag is what makes it pay. Set it under **Offer Settings** on the **Commerce Insert** tab in [app.getchatads.com](https://app.getchatads.com), alongside marketplace targeting, category rules, and product filters - those settings shape what the tool returns. * **Without a tag the tool still works**, it just returns plain, untagged Amazon URLs. Nothing errors and nothing is blocked; you simply don't earn on them. Set the tag before you ship. * **Tags are per marketplace, with no cross-marketplace fallback.** A US tag is applied to `amazon.com` links only and does nothing for `amazon.co.uk`, and vice versa. A URL whose marketplace has no tag of its own comes back untagged rather than borrowing another marketplace's. ## Connect Commerce Insert runs on the **same MCP server as Commerce Extract and Commerce Match**. If you've already connected it, `insert_product_links` is there too - skip this section. Add the server once; one entry serves all three tools. In Claude Code it's one command. Most other clients (Claude Desktop, Cursor, Windsurf, etc.) take the JSON block - drop the `transport` field if your client rejects it: ```bash Claude Code theme={null} claude mcp add --transport http chatads-commerce https://api.getchatads.com/tools/mcp/mcp --header "x-api-key: cak_your_access_key" ``` ```json JSON config theme={null} { "mcpServers": { "chatads-commerce": { "url": "https://api.getchatads.com/tools/mcp/mcp", "transport": "http", "headers": { "x-api-key": "cak_your_access_key" } } } } ``` It's a Streamable HTTP MCP server, so there's nothing to install locally and no Node or Python dependency - one URL in a config file. Restart your client and `insert_product_links` is available. ## Tool | Tool | Params | What it returns | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | `insert_product_links` | `message` (required) - the AI-generated text to monetize; `max_offers`, `max_products_per_offer` (optional) - result sizing, and your main lever on response size | A `data.status`, a `data.returned` count, and a `data.offers` array | | Param | Type | Description | | ------------------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `message` | string (required) | The **AI-generated text** you want to monetize - an article, a post, a newsletter section, an assistant reply. Pass the model's output, not the prompt that produced it. Subject to your team's configured message length limit (default 10,000 characters) | | `max_offers` | number (optional) | Maximum number of affiliate offers to return, 1-5. Default `5`. Lower it when you only want the top opportunity | | `max_products_per_offer` | number (optional) | Max products per offer carousel, 1-3. Default `3`. **Lower this to cut response size** - only `products[0].url` is the link to use, so `1` returns roughly a third of the characters (\~600 vs \~1,600 on a one-offer response) with no loss of usable data | Each offer: | Field | Type | Description | | --------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `link_text` | string | The exact phrase from your `message` to hyperlink - insert the link around this text verbatim | | `match_start` / `match_end` | number | Offsets of `link_text` in the `message` you sent, counted in Unicode code points (not UTF-16 units), so you can splice the link in without a string search. `match_end` is exclusive. Omitted when unavailable | | `is_branded` | boolean | Whether `link_text` itself names a brand | | `term_brand` | string | The brand attributed to this offer, when known | | `products` | array | One or more matching products, best pick first. `products[0].url` is the link to use | Each product carries `title`, `url`, `image`, `brand_name`, `category`, `price`, `currency`, `stars`, and `reviews`. `price` is always in USD and `currency` is always `"USD"`; for non-USD catalogs you also get `price_local`/`currency_local`, the raw catalog price and its currency. Fields with no value are omitted. ### Example Calling the tool with: ```json theme={null} { "message": "Our top pick for commuters is the Bose QuietComfort Ultra earbuds, which deliver the best noise cancellation in the category." } ``` returns: ```json theme={null} { "data": { "status": "filled", "returned": 1, "offers": [ { "link_text": "Bose QuietComfort Ultra earbuds", "match_start": 34, "match_end": 65, "is_branded": true, "term_brand": "Bose", "products": [ { "title": "Bose QuietComfort Ultra Bluetooth Earbuds...", "url": "https://www.amazon.com/dp/B0CD2FSRDD/?tag=youraffiliatetag-20", "brand_name": "Bose", "category": "Electronics" } ] } ] }, "meta": { "request_id": "60556e82-ec0b-425b-8289-b95395db8943" } } ``` Splicing that back into your text gives you: ```text theme={null} Our top pick for commuters is the [Bose QuietComfort Ultra earbuds](https://www.amazon.com/dp/B0CD2FSRDD/?tag=youraffiliatetag-20), which deliver the best noise cancellation in the category. ``` The tool returns the links, not rewritten text - you own the final copy, so you decide the markup, the placement, and whether to use a given link at all. That's what makes it drop into a publishing pipeline as easily as a chat loop. The JSON above is the text response. Clients that support MCP structured tool output also receive the `data` payload directly as structured content - the bare `{"status": ..., "returned": n, "offers": [...]}` object, matching the tool's declared output schema, the same way [Commerce Extract](/guides/commerce-extract) and [Commerce Match](/guides/commerce-match) return theirs. ## Response Statuses `data.status` tells you what happened. **Only `filled` carries offers; every other status below is a successful "nothing to link" response with an empty `offers` array, not an error - don't retry it as-is.** The one exception is `message_too_long`: shorten the message and resend, and it can succeed. `data.returned` is how many offers came back. | Status | Meaning | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `filled` | Offers came back - `data.returned` is how many | | `no_offer` | Nothing worth linking - no product mention cleared the bar, or the text isn't shopping-related | | `message_too_long` | Over your team's message length limit (10,000 characters by default). Retryable after shortening `message` - unlike the other statuses here | | `blocked_keyword` | The text tripped your team's blocked-keyword rules | | `language_not_allowed` | The detected language isn't in your team's allowed set | | `no_brand_found` | Brand-only mode is on for your team and the text names no brand | | `catalog_not_enabled` | Your team's default Amazon marketplace isn't available right now (for example Amazon UK while that marketplace is paused) - no links can be returned | The `message_too_long` cap applies to every call. Client errors - a missing `message` - come back the other way: the response has no `data` field and `error` carries a code and message. Those are worth fixing, not retrying. ## Limits * **Message length:** 10,000 characters per call by default. There is no minimum word count - a single product name is a valid message. * **Requests:** the free tier includes 500 requests per month. Every call counts, including ones that return no offers. [Get in touch](https://www.getchatads.com/contact) to raise your cap - tell us roughly what volume you're expecting. * Commerce Insert shares one usage pool with [Commerce Extract](/guides/commerce-extract) and [Commerce Match](/guides/commerce-match) and the rest of your team's API usage, and the same per-minute burst limit. Your current month's usage is shown at the top of the **Commerce Insert** tab. * Your team's blocked-keyword, language, category, and product-filter rules still apply - they're the same rules configured under **Offer Settings** on the Commerce Insert tab. Content rules surface as a `data.status`, not an error. ## Troubleshooting ### "This tool requires a cak\_ API key" You connected with a user key (`uk_...`). Commerce Insert MCP takes a team access key (`cak_...`) - create one on the **Commerce Insert**, **Commerce Extract**, or **Commerce Match** tab. ### "Message is required" The `message` argument was missing, empty, or whitespace only. An empty message is a client error, not an empty-offers success. ### The URLs come back with no `tag=` parameter Your team has no Amazon Affiliate Tag set for that marketplace, so the link is returned untagged and earns nothing. Add one under **Offer Settings** on the **Commerce Insert** tab - see [Set Your Amazon Affiliate Tag](#set-your-amazon-affiliate-tag). ### Text that clearly names a product returns `no_offer` In order of what usually fixes it: 1. **Check you sent the generated text, not the prompt.** A prompt or user question has no product mention in it to link. 2. **Check the casing.** The same extraction engine backs all three tools and capitalization is a real signal - see [Casing Is a Signal](/guides/commerce-extract#casing-is-a-signal). 3. **Check the product is in the catalog.** Amazon US today; some products legitimately aren't there. ### "Daily request limit exceeded" / "Monthly request limit exceeded" / "Per-minute rate limit exceeded" You've used your plan's allowance. See [Limits](#limits). ### "API key disabled. Contact support." Your key's team has been disabled. Email [chris@getchatads.com](mailto:chris@getchatads.com). ### Tool not appearing in your MCP client 1. Verify the URL is exactly: `https://api.getchatads.com/tools/mcp/mcp` 2. If your client's config uses a `transport` field, it should be `"http"` 3. Confirm the key in `x-api-key` starts with `cak_` 4. Restart your MCP client completely 5. Ask: "What tools do you have access to?" # Commerce Match MCP Source: https://docs.getchatads.com/guides/commerce-match Turn a product phrase into shoppable merchant listings over one MCP tool ## Overview Commerce Match MCP is a **resolution-only** MCP tool. Give `find_product_matches` a single product phrase and it returns up to three matching product listings, best pick first - title, image, brand, category, and a product page URL you can link straight to. Every match resolves against the catalog of a merchant you already work with, and the `url` comes back untagged, so you append your own affiliate tag or link as-is - there is no new affiliate account to sign up for and no ChatAds tag in the response. It's the inverse of [Commerce Extract](/guides/commerce-extract): Extract finds the product mentions inside a block of text, Match turns one of those phrases into something shoppable. All three tools live on the same server behind the same `cak_` access key, so connecting once gives you all of them - including [Commerce Insert](/guides/commerce-insert), which does both steps for you on a full AI reply. **Amazon US is the catalog live today.** The resolution engine is catalog-agnostic, but Amazon US is currently the only catalog wired up, so every match returns `merchant: "amazon"` with a US `url`. There is no country or marketplace parameter. This is a **different server** from the [MCP Data Connector](/guides/mcp-data-connector). That one is read-only access to your own widget data with a `uk_` user key. This one takes a `cak_` team access key and matches text you send it. ## Get Your Access Key Commerce Match MCP authenticates with a team **access key** (`cak_...`) in the `x-api-key` header - the same key type Commerce Extract uses. If you already hold one, reuse it. 1. Log into [app.getchatads.com](https://app.getchatads.com) 2. Open **Commerce Match** 3. In the **Access Keys** card, click **Create Key** You can hold as many access keys as you have clients - one per MCP client is a good default, so you can revoke them independently. Widget keys (`cwk_...`) and user keys (`uk_...`) do not work here. ## Connect Commerce Match runs on the **same MCP server as Commerce Extract and Commerce Insert**. If you've already connected it, `find_product_matches` is there too - skip this section. Add the server once; one entry serves all three tools. In Claude Code it's one command. Most other clients (Claude Desktop, Cursor, Windsurf, etc.) take the JSON block - drop the `transport` field if your client rejects it: ```bash Claude Code theme={null} claude mcp add --transport http chatads-commerce https://api.getchatads.com/tools/mcp/mcp --header "x-api-key: cak_your_access_key" ``` ```json JSON config theme={null} { "mcpServers": { "chatads-commerce": { "url": "https://api.getchatads.com/tools/mcp/mcp", "transport": "http", "headers": { "x-api-key": "cak_your_access_key" } } } } ``` It's a Streamable HTTP MCP server, so there's nothing to install locally and no Node or Python dependency - one URL in a config file. Restart your client and `find_product_matches` is available. ## Tool | Tool | Params | What it returns | | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | `find_product_matches` | `term` (required) - a product name or phrase to match; `context` (optional) - surrounding text containing that term, to disambiguate it | Up to 3 product matches in a `matches` array, plus a `count` | | Param | Type | Description | | --------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `term` | string (required) | The product name or phrase to match, e.g. "Bose QuietComfort Ultra earbuds". Brand specificity belongs here - a term naming its brand matches far better than a bare category noun. Capped at 100 characters; a longer term is truncated at a word boundary, not rejected | | `context` | string (optional) | The surrounding text the term came from, used to disambiguate its category and vertical. It **must contain `term` verbatim** - it's the passage the term was pulled from, not background you write yourself. If you have no surrounding text, omit it. Only the 500 characters either side of the term are used; the rest is ignored, not rejected | If `term` appears more than once in `context`, only the **first occurrence** is used. The words immediately around that occurrence are what drive the category and vertical signals, so a `context` where the same phrase appears twice under different brands or in two unrelated topics resolves against the first one and ignores the rest. When that matters, trim `context` down to the passage you actually mean. The response carries no offsets, so there's no way to tell after the fact which occurrence was used. Everything outside 500 characters either side of that occurrence is dropped before matching, so trimming a long `context` yourself is optional - it changes which passage is used, not whether the call succeeds. Each match: | Field | Type | Description | | ------------ | ------ | ----------------------------------------------------------------------------- | | `title` | string | The merchant's product title | | `image` | string | Product image URL | | `brand_name` | string | The product's brand | | `url` | string | Merchant product page URL. Untagged - no affiliate account required | | `category` | string | Catalog main/department category for this product | | `merchant` | string | Which merchant the match came from. Branch on this field rather than assuming | The response is a `matches` array of 0 to 3 items plus a `count`. `matches[0]` is the best pick. An empty `matches` array is a success, not an error - it means we found no confident match for that term, and retrying won't change that. ### Example Calling the tool with: ```json theme={null} { "term": "Bose QuietComfort Ultra earbuds", "context": "The Bose QuietComfort Ultra earbuds are great for commuting." } ``` returns: ```json theme={null} { "data": { "matches": [ { "title": "Bose QuietComfort Ultra Bluetooth Earbuds...", "image": "https://m.media-amazon.com/images/I/51example.jpg", "brand_name": "Bose", "url": "https://www.amazon.com/dp/B0CD2FSRDD", "category": "Electronics", "merchant": "amazon" } ], "count": 1 }, "meta": { "request_id": "60556e82-ec0b-425b-8289-b95395db8943" } } ``` The JSON above is the text response. Clients that support MCP structured tool output also receive the `data` payload directly as structured content - the bare `{"matches": [...], "count": n}` object, matching the tool's declared output schema. Same envelope shape as [Commerce Extract](/guides/commerce-extract). ## Limits * **Input length:** `term` is capped at 100 characters and `context` at 500 characters either side of the term's first occurrence. Over-cap input is truncated or windowed, not rejected - the call still succeeds. Near-miss copies (smart quotes, extra whitespace, invisible characters, markdown wrapping) are normalized before the containment check, so they match rather than erroring. * **Requests:** the free tier includes 500 requests per month. Every call counts, including ones that return zero matches. [Get in touch](https://www.getchatads.com/contact) to raise your cap - tell us roughly what volume you're expecting. * Commerce Match shares one usage pool with Commerce Extract, [Commerce Insert](/guides/commerce-insert), and the rest of your team's API usage, and the same per-minute burst limit. Your current month's usage is shown at the top of all three tabs - same team-wide figure either way. * Your team's blocked-keyword and language content rules still apply. Text that trips one returns an empty `matches` array rather than an error. ## Troubleshooting ### "This tool requires a cak\_ API key" You connected with a user key (`uk_...`). Commerce Match MCP takes a team access key (`cak_...`) - create one on the **Commerce Match**, **Commerce Extract**, or **Commerce Insert** tab. ### "Term is required" The `term` argument was missing, empty, or whitespace only. An empty term is a client error, not an empty-matches success. ### "Term must appear in context" The `context` you sent doesn't contain `term` verbatim. `context` is the passage the term was pulled from, not a slot for background you write separately. Near-miss copies - smart quotes, extra whitespace, invisible characters, markdown wrapping - are normalized on both fields first, so this error means the term genuinely isn't there. Fix the input or drop `context` and send `term` alone; it's an `INVALID_INPUT` client error, so retrying the same call won't help. ### "Extraction backend temporarily unavailable - please retry" A `SERVICE_UNAVAILABLE` error means the matching service didn't respond. It's deliberately surfaced as an error rather than silently returning zero matches, so a retry is safe and correct here. ### "Daily request limit exceeded" / "Monthly request limit exceeded" You've used your plan's allowance. See [Limits](#limits). ### An obvious product returns `"count": 0` We had no confident match for that phrase in the catalog. In order of what usually fixes it: 1. **Put the brand in `term`.** "Bose QuietComfort Ultra earbuds" matches far better than "earbuds". 2. **Check the casing.** The same scoring engine backs both tools, and capitalization is a real signal - see [Casing Is a Signal](/guides/commerce-extract#casing-is-a-signal). 3. **Trim `context`** to the passage the term actually came from, so the category signals around it are the right ones. Some products legitimately aren't in the catalog. An empty `matches` array is a success - treat it as "no link for this one" and move on rather than retrying. ### Tool not appearing in your MCP client 1. Verify the URL is exactly: `https://api.getchatads.com/tools/mcp/mcp` 2. If your client's config uses a `transport` field, it should be `"http"` 3. Confirm the key in `x-api-key` starts with `cak_` 4. Restart your MCP client completely 5. Ask: "What tools do you have access to?" # Customization Source: https://docs.getchatads.com/guides/customization Tune the widget's appearance and the AI's behavior from the dashboard Everything on this page lives on the **Customize** tab of the [dashboard](https://app.getchatads.com). Changes apply server-side without touching your embed code. ## Appearance Accent Color and Button card with color picker, button text, and bubble position controls * **Site name** - your site's name (up to 100 characters). The AI uses it to introduce itself as an assistant for your site. * **Accent color** - the color of accents within the opened widget. Optionally apply it to the launcher button too; otherwise the launcher uses the default dark style. * **Button text** - the label on the launcher pill. Defaults to "Ask AI", up to 8 characters. * **Bubble position** - which bottom corner the launcher sits in. The "above sticky ads" variants lift it clear of anchor/adhesion ad units. * **Welcome message** - shown in the middle of the widget when it first opens, up to 200 characters. * **Branding** - Free and Pro plans show "Powered by ChatAds". The Business plan can hide it. See [Plans & Billing](/guides/chatads-billing). ## Starter Questions Up to 3 short prompts (50 characters each) shown as pill buttons in the empty chat panel. When a visitor clicks one, it sends immediately. Use them to surface the questions your readers actually ask - the [Conversations tab](/guides/analytics#conversations) is a good source. Starter Questions card with three example questions Open widget showing the welcome message and three starter question pills ## Page Context Page context makes ChatAds article-aware. When enabled (the default), the widget sends the current page's content once, the first time a visitor opens the chat, and ChatAds extracts roughly the first 1,000-2,000 words of relevant content from it - depending on your plan (Free 1,000 / Pro 1,500 / Business 2,000) - so the assistant can answer questions about that specific article for the rest of the conversation. Extracted content includes: * Headings, paragraphs, list items, and table cells * Affiliate links already present on the page (Amazon and supported affiliate network links) Scripts, styles, images, media, anything typed into a form, and the ChatAds widget's own interface are never sent. Navigation and footers are sent but filtered out on our servers, so the assistant never sees them. If you turn page context off, ChatAds behaves like a standard site chatbot and relies less on the current page. ## Custom Prompt You can add up to 500 characters of custom instructions, sent to the AI with every message. ChatAds already provides a robust prompt covering page content, metadata, prompt-injection blocking, and chatbot behavior; use this field for anything specific to your site - a brand voice note, a topic to avoid, a fact the AI should know. ### What the AI declines by default Out of the box, the assistant is scoped to your site's topic. It answers anything related to your site's overall theme - including practical questions about choosing, buying, using, or maintaining things you cover - but politely declines requests that have nothing to do with it. It also declines these categories when they're unrelated to your site: games, roleplay, coding help, homework, math problems, trivia, politics, creative writing, translation, jokes, songs, and general life advice. When one of those *does* connect to your site's topic (a cooking-time calculation on a recipe site, say), it answers normally. ### Widening the scope If your site is intentionally broad - a general Q\&A site or a multi-topic publication - the default scoping can feel too strict. Use the custom prompt to widen it, for example: *"This site covers general knowledge across many topics. Treat any sincere question as on-topic and answer it directly."* Your custom instructions are sent after the defaults, so they take precedence for topic scope. The custom prompt adjusts the AI's behavior only. It can't disable ChatAds' separate [message screening](/guides/widget-messages#screening-replies), which blocks spam, prompt injection, and a small set of clearly off-topic requests before they reach the AI. # FAQ Source: https://docs.getchatads.com/guides/faq Quick answers to the questions publishers ask before and after installing ChatAds No. The widget is a single \~20 KB (gzipped) script (its only dependency, DOMPurify, is inlined at build time, so there are no external requests), it loads `async` by default, and it causes no layout shift. See [Performance](/guides/performance) for the full breakdown. No. ChatAds works out of the box: it reads the page the visitor is currently on (roughly the first 1,000-2,000 words depending on your plan) and answers questions about it. There is no ingestion or training step. You can optionally add a [custom prompt](/guides/customization#custom-prompt) for site-specific instructions. You do - 100%, on every plan. Amazon links use *your* Associates tag, scraped links are *your* existing links, and ChatAds never takes a cut. ChatAds makes money from its Pro and Business subscriptions. Only for the Amazon monetization toggle. [Affiliate Link Scraping](/guides/chatads-monetization#affiliate-link-scraping) (reusing the affiliate links already on your page) and plain site chat work without one. If you want Amazon links, [setup takes about 5 minutes](/partners/amazon-affiliates). Yes. Any valid Associates tracking ID works. We recommend creating a dedicated tracking ID (e.g. `mystore-chatads-20`) so you can see ChatAds-driven conversions separately in Amazon's reporting. Very likely. Link scraping recognizes Amazon, CJ, Awin, ShareASale, Impact, Rakuten, Pepperjam, Geniuslink, Avantlink, Howl, Affilizz, GeoRiot, Partnerize, Next2, Kickbooster, Target and Walmart's own affiliate redirects, Skimlinks, VigLink, Sovrn, `rel="sponsored"` links, common tracking parameters, and cloaked links from plugins like ThirstyAffiliates, Pretty Links, Lasso, and AAWP. Missing yours? [Tell us](mailto:team@getchatads.com?subject=Affiliate%20Partner%20Scraping%20Request) and we'll add it. Visitors who already opened the widget that day see "Chat limit reached" with the input disabled; visitors who haven't opened it don't see the widget at all. Limits reset at midnight UTC. See [Rate Limits](/guides/rate-limits), or [upgrade](/guides/chatads-billing) for a higher cap. The assistant replies in whatever language the visitor writes in. Sponsored Amazon links are only added to English replies for US visitors; internal links and links from your own page work in any language. By default the widget hides itself for non-English browsers (you can [change that](/guides/widget-configuration#master-settings)). The abuse surface is small: per-visitor daily limits (default 20 messages), per-minute burst limits, duplicate-question deflection, and screening that rejects off-topic or prompt-injection messages before they reach the AI (screened messages don't count against your limits). See [Rate Limits & Screening](/guides/rate-limits). Yes - include/exclude [page rules](/guides/widget-configuration#page-rules) with wildcards, a mobile toggle, and an English-browsers-only toggle. Rules apply server-side, no redeploy needed. No cookies. The widget keeps a small amount of state in `localStorage` (session, daily counters) and does no cross-site tracking. See [Privacy & Data](/guides/privacy-and-data). Yes - the [Conversations tab](/guides/analytics#conversations) shows full transcripts (PII-stripped, retained 90 days, exportable to CSV), and it's a great source for content ideas and starter questions. Still stuck? [Contact support](mailto:team@getchatads.com) - we answer fast. # Ghost Source: https://docs.getchatads.com/guides/ghost-integration Add a free AI chat assistant to your Ghost site and earn affiliate revenue from the conversations [ChatAds](https://www.getchatads.com) is an embeddable AI chat widget for publishers. Readers ask your site an AI assistant questions right on the page (like a ChatGPT box that lives in the corner of your posts), and ChatAds monetizes those chats with relevant in-line affiliate links. It works out of the box, with no training or content upload required. It installs on Ghost with a single line in **Code injection**, so there is nothing to maintain in your theme. ## Why Ghost publishers use it * **A new revenue stream that isn't display ads.** When a reader asks the assistant something with buying intent ("what's a good beginner espresso machine?"), ChatAds can weave in an affiliate link. No banner clutter, no slowing your site down. * **Keeps readers on your page.** Instead of leaving to search elsewhere, readers get answers in context, on your site. * **Zero content work.** The assistant answers general questions immediately. You don't have to feed it your archive or configure prompts to get started. * **You stay in control.** Appearance, which pages it shows on, and whether monetization is on are all managed from the ChatAds dashboard, not in your Ghost admin, so new features ship without you editing anything. ## Install (about 2 minutes) **1. Get your widget key** Sign up at [app.getchatads.com](https://app.getchatads.com) (there's a free tier). On the **Settings** tab, copy your embed snippet. Your key starts with `cwk_`. **2. Add it to Ghost** In Ghost Admin: 1. Go to **Settings > Code injection** 2. Paste the snippet into the **Site footer** field: ```html theme={null} ``` 3. Click **Save** That's it. The launcher pill (default label "Ask AI") appears in the bottom corner of your site. **3. Lock it to your domain** Back on the ChatAds **Settings** tab, add your Ghost site's domain to **Allowed Domains** so no one else can use your key. ## Turning on monetization (optional) Monetization is off by default. In the dashboard you can enable either or both: * **Amazon affiliate links** - the assistant recommends real products and links them with your Amazon Associates tag. * **Affiliate link scraping** - reuses the affiliate links you already have on the page, plus links to products mentioned on the page. You can also just run the assistant as a free reader-engagement tool with monetization off. ## Customization From the dashboard you control the widget color, welcome message, starter questions, the AI's tone, and which pages it appears on (for example, posts only, not your homepage). None of this touches your Ghost theme. ## Pricing There's a free tier to start. Paid tiers raise the daily message limits. See [getchatads.com](https://www.getchatads.com) for current plans. ## Links * Site: [https://www.getchatads.com](https://www.getchatads.com) * Dashboard / sign-up: [https://app.getchatads.com](https://app.getchatads.com) * Docs: [https://docs.getchatads.com](https://docs.getchatads.com) * Questions: [https://www.getchatads.com/contact](https://www.getchatads.com/contact) # MCP Data Connector Source: https://docs.getchatads.com/guides/mcp-data-connector Pull your ChatAds widget usage, conversations, and click data into Claude or any MCP client ## Overview The MCP Data Connector is a **read-only** MCP server for your ChatAds widget data - usage, conversation transcripts, and inline-link clicks. It makes no changes to your account: no settings, no keys, no billing. Point any MCP-compatible client (Claude, Cursor, etc.) at it and ask questions about your widget's performance in plain language. Looking for product extraction or matching rather than your own widget data? That's a separate MCP server, using a team access key (`cak_...`): [Commerce Extract](/guides/commerce-extract) pulls scored product and purchase-intent mentions out of any text you send it, [Commerce Match](/guides/commerce-match) turns a product phrase into a shoppable link, and [Commerce Insert](/guides/commerce-insert) does both at once on a full AI reply. ## Get Your Key The connector authenticates with your **MCP Data Connector Key** (`uk_...`), a personal key rather than a team key - see [Your Account](/guides/account-management#mcp-data-connector-key) for how it's managed. 1. Log into [app.getchatads.com](https://app.getchatads.com) 2. Open **Account** 3. In the **MCP Data Connector Key** card, click **Create MCP Data Connector Key** (or **Show** if you already have one) If you created your key before this feature launched, reveal it once (or reset it) on the Account page - that's what registers it for MCP lookups. New keys work immediately. ## Connect In Claude Code it's one command. Most other clients (Claude Desktop, Cursor, Windsurf, etc.) take the JSON block - drop the `transport` field if your client rejects it: ```bash Claude Code theme={null} claude mcp add --transport http chatads-widget https://api.getchatads.com/mcp/mcp --header "x-api-key: uk_your_user_key" ``` ```json JSON config theme={null} { "mcpServers": { "chatads-widget": { "url": "https://api.getchatads.com/mcp/mcp", "transport": "http", "headers": { "x-api-key": "uk_your_user_key" } } } } ``` Restart your MCP client and it's ready to go. ## Tools | Tool | Params | What it returns | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `chatads_widget_usage` | `start_date`, `end_date` (`YYYY-MM-DD`, default: last 30 days ending today) | Daily message/page-load/click counts for the range, plus your widget plan tier and daily chat limit | | `chatads_widget_conversations` | `limit` (default 25, max 1000), `session_id` (fetch one full session by UUID), `max_message_chars` (default 300, `0` = full text) | Recent chat transcripts, grouped by session, newest first; a `truncated` flag signals more sessions exist | | `chatads_widget_clicks` | `limit` (default 200, max 2000), `start_date`/`end_date` (`YYYY-MM-DD`, within the last 90 days), `group_by` (`day`\|`source`\|`page` — returns per-key counts instead of rows), `include_href` (default false) | Inline affiliate-link click events from the last 90 days, with a `source` label (Amazon, Skimlinks, CJ, etc.) | All three also accept an optional `team_id` parameter - you only need to pass it if your account belongs to more than one team. If you do, the tool tells you your team IDs and names so you can pick one. ### Response Fields All responses arrive as JSON with the payload under `data`. Each tool always includes your `team_id`; an empty array is a success (no data in the range), not an error. `chatads_widget_usage` also returns `team_name`, `widget_plan_tier`, and `daily_chat_limit`: | Field | Description | | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `days` | One row per day: `date`, `message_count` (chat messages), `page_load_count` (pages the widget loaded on), `click_count` (inline link clicks) | | `totals` | The same three counts summed across the requested range | `chatads_widget_conversations` returns a `sessions` array: | Field | Description | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | `session_id` | UUID of the chat session. Pass it back via the `session_id` param to fetch that full session | | `page_url` | The page the conversation happened on | | `messages` | Each exchange: `created_at`, `user_message`, `assistant_message`, `has_affiliate_links` (whether the reply carried affiliate links) | | `truncated` | List mode only. `true` means more sessions exist than the row `limit` covered - raise `limit` or fetch sessions individually by `session_id` | `chatads_widget_clicks` returns a `clicks` array by default, or a `summary` when `group_by` is set: | Field | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `clicks` | Each event: `created_at`, `page_url`, `anchor_text`, `sponsored` (whether the clicked link was an affiliate link), `source` (Amazon, Skimlinks, CJ, etc.), `session_id`, and `href` when `include_href=true` | | `truncated` | Row mode only. `true` means more clicks exist than the row `limit` covered - raise `limit` or narrow the date range | | `summary` | With `group_by`: `{key, count}` rows, count-descending. `truncated: true` means the tally hit its 5,000-row cap - narrow the date range | ## Limits * A per-user rate limit applies across all three tools, separate from any team's ChatAds plan limits. * Conversations and clicks are retained 90 days (the same purge schedule as the dashboard). * Data mirrors what you'd see in the dashboard's **Conversations** tab and **Click Log Export** - this connector doesn't compute anything new, it just makes that data queryable from your MCP client. ## Troubleshooting ### "Widget data tools require a uk\_ user key" You connected with a team API key (`cak_...`). The widget-data tools only accept an MCP Data Connector Key (`uk_...`) - create one on the [Account page](https://app.getchatads.com/account). ### "Your account belongs to multiple teams" Pass the `team_id` from the error message as an argument to the tool call. ### Tool not appearing in your MCP client 1. Verify the URL is exactly: `https://api.getchatads.com/mcp/mcp` 2. If your client's config uses a `transport` field, it should be `"http"` 3. Restart your MCP client completely 4. Ask: "What tools do you have access to?" # Overview Source: https://docs.getchatads.com/guides/overview What ChatAds is and how it looks in a live content experience ChatAds is an embeddable AI chatbot for blogs and content sites. It gives visitors a way to ask questions in the context of the page they are reading, and it can optionally monetize those conversations two ways: by inserting Amazon affiliate links, or by reusing the affiliate links you already have on the page. You install it with one script tag. There is no training step and no content ingestion project: the widget reads the page the visitor is on and answers questions about it out of the box. ## Product Walkthrough ## What It Looks Like When a visitor opens the widget, they see a welcome message and up to three starter questions you configure: Open ChatAds widget showing a welcome message and three starter question buttons When monetization is enabled and the AI recommends a product, the product phrase becomes an in-line affiliate link, right inside the answer: ChatAds reply recommending a cast iron grill pan with an in-line affiliate link ## Try It Live Open the live recipe page and test the embedded ChatAds widget in a real content experience. ## The Dashboard Everything is managed from [app.getchatads.com](https://app.getchatads.com). The dashboard has six tabs: | Tab | What it does | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Usage** | Daily message pacing against your plan limit, plus charts of page loads, messages, and affiliate link clicks. Includes a click log CSV export. See [Analytics & Conversations](/guides/analytics). | | **Settings** | Widget key, embed snippet, allowed domains, page rules, and access controls. See [Installation](/guides/chatads-setup) and [Widget Configuration](/guides/widget-configuration). | | **Customize** | Site name, welcome message, starter questions, colors, button text and position, page context, and a custom AI prompt. See [Customization](/guides/customization). | | **Monetize** | The two monetization toggles, Amazon Associates tag (US), ad frequency controls, and product quality filters. See [Monetization](/guides/chatads-monetization). | | **Conversations** | Read transcripts of what visitors asked and how the AI answered, with search and CSV export. See [Analytics & Conversations](/guides/analytics). | | **Plan & Billing** | Your tier, daily message limit, payment method, and invoices. See [Plans & Billing](/guides/chatads-billing). | # Performance Source: https://docs.getchatads.com/guides/performance What the widget costs your page speed: script size, load behavior, and Core Web Vitals Publishers care about page speed, so here is exactly what embedding ChatAds does to your page. ## Script Size The widget is a single self-contained JavaScript file - its only dependency, DOMPurify, is inlined at build time (markdown rendering is a hand-written minimal-subset renderer, no parser library), so it makes zero external requests for code: * **\~20 KB gzipped** over the wire (\~60 KB uncompressed) * Served from `getchatads.com/widget.js` via a global CDN * No external fonts, stylesheets, or images - styles are inlined and the widget uses your visitors' system font stack For comparison, that's a fraction of the size of a typical consent banner or commenting embed. ## Load Behavior * The script waits for `DOMContentLoaded` before doing anything, so it never delays your content from rendering. * On load it makes one small request to fetch your widget's configuration (enabled state, page rules, theme). If the widget shouldn't show on that page - wrong domain, excluded path, non-English browser - it exits without rendering anything. * All further requests happen only when a visitor actually uses the chat. * The snippet ships with the `async` attribute by default (what the dashboard generates), so it never blocks HTML parsing even when pasted into ``. `defer`, or a placement just before ``, work equally well. ## Core Web Vitals * **Layout shift (CLS):** none. The launcher is a fixed-position overlay, so it never moves your content. * **Largest Contentful Paint (LCP):** unaffected. The widget initializes after the DOM is ready and renders only a small launcher pill. * **Interaction readiness (INP):** the widget's work happens off the critical path; there is no heavy main-thread work on page load. ## No Iframe The widget renders directly on the page rather than inside an iframe, which keeps it lightweight and lets inserted links behave like normal page links (right-click, open in new tab, etc.). Its styles are namespaced so they don't collide with your site's CSS. # Privacy & Data Source: https://docs.getchatads.com/guides/privacy-and-data What ChatAds collects, where it lives, how long it's kept, and what your visitors should know Embedding third-party JavaScript is a trust decision. This page lays out exactly what ChatAds stores and for how long, so you can update your own privacy policy accurately. ## No Cookies, No Cross-Site Tracking The widget sets **no cookies** and does not track visitors across sites. It keeps a small amount of state in the browser's `localStorage`, scoped to your widget key: * The visitor's chat session and message history (so a conversation survives a page reload) * Daily counters for the per-visitor message limit and your ad frequency cap * Whether the visitor opened the widget today (used when your team's daily limit is reached) Old entries clean themselves up automatically. ## What Gets Sent to ChatAds * **Chat messages** the visitor types, plus the AI's replies. * **Page context** - when [page context](/guides/customization#page-context) is enabled (the default), the widget sends a stripped-down copy of the page's structure and visible text once, the first time a visitor opens the chat, so the AI can answer questions about the article for the rest of the conversation. It is sent compressed, is size-capped, and is held on our servers for at most 24 hours. Scripts, styles, images, media, and anything typed into a form are never included. * **Usage events** - page loads, messages, and link clicks, aggregated per day for your usage charts. * **Click events** - for each inline link click: the page URL, anchor text, destination URL, whether the link was sponsored, country (an ISO code derived from IP; the raw IP is not stored in the click log), browser language, and chat session ID. Visitor IPs are used server-side for rate limiting (per-visitor daily and per-minute limits) and to derive the country code for Amazon marketplace targeting. ## Conversation Logs * Conversation logging is **on by default** and can be turned off any time from the Conversations tab; new messages stop being stored immediately. * Visitor messages are **PII-stripped before storage**: emails, phone numbers, and similar identifiers are removed. * Transcripts are visible only to your team in the dashboard (and via your own [MCP Data Connector](/guides/mcp-data-connector) key). If your site covers sensitive topics (health, medical, financial), consider turning conversation logging off from the Conversations tab. PII stripping removes identifiers like emails and phone numbers, but not the free-text content itself, so visitors may type sensitive details into the chat that would otherwise be stored verbatim. ## Retention | Data | Retention | | --------------------------------------------------------------- | ----------------------------------- | | Conversation transcripts | 90 days, then deleted automatically | | Click log events | 90 days, then deleted automatically | | Daily usage aggregates (counts of page loads, messages, clicks) | Kept for your usage charts | Export CSVs from the dashboard before the 90-day window if you want to keep transcripts or click logs long-term. For your own account data (as a ChatAds user, not a reader), GDPR-style export and deletion controls are on the [Account page](/guides/account-management#exporting-your-personal-data), with team-level equivalents on the [Team page](/guides/team-management#exporting-team-data). ## Visitor Erasure Requests If a visitor asks you to erase a conversation they had with your widget, forward the request to [team@getchatads.com](mailto:team@getchatads.com) and we will delete the matching transcript and click-log rows within the 90-day retention window. Include any details that help us locate the conversation, such as the approximate date and the page it happened on. Transcripts and click logs are deleted automatically 90 days after they are recorded regardless. ## What Your Privacy Policy Should Mention If you embed ChatAds, we recommend your privacy policy discloses that: 1. An AI chat assistant is provided by a third party (ChatAds), and questions typed into it are processed by ChatAds and its AI provider to generate answers. 2. Chat transcripts may be retained for up to 90 days. 3. Chat replies may contain affiliate links (see [Affiliate Disclosure](/guides/affiliate-disclosure)). The widget itself also displays "Links may include affiliate offers" in its footer at all times. This page describes how the product behaves; it isn't legal advice. For data processing agreements or region-specific compliance questions, [contact us](mailto:team@getchatads.com). # Rate Limits & Screening Source: https://docs.getchatads.com/guides/rate-limits Daily message caps, burst protection, and the checks every message goes through ## Daily Message Limits Each plan has a daily widget chat cap, enforced server-side and reset at midnight UTC: | Tier | Daily Team Chat Limit | | -------- | --------------------- | | Free | 100/day | | Pro | 500/day | | Business | 1,500/day | When the team hits its daily limit, visitors who have already opened the widget that day see "Chat limit reached. Please try again later." with the input disabled. Anyone who hasn't opened it yet won't see the widget at all until the limit resets. See [Plans & Billing](/guides/chatads-billing) for pricing and upgrades. Individual visitors also have their own daily allowance (default 20 messages/day, tracked by IP) - see [Per-Visitor Daily Limits](/guides/widget-configuration#per-visitor-daily-limits). ## Burst Protection A short-window rate limiter protects the service from bursts and spam: * Team-level: 300 requests per minute * Per-visitor: 10 chat messages per minute per IP * Endpoint-specific IP limits also apply to the other widget routes If a burst limit is exceeded, the visitor sees "You're sending messages too quickly - please wait a moment and try again." and can retry shortly. ## Message Screening Every question goes through automatic checks before it reaches the AI. Screened-out messages don't count against your daily limits, and the visitor sees a short in-chat reply explaining what happened: * **Length** - questions over 600 characters (roughly 100 words) are rejected * **Topic** - off-topic, spammy, or prompt-injection content is declined; the assistant stays focused on your content and refuses games, roleplay, coding help, homework, and attempts to override its instructions * **Duplicates** - the same question repeated more than 3 times in a minute is deflected This protects your AI spend and keeps conversations on-brand. For the exact message text visitors see in each case, see [Widget Messages Explained](/guides/widget-messages). # Team & Roles Source: https://docs.getchatads.com/guides/team-management Invite teammates, control what each role can do, and review your team's activity log Every ChatAds workspace is a **team**: the widget configuration, monetization settings, analytics, and billing all belong to the team, and every person you invite works on that shared setup. To open team settings, click the **gear icon** in the top-right of the dashboard and choose **Team**. ## Inviting Team Members Team Members card with an Invite Member button and a table listing each member's email, role, and join date Click **Invite Member**, enter the person's email address, and pick a role. They receive an email with an acceptance link; until they accept, the row shows a **Pending** badge and you can resend the invitation from the table. Invitations expire after 14 days. Owners and admins can invite members. Admins can assign the Admin, Member, or Viewer role; only an owner can grant the Owner role. ## Roles & Permissions ChatAds has four roles. The Team page shows this same reference table: Role permissions matrix comparing Owner, Admin, Member, and Viewer across team management and widget permissions | Permission | Owner | Admin | Member | Viewer | | ------------------------------------------------------------------------------------------------------- | ----- | ----- | ------ | ------ | | Invite / remove members | Yes | Yes | - | - | | Update team settings (e.g. team name) | Yes | Yes | - | - | | Manage billing and payment methods | Yes | - | - | - | | Delete the team | Yes | - | - | - | | View widget settings, usage, and conversations | Yes | Yes | Yes | Yes | | Edit general widget settings (prompt, theme, page rules, starter questions) | Yes | Yes | Yes | - | | Manage activation & monetization (widget on/off, monetization toggles, allowed domains, affiliate tags) | Yes | Yes | - | - | A useful way to think about it: * **Owner** - full control, including billing and team deletion. Every team needs at least one. * **Admin** - runs the team day to day: members, widget activation, monetization, domains. No billing. * **Member** - edits the widget's content and behavior (system prompt, theme, page rules, starter questions) but can't touch activation, monetization, or membership. Members can view (but not edit) the team's API keys and Amazon affiliate tag. A good fit for writers and site editors. * **Viewer** - read-only. Sees usage, conversations, settings, and members without being able to change anything. A good fit for stakeholders who just need visibility. ### Changing Roles & Removing Members Owners and admins change roles from the dropdown in the members table. A few guardrails apply: * You can't change your own role. * Only an owner can change another owner's role. * The last owner can't be removed or leave; promote someone else to Owner first. ## Team Name & Team ID The **Team Information** card holds your team name (shown in the dashboard and invitation emails) and your **Team ID**. The ID is only used for support: include it when you email [team@getchatads.com](mailto:team@getchatads.com) so we can find your account immediately. ## Activity Log Every meaningful account action is recorded in an audit trail. Click **View Activity** on the Team page (or the gear icon > Team > Activity Log) to see it: Team Activity feed showing logged events such as affiliate tag updates, settings changes, and invoices, each with user, timestamp, and IP address Logged events include member invitations, joins, and removals; role changes; settings and affiliate tag updates; plan changes; invoices and payment method changes; and data exports. Each entry records the event type, who did it, a timestamp, success or failure, the IP address and browser it came from, and event-specific details (expand **Show metadata** to see them). The log is visible to **all team members**, and the **Export CSV** button downloads the recent history for compliance or record-keeping. ## Exporting Team Data The **Export Team Data** card downloads your team configuration as JSON: settings, members, key metadata, and keyword rules. Secrets (keys and Amazon affiliate tags) are never included in the export. This exports the team's configuration. For your chat and click data, use the CSV exports on the [Usage and Conversations tabs](/guides/analytics), and for your personal data see [Your Account](/guides/account-management#exporting-your-personal-data). ## Deleting Your Team Only an owner can delete a team, from the **Danger Zone** at the bottom of the Team page. Deletion is a two-stage process: 1. The team enters a **30-day grace period**. Any active paid plan is canceled, and the owner can restore the team at any point during the window. 2. After 30 days, the team and all its data are permanently deleted. Remove the widget snippet from your site when you delete the team; a deleted team's widget stops serving. # Why No Offers? Source: https://docs.getchatads.com/guides/why-no-offers Diagnose why the widget isn't inserting affiliate links If replies aren't carrying affiliate links, work through the checks below in order. First, confirm the relevant toggle is actually on: both monetization paths are opt-in on the **Monetize** tab (see [Monetization](/guides/chatads-monetization)). ## Amazon Affiliate Links | Check | Why it blocks offers | Fix | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | | Associates tag missing | The Amazon toggle is on but no tag is set, so no links can be attributed - the dashboard shows a warning in this state | Add your tag on the Monetize tab | | Daily ad cap reached | A visitor who has already seen their capped number of sponsored links today gets no more until tomorrow | Raise or remove the cap, or test in a private window | | Product Pushiness set to `low` | The AI only mentions products when the visitor is clearly shopping, so many replies contain nothing to monetize | Raise pushiness on the Monetize tab | | Sponsored links per reply | Each reply carries at most 1 sponsored link by default (2 if raised); extra product mentions stay unlinked | Raise the setting to 2 if you want more | | Category filters too strict | Allowed/excluded category rules shrink the pool of eligible products | Loosen the rules, or prefer exclusions over a narrow allowlist | | Non-English text | Amazon monetization is English-only today | No action - support for more languages is planned | | Non-US traffic | Sponsored links serve the Amazon US marketplace only; other geographies are filtered | No action - UK and more marketplaces are planned | | Product quality floors | Eligible products must be \$20+, 10+ reviews, 3.5+ stars (or your stricter thresholds); cheap or poorly-reviewed matches are suppressed by design | Nothing to fix - this protects conversion quality | | Auto-blocked category | The matched product falls in a permanently excluded low-value category (Books, Software, Grocery, etc. - full list on the Monetize tab) | Nothing to fix - these categories don't convert | | Branded product not in our catalog | When a reply names a specific branded product, ChatAds won't substitute a generic offer. If that exact product isn't in our catalog, neither the brand nor a generic fallback is served | This is intentional - a wrong-brand link erodes reader trust | ## On-Page Link Scraping | Check | Why it blocks offers | Fix | | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Phrase mismatch | The AI wrote "Nike shoes" but your on-page link says "Nike sneakers" - matching is phrase-based, so it doesn't insert | Generative text can't be forced verbatim; links insert when phrasing aligns | | Unrecognized affiliate partner | Your links use a network or plugin we don't detect yet | [Email us the partner](mailto:team@getchatads.com?subject=Affiliate%20Partner%20Scraping%20Request) - additions are quick | | External link without a redirect tool | External page product links only insert when Skimlinks, VigLink, or Sovrn is on the page; otherwise an external link earns nothing | Add a page-level redirect tool, or rely on same-site links | | Never-monetizable domain | Links to Reddit, Wikipedia, YouTube, and similar social/reference sites are always skipped | Nothing to fix | ## Still Seeing No Offers? If you've walked the tables and links still aren't appearing, [contact support](mailto:team@getchatads.com) with the page URL and an example question - we'll trace the exact reply. # Why This Product? Source: https://docs.getchatads.com/guides/why-this-term How ChatAds decides which product mention in a reply to monetize When a reply mentions products, ChatAds picks the product phrase it scores as the strongest monetization candidate and links that one. The scoring runs in under 200ms per reply and weighs brand detection, word patterns, sentence position, and purchase-intent signals. A few reasons the linked phrase might not be the one you expected: * **Multiple products in one reply** - ChatAds links the highest-confidence match, which may not be the one you consider most important. A reply mentioning both "MacBook Pro" and "USB-C hub" might link the hub if it scores higher. * **Generic vs. specific** - a brand mention can win over a more specific product deeper in the text, or vice versa; brand recognition and sentence position both carry weight. * **Sentence context only** - scoring sees the reply text, not the reader's full intent, so a choice that looks off in the conversation can be reasonable for the sentence in isolation. ## What You Can Control * **[Category rules](/guides/chatads-monetization#category-inclusion--exclusion)** - restrict offers to categories relevant to your content, or exclude categories that keep mismatching. * **[Brand Pushiness](/guides/chatads-monetization#brand-pushiness)** - control whether the AI leads with specific brands or stays generic, which changes what's available to link. * **[Sponsored links per reply](/guides/chatads-monetization#sponsored-links-per-reply)** - allow 2 links per reply so a second strong product mention also gets linked. If you consistently see a specific bad pattern, [send us examples](mailto:team@getchatads.com) - real transcripts are the fastest way to improve the scoring for your site. # Why This Offer? Source: https://docs.getchatads.com/guides/why-this-url How a product mention becomes a specific Amazon listing After ChatAds identifies a product phrase in a reply, it resolves that phrase to a specific listing. Resolution searches the catalog and ranks candidates on relevancy to the phrase, price, review count, star rating, and more; the highest-scoring product becomes the offer. Because this matches free-text phrases against millions of listings, edge cases exist: "wireless earbuds" might resolve to a strong-but-unfamiliar model, or "running shoes" might land on a trail shoe when the conversation was about road running. The [quality floors](/guides/chatads-monetization#product-quality-filters) (\$20+, 10+ reviews, 3.5+ stars) keep even imperfect matches defensible, and [category rules](/guides/chatads-monetization#category-inclusion--exclusion) let you fence resolution into your niche. ## Why Is the Offer Out of Stock? Amazon inventory is fluid. ChatAds filters out products our catalog records as out of stock, but that reflects the last time the listing was checked, not Amazon's real-time inventory. A product can sell out between our last check and the reader's click; the affiliate link still works, and Amazon shows alternatives on the product page. ## Reporting a Bad Match If a specific phrase keeps resolving to a poor listing, [send us the page URL and the reply](mailto:team@getchatads.com) - concrete examples feed directly into ranking improvements. # Widget Configuration Source: https://docs.getchatads.com/guides/widget-configuration Control where the widget appears and who can use it All access controls live on the **Settings** tab of the [dashboard](https://app.getchatads.com). Changes apply server-side, so you never need to redeploy your embed snippet. ## Master Settings Master Settings card with enable widget, English browsers only, show on mobile, include internal links, and max messages per day settings * **Enable Widget** - the master switch. Turn it off and the widget disappears from your site immediately. * **English browsers only** - hides the widget when the visitor's browser language is not English, including your own browser while you test. On by default because sponsored Amazon links only appear on English replies for US visitors; turn it off to show the widget to every browser language. The assistant replies in whatever language the visitor writes in. * **Show on mobile** - on by default. The widget works well on small screens; toggle off for a desktop-only experience. * **Include internal links** - on by default. The widget will insert links to product pages on your own site when the reply text matches the link's anchor text. These are regular internal links, not sponsored or tracked. Turn it off and the widget won't add internal links to responses. * **Max messages per day per user** - see [Per-Visitor Daily Limits](#per-visitor-daily-limits) below. ## Allowed Domains Restrict which domains can embed your widget. Leave the list empty to allow any site, or add one or more domains to prevent unauthorized use. Domain checks happen on widget impression, chat, and click events. Subdomains must be listed explicitly; `www.` is matched automatically. Allowed Domains card with two domains added as chips Always add at least one allowed domain before going to production. With an empty allowlist, anybody could embed your widget key on their site and consume your daily message allowance. ## Page Rules Control which pages the widget appears on with include and exclude path rules: * Paths without `*` are exact matches * `/blog/*` matches `/blog` and all subpages * `*pricing*` matches any pathname containing `pricing` * Exclude rules are evaluated after include rules Page Rules card with include paths and exclude paths inputs For example, `Include: /blog/*` with `Exclude: /blog/admin/*` shows the widget on blog pages except admin pages. ## Per-Visitor Daily Limits Each visitor can send up to 20 messages per day by default (tracked by IP, reset daily). When a visitor uses up their allowance, the input is disabled with the notice "You've used your N messages for today - come back tomorrow!" Use this to keep individual heavy users from consuming your team's [daily message limit](/guides/rate-limits). Raising the per-visitor limit above the default of 20 requires domain verification: (1) add a public domain to Allowed Domains and (2) load the widget once on that domain so our system detects it. Localhost domains can be added for local testing but don't count toward verification. Lowering the limit works immediately. # Widget Messages Explained Source: https://docs.getchatads.com/guides/widget-messages Every message and warning the widget or dashboard can show, what triggers it, and how to fix it This page lists every message a visitor can see in the chat widget, plus the warnings you can see in the dashboard - what triggers each one and what (if anything) to do about it. ## In-Chat Messages Visitors Can See ### Screening replies These arrive as a normal chat reply. Screened-out messages never reach the AI and don't count against your daily limits. | Message | Trigger | Notes | | ---------------------------------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------- | | "Please keep your question under 100 words." | Question over 600 characters | The visitor shortens and resends. | | "I'm sorry, this doesn't seem on topic. Can you ask another question?" | Off-topic, spammy, or prompt-injection content | The assistant stays focused on your site's content by design. | | "You just asked that - try rephrasing or asking something new." | The same question sent more than 3 times within a minute | Duplicate-flood protection. | A conversational reply like "I'm here to help with \[your site's topic] - is there something about that I can help with?" is different: that's the AI itself declining a question it judged unrelated to your site, not screening. You can widen what counts as on-topic with a [custom prompt](/guides/customization#widening-the-scope). ### Added to replies Unlike screening replies, this text is appended to an otherwise normal AI reply rather than replacing it. | Addition | Trigger | Notes | | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | | "Heads up: I'm an AI assistant, not a medical or health professional. For anything involving allergies, medications, or a health condition, double-check the details yourself and consult a qualified professional before relying on this." | The visitor's question touches allergies, medications, pregnancy, dosage, or another health/medical/safety topic | Appended once at the end of the reply; the assistant's answer itself is unaffected. | ### Limit notices | Message | Trigger | Notes | | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "You've used your N messages for today - come back tomorrow!" | The visitor hit your per-visitor daily limit (default 20/day, tracked by IP) | Input is disabled until the next day. Raise the limit from the Settings tab (requires domain verification). | | "Chat limit reached. Please try again later." | Your team hit its plan's daily message limit (100/500/1,500 per day) | Input is disabled; visitors who haven't opened the widget that day don't see it at all. Resets at midnight UTC. [Upgrade](/guides/chatads-billing) for a higher limit. | | "You're sending messages too quickly - please wait a moment and try again." | Burst protection: more than 10 messages per minute from one visitor, or more than 300 per minute across your team | Momentary; the visitor can retry shortly. | ### Error notices | Message | Trigger | Notes | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | "This chat widget isn't available right now." | The request was blocked: widget disabled, the embedding domain isn't in Allowed Domains, or the request looked automated | Check the widget is enabled and the site's domain is listed in Allowed Domains (subdomains must be listed explicitly; `www.` is matched automatically). | | "Sorry - our model is down! Try again soon." | The AI provider is temporarily unavailable | Rare; resolves on its own. | | "Sorry, something went wrong. Please try again." | Any other unexpected error | If persistent, [contact support](mailto:team@getchatads.com). | ## Why Isn't the Widget Showing at All? The widget hides itself (no launcher button) when: * The **widget enabled** toggle is off in the Settings tab * The page's domain isn't in your **Allowed Domains** list (when the list is non-empty) * The current path doesn't match your **Page Rules** (include/exclude paths) * **Show on mobile** is toggled off and the visitor is on a small screen * **English browsers only** is on and the visitor's browser language isn't English * Your team already hit its **daily message limit** and this visitor hadn't opened the widget yet that day ## Dashboard Warnings | Warning | Where | What it means | | ------------------------------------ | ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | "Any site can use your chat widget" | Settings tab, Allowed Domains | Your allowlist is empty, so any site could embed your key. Add your production domain(s). | | Per-visitor limit locked at 20 | Settings tab, max messages per day | Raising the per-visitor limit requires domain verification: add a public domain to Allowed Domains and load the widget once on that domain. Localhost doesn't count. | | English-only warning | Settings tab | You turned off the English-browsers-only display gate. The widget shows for all browser languages and the assistant replies in the visitor's language; sponsored Amazon links still only appear on English replies for US visitors. | | "No Amazon Affiliate Tag configured" | Monetize tab | Amazon Affiliate Links is on but no Associates tag is set, so no Amazon links will be inserted. Add your tag. | | "Monetization disabled" | Monetize tab | The linked ChatAds API key that powers Amazon monetization was deleted or revoked. Click Re-enable to create a new one. | | Key regeneration warning | Settings tab, Widget Key | Regenerating your `cwk_` key invalidates the current embed snippet - your widget stops working until you deploy the new snippet. | # WordPress Source: https://docs.getchatads.com/guides/wordpress-integration Add a free AI chat assistant to your WordPress site and earn affiliate revenue from the conversations [ChatAds](https://www.getchatads.com) is an embeddable AI chat widget for publishers. Readers ask your site an AI assistant questions right on the page (like a ChatGPT box that lives in the corner of your posts), and ChatAds monetizes those chats with relevant in-line affiliate links. It works out of the box, with no training or content upload required. The easiest way to install it on WordPress is the official plugin - you paste your widget key, and there's nothing to keep in sync when new widget features ship. ## Why WordPress publishers use it * **A new revenue stream that isn't display ads.** When a reader asks the assistant something with buying intent ("what's a good beginner espresso machine?"), ChatAds can weave in an affiliate link. No banner clutter, no slowing your site down. * **Keeps readers on your page.** Instead of leaving to search elsewhere, readers get answers in context, on your site. * **Zero content work.** The assistant answers general questions immediately. You don't have to feed it your archive or configure prompts to get started. * **You stay in control.** Appearance, which pages it shows on, and whether monetization is on are all managed from the ChatAds dashboard, not in your WordPress admin, so new features ship without you editing anything. ## Install (about 2 minutes) **1. Get your widget key** Sign up at [app.getchatads.com](https://app.getchatads.com) (there's a free tier). On the **Settings** tab, copy your widget key. It starts with `cwk_`. **2. Add it to WordPress** **Option A: Official ChatAds plugin (recommended)** 1. In your WordPress admin, go to **Plugins > Add New**, search for **ChatAds**, and install it 2. Activate the plugin 3. Go to **Settings > ChatAds**, paste your widget key (starts with `cwk_`), and save **Option B: Code-insertion plugin** 1. Install a header/footer script plugin, e.g. [WPCode](https://wordpress.org/plugins/insert-headers-and-footers/) 2. Go to the plugin's header/footer settings screen 3. Paste your embed snippet into the **Footer** field and save: ```html theme={null} ``` **Option C: Google Tag Manager** If GTM is already installed on the site, create a new **Custom HTML** tag containing the snippet above, set the trigger to **All Pages**, and publish the container - no plugin needed. Pasting the snippet directly into `footer.php` via Appearance > Theme File Editor also works, but theme updates or switching themes can wipe it out. The plugin or GTM route survives theme changes. That's it. The launcher pill (default label "Ask AI") appears in the bottom corner of your site. **3. Lock it to your domain** Back on the ChatAds **Settings** tab, add your WordPress site's domain to **Allowed Domains** so no one else can use your key. ## Turning on monetization (optional) Monetization is off by default. In the dashboard you can enable either or both: * **Amazon affiliate links** - the assistant recommends real products and links them with your Amazon Associates tag. * **Affiliate link scraping** - reuses the affiliate links you already have on the page, plus links to products mentioned on the page. You can also just run the assistant as a free reader-engagement tool with monetization off. ## Customization From the dashboard you control the widget color, welcome message, starter questions, the AI's tone, and which pages it appears on (for example, posts only, not your homepage). None of this touches your WordPress theme. ## Pricing There's a free tier to start. Paid tiers raise the daily message limits. See [getchatads.com](https://www.getchatads.com) for current plans. ## Links * Site: [https://www.getchatads.com](https://www.getchatads.com) * Dashboard / sign-up: [https://app.getchatads.com](https://app.getchatads.com) * Docs: [https://docs.getchatads.com](https://docs.getchatads.com) * Questions: [https://www.getchatads.com/contact](https://www.getchatads.com/contact) # Amazon Associates Setup Source: https://docs.getchatads.com/partners/amazon-affiliates Connect your Amazon Associates account so ChatAds can insert Amazon links under your tag Amazon is the default catalog behind ChatAds' [Amazon Affiliate Links](/guides/chatads-monetization#amazon-affiliate-links) monetization: it's the largest consumer catalog on the internet, and there's nothing to integrate on the supply side. When the AI mentions a product, ChatAds matches it to an Amazon listing and generates a link using **your** Associate ID. The affiliate relationship is entirely yours: * **You earn the commissions** - ChatAds doesn't take a cut of affiliate revenue * **You own the reporting** - track clicks, conversions, and earnings in your [Amazon Associates dashboard](https://affiliate-program.amazon.com/home/reports) * **You manage compliance** - follow Amazon's [Operating Agreement](https://affiliate-program.amazon.com/help/operating/agreement) as with any affiliate integration (see [Affiliate Disclosure](/guides/affiliate-disclosure)) If you don't already have an account: 1. Go to [affiliate-program.amazon.com](https://affiliate-program.amazon.com) 2. Click **Sign Up** and log in with your Amazon account (or create one) 3. Fill in your account information, website details, and preferred payment method 4. Amazon provides your **Associate ID** (also called a tracking ID) The sign-up takes about 5 minutes. Amazon approves most applications immediately, then reviews your first qualifying purchases within 180 days. The specific site running the ChatAds widget must be listed as one of your properties in your Associates account - Amazon's [Participation Requirements](https://affiliate-program.amazon.com/help/operating/agreement) (§1) require this, and links generated for an unlisted site won't earn commission. Already an Associate? Skip ahead - your existing Associate ID works as-is. Your Associate ID looks like `yoursite-20` - typically your site name followed by `-20` for the US marketplace. Find it in the top-right corner of [Associates Central](https://affiliate-program.amazon.com) or under **Account Settings > Manage Your Tracking IDs**. Amazon Associates is a separate program per marketplace, each with its own tracking ID. If you also participate in the UK program, your UK tracking ID typically ends in `-21`. 1. Log into [app.getchatads.com](https://app.getchatads.com) 2. Open the **Monetize** tab 3. Enter your ID in the **Amazon Affiliate Tag (US)** field; if you have a UK tracking ID, add it in the **Amazon Affiliate Tag (UK)** field 4. Save ChatAds picks the tag by marketplace: `.com` links use your US tag, `.co.uk` links use your UK tag. There's no cross-marketplace fallback - if a UK visitor triggers a link and you haven't set a UK tag, ChatAds won't generate a `.co.uk` link for that catalog. A US-only publisher needs just the US tag. Create a dedicated tracking ID for ChatAds (e.g. `yoursite-chatads-20`) so ChatAds-driven conversions show up separately in Amazon's reporting. ## Earnings & Reporting You keep 100% of commissions, so all earnings reporting happens in Amazon's systems: * **[Associates Central](https://affiliate-program.amazon.com/home/reports)** - clicks, orders, and earnings * **[Earnings Report](https://affiliate-program.amazon.com/home/reports/earnings)** - commission breakdowns by product category Amazon pays monthly, approximately 60 days after the end of the month in which the sale occurred. Commission rates vary by category - see Amazon's [commission income statement](https://affiliate-program.amazon.com/help/node/topic/GRXPHT8U84RAYDXZ). On the ChatAds side, the [Click Log Export](/guides/analytics#click-log-export) gives you every individual link click to reconcile against Amazon's reports. ChatAds inserts the links; it doesn't process or track Amazon commissions. For questions about earnings, payouts, or rates, refer to [Amazon Associates Help](https://affiliate-program.amazon.com/help). ## Using a Different Catalog If you have your own product feed, brand inventory, or a private affiliate network you'd rather link to, ChatAds can use it instead - see [Custom Catalogs](/partners/custom-catalogs). # Custom Catalogs Source: https://docs.getchatads.com/partners/custom-catalogs Point ChatAds at your own product feed instead of (or alongside) Amazon Amazon isn't the only catalog ChatAds can link to. If you have your own product feed, direct brand inventory, a private affiliate network, or a curated SKU list, ChatAds can use it as the catalog behind your widget's product links. ## What Is a Custom Catalog? Any set of products you want product mentions to resolve to, instead of (or in addition to) Amazon. Common examples: * **Your own product catalog** - e-commerce platforms, marketplaces, or retailers who want to surface their own SKUs * **Direct brand inventory** - brands who want their products linked directly rather than through an affiliate marketplace * **A private affiliate network** - custom link providers, CJ/Impact/Rakuten feeds, or first-party tracking * **A curated product list** - a hand-picked set of products you trust for your readers ChatAds handles the matching; you supply the catalog and the link format. Product mentions in chat replies then resolve to your inventory, with your tracking and your economics. ## Catalog Feed Format Custom catalogs are uploaded as a flat feed - CSV or JSON, one row per SKU. ### Required Fields | Field | Notes | | ------------ | ---------------------------------------------------------------------------------------------- | | `title` | Full product title. Used to match product mentions and shown as link context. | | `url` | Destination URL for the inserted link. Use whatever tracked link format your network requires. | | `brand_name` | Brand name. Required for accurate matching. | ### Important but Optional | Field | Why it matters | | --------------- | --------------------------------------------------------------------------------------------- | | `product_id` | Unique product identifier, useful for your own reporting and dedup. | | `image_url` | Product image URL. Strongly recommended for any UI that renders product cards. | | `category_name` | Top-level category (e.g. "Kitchen"). Enables category targeting rules. | | `category_path` | Full breadcrumb (e.g. "Home > Kitchen > Cookware"). Enables finer-grained category targeting. | | `price` | USD price. Needed for minimum-price quality filters. | | `stars` | Star rating (e.g. `4.5`). Needed for minimum-rating filters. | | `reviews` | Number of reviews. Needed for minimum-review-count filters. | Leaving an optional field blank simply skips the corresponding filter for that product. ### Example Row ```json theme={null} { "product_id": "YOGA-MAT-001", "title": "Gaiam Essentials Premium Yoga Mat, 72\" x 24\" x 6mm", "url": "https://shop.example.com/p/YOGA-MAT-001?ref=chatads", "brand_name": "Gaiam", "image_url": "https://cdn.example.com/images/yoga-mat-001.jpg", "category_name": "Sports & Fitness", "category_path": "Sports & Fitness > Yoga > Mats", "price": 24.99, "stars": 4.4, "reviews": 18420 } ``` ## Getting Started Custom catalogs are set up with our team. Reach out to [team@getchatads.com](mailto:team@getchatads.com) for pricing and next steps.