Interview Agents

How Interview Agents work

A tour of the runtime — what happens between a page load and a finished interview, including identifying users and passing custom session metadata.

This page walks through what actually happens when Seena is installed on a page — from the moment the script loads to the moment a finished interview lands in your dashboard.

1. The widget loads

The seena.js script initializes in the background after your page becomes interactive. It reads your data-site-id from the script tag, fetches the agent configuration for that site, and starts a session — a unique record for this visitor's time on your site.

2. The session collects context

As the visitor moves through your site, the widget records lightweight context it'll use later:

  • Pageviews and the sequence between them
  • Time on each page
  • Scroll depth
  • Exit intent (when the cursor leaves the window upward)
  • Clicks on any element the agents are watching for
  • Optional custom events you send with window.seena('track', eventName, properties)

None of this is visible to your visitors. It's purely for deciding when an agent should engage and, if one does, giving the agent enough context to have a real conversation.

3. Identifying your users

If your app has signed-in users, you can tell Seena who they are either by setting the variables globally in the same install script 

<script src="https://app.seenalabs.io/widget/seena.js"
        data-site-id="..."
        data-custom-data='{"environment":"production","region":"us-east"}'>
</script>

Or you can set a window.Seena.setCustomData object for more granularity and control. 

window.Seena.setCustomData({
  customer_id: 'cus_abc123',
  plan_tier: 'enterprise',
});

window.Seena.setCustomData({ plan_tier: 'free' });   // update
window.Seena.setCustomData({ plan_tier: null });     // delete that key

With user identity set, interviews attach to that user in your dashboard. You can filter sessions, insights, and briefings by specific users; you can see a longitudinal view of one user's feedback across many visits.

If you don't identify users, sessions are anonymous and stitched by browser fingerprint within a visit. That's fine for public marketing pages; it's usually not what you want for authenticated product surfaces.

4. Custom session metadata and tags

Besides user identity, you can attach arbitrary metadata to any session. Use window.seena('identify', …) or set it in window.seenaConfig:

window.seenaConfig = {
  user: { id: '...', email: '...' },
  session: {
    plan: 'pro',
    experiment: 'checkout-v3',
    accountAge: 'new', // or 'returning' — anything you want
  },
};

These become searchable facets in your dashboard — filter interviews by plan, experiment arm, cohort, or any other dimension you care about. They're also available to the agent at conversation time, so you can write agent instructions that reference them.

5. Trigger evaluation

On every meaningful event (pageview, scroll milestone, click, timer tick, exit), the widget evaluates every agent's trigger conditions. The general feedback agent is always available. Custom agents fire only when their conditions match and the workspace's governance rules allow it:

  • Has this visitor already been invited the maximum times this session?
  • Has enough time passed since the last invitation in this session?
  • Has the visitor dismissed too many invitations recently?
  • Did this visitor participate in an interview within the recurrence window on this site?

The full rule set is documented in Agent governance.

6. The invitation

When a custom agent passes all checks, the pill on the page appears, or it morphs from "Feedback" (if the feedback agent is enabled) to that agent's invitation. The visitor can accept, ignore it, or dismiss. Dismissals count toward the escalation threshold; ignoring doesn't.

7. The conversation

When the visitor accepts, the widget opens into an interview view. For voice-mode interviews, it asks for microphone permission. For text mode, the user can just use text.

The agent asks the first question, listens, asks a natural follow-up, and wraps up. Most conversations land between 30 and 90 seconds. The visitor can end the conversation at any time — Seena never holds anyone hostage to finish.

8. Analysis

After the conversation ends, Seena transcribes it, extracts insights, links them to the events from the session, and rolls them into your daily or weekly briefings. You don't do any of this manually.

See What is an insight and What is a briefing for what lands in your dashboard.

What to read next