Scout: AI support messenger

Scout — your AI product explorer. Scout is an Intercom-style messenger that Guidely adds to your product. End users open a chat bubble, ask questions and get answers drawn from your help articles, browse the articles themselves, and reach your team when Scout can't help. Your team answers handed-off conversations in the dashboard Inbox.

Customer app ── chat bubble: Home · Messages · Help
      │  question
      ▼
   Scout (Claude) ── reads articles, FAQs, learned answers ── answers with article links
      │  "talk to a person", billing/account questions, no answer, limits reached
      ▼
   Inbox (dashboard) ── a teammate replies and closes it ── the user sees it in the messenger
      │
      ▼
   Learned answer (question + how it was solved) ── used by Scout next time

Turning it on

1. **Articles.** Write them in **Resource center**, or click **Import articles** to upload Markdown,

   text, PDF or Word files. Scout drafts one or more articles from each file as unpublished drafts: review, edit and publish them. The From Intercom tab copies every article in an Intercom help center through the Intercom API (an access token with “Read and list articles”, and the workspace's US/EU/AU region), recreating its collections or putting everything in one collection. Articles arrive as drafts unless you choose to publish the ones live in Intercom; ones imported before are skipped, so you can run it again to pick up new articles. Scout only uses published articles.

2. **Anthropic API key** (dashboard → **Scout**, admins): add a key for this project, or rely on the

   server-wide ANTHROPIC_API_KEY if your Guidely server has one. A project key takes precedence and bills that project's usage to its own Anthropic account. Guidely checks the key with Anthropic, stores it encrypted and only ever shows its last four characters.

3. **Scout settings** (admins): switch on *Show the messenger in your app*, choose where it shows

   under Show it on (Web, iOS, Android — any combination; projects created before mobile support are web-only until you tick a mobile platform), name your product and describe it in About your product, set the greeting, optional instructions (tone, scope, when to escalate), whether people can reach the team, notification emails, and reply limits. Try questions in the Playground before going live; it uses published articles and saves nothing.

4. **Install** — nothing extra beyond SDK **0.2.1 or later** for the web (`@guidelytech/*` 0.1.0 predates

   the messenger and ignores it). Every Guidely SDK (React, Next.js, Svelte, SvelteKit, script tag, React Native, iOS, Android) shows the messenger once it is enabled for its platform. On the web the widget code is a separate ~9 kB chunk that only loads for projects with the messenger on; in mobile apps it is drawn with native UI (see mobile.md).

The messenger replaces the resource center launcher: its Help tab shows the same articles, recommended guides, checklists, FAQs and links.

How Scout answers

• Scout answers for one project only: its published articles, the guides live in the user's

  environment, and that project's product name and About your product text (falling back to the project's name and description). It introduces itself as the assistant inside your product and declines requests unrelated to it.

• Scout sees a catalog of your published article titles and summaries, your published resource-center

  FAQs (question and answer, up to 30,000 characters in all), its learned answers and the guides live in the user's environment. It reads the relevant articles (full-text search over title, summary and body) before answering and cites them; citations appear as article cards under the reply.

• Audience targeting applies to Scout too: articles (or collections) targeted at audiences the

  visitor isn't in are left out of the catalog, search and article reads, so Scout never quotes or cites them. Membership comes from the visitor's last identify(); anonymous visitors only get untargeted articles. In the Playground, the All articles menu switches to answering as a visitor in a given audience (or in none). As in the widget, this is not access control.

• When a published walkthrough fits, Scout offers a Show me button that starts the guide.
• When the articles don't cover the question, the user asks for a person, or the question needs

  someone with account access, Scout hands the conversation to the team (if enabled) and says so.

• Replies stream into the messenger as they are written. Scout runs on Claude (`claude-opus-5` by

  default, SCOUT_MODEL), with up to 6 lookup rounds per reply.

Without an Anthropic key (the project's own or ANTHROPIC_API_KEY on the server), or with Let Scout answer off, the messenger still works: every conversation goes straight to the Inbox.

How Scout learns

Scout gets better from the conversations your team resolves:

1. Scout hands a conversation to the Inbox (or the user asks for a person) and a teammate answers.
2. When the conversation is **closed**, the worker studies it a couple of minutes later. Claude decides

   whether the teammate solved something other customers will ask too and, if so, writes a learned answer: the question in general terms and how it was solved, using only what the teammate said, without names, accounts or other personal details. One-off account fixes (refunds, manual changes), bug reports and small talk are skipped.

3. If an existing learned answer covers the same question, it is updated and counts one more source

   instead of adding a duplicate. Answers a teammate edited or turned off are never rewritten.

4. Scout uses learned answers in later replies (the 60 most recently updated in its prompt, the rest

   through search) when articles and FAQs don't cover the question; articles and FAQs win when they disagree. Learned answers are not cited as article cards, and Scout never mentions past conversations.

The Scout page lists What Scout has learned: approve, edit, turn off, delete, or add an answer yourself (editors with Publish articles). Settings: Learn from resolved conversations (on by default) and Review learned answers first, which holds new ones as To review until approved. A teammate replying again in a closed conversation makes it worth studying again on the next close. Conversations already closed when learning is switched on are studied too, oldest first, five per worker pass. Learning needs the worker and an Anthropic key, like imports.

A good learned answer often belongs in an article: copy it into the Resource center when it is worth showing to everyone in the Help tab.

Inbox

Inbox lists conversations that need a reply (handed off or in progress with the team), those Scout is handling, yours, and closed ones. Replying takes the conversation over from Scout and assigns it to you if unassigned; close it when done (the user can rate it, and a new message reopens it). New handoffs and user replies email the addresses in Scout settings (SMTP_URL; logged when unset).

User identity in the Inbox is unverified. The name, id and traits shown come from what the app passed to identify() in the browser, which anyone can call. Don't disclose account details to someone based on them alone.

Developer API

guidely.openMessenger()            // or openMessenger("help" | "messages" | "home")
guidely.showNewMessage("I need help with exports")
guidely.closeMessenger()
guidely.on("conversation:message", ({ message, conversation }) => { /* Scout or a teammate replied */ })
guidely.on("messenger:open", () => {})

The same calls exist in the mobile SDKs: openMessenger(tab), showNewMessage(text) and closeMessenger() on the React Native client and Guidely.shared (iOS) / Guidely (Android).

openResourceCenter() opens the Help tab when the messenger is on. reset() (on logout) forgets the browser's conversations.

Conversations belong to the browser or app install that started them: the SDK stores a per-conversation token, so history does not follow a user across devices yet, and a shared computer loses it on reset().

Limits and costs

Past a limit, conversations go to the Inbox instead. Each Scout reply stores its token usage (returned with the message by GET /conversations/:id); the Scout page shows replies used this month and the Playground shows the usage of each test reply.

Troubleshooting: the messenger doesn't appear

1. **SDK version.** Check that your app has `@guidelytech/*` 0.2.1 or later (`npm ls @guidelytech/sdk-core`).

   0.1.0 has no messenger code.

2. **Environment and platform.** The messenger shows in every environment of the project, but your

   app must use a key from this project (pk_… on the Setup page), and its platform (Web, iOS or Android) must be ticked under Show it on.

3. Config refresh. Settings reach the app on its next config fetch; reload the page.
4. No AI key doesn't hide the messenger: users can still write, and conversations go to the Inbox.

Data handling

Conversation text, the article catalog, article bodies Scout reads, FAQs and learned answers are sent to the Anthropic API to generate replies; uploaded files are sent to draft articles, and resolved conversations are sent to write learned answers. Nothing else (traits, events, URLs) is sent. Closed conversations and conversations nobody is waiting on follow the project's event retention. See security.