Set up a listening agent

Listening agents

Open the Listening agents page from the left sidebar (/agents), or open a project and switch to its Listening agents tab. The page is described as: Watch your data on a schedule. Each agent posts a digest into its own chat. If you have none yet, you'll see No agents yet. (or No listening agents yet on the project tab).

New agent

In the side panel header, click the New agent button (an icon-only + button, labelled New agent for screen readers). You can also click the visible New agent button in the empty-state hint, or Add agent on a project tab. Any of these opens the New listening agent modal, whose first step is titled Configure what this agent tracks and when it runs.

Project

Optionally pick a Project. Leaving it as No project makes the agent account-wide; binding it to a project filters it into that project's Listening agents tab. For our cold-brew brand, you might bind it to the Cold Brew project so it sits alongside that project's other work.

Name

Enter a Name — the placeholder is e.g. Daily AI mentions. For our example, something like Daily cold-brew mentions works. The name is just a label; the next field is where the agent earns its keep.

Instructions

Instructions is the most important field. It answers What should this agent summarise from the scraped posts? — and it decides whether each run is a useful read or generic noise. Give it focus: tell it what to surface and what to flag.

Vague instructions ("summarise new mentions") produce a vague digest. Sharp instructions point the agent at the value you care about. For our cold-brew brand:

Summarise new mentions of our cold-brew brand. Flag complaints and feature requests, call out any new pain points or recurring topics, and note competitor comparisons. Skip generic positive chatter.

Patterns that work well: "summarise complaints and feature requests about X", "flag new pain points, trends, or topics that weren't there last run", "surface negative quotes and the platforms they came from." The tighter the instruction, the more each run reads like a briefing rather than a feed.

Datasets

Select one or more Datasets to monitor. This is a multi-select and at least one dataset is required — if you skip it you'll see Pick at least one dataset. Pointing one agent at several datasets keeps them all growing together: for the cold-brew brand you might add your brand dataset, a competitor dataset, and a category dataset to a single agent. If the list is empty you'll see No datasets in this project yet or No datasets in your account yet, which means you need to run a collection first.

Mentions per run

Choose Mentions per run — the options are 10, 25, 50, 100, 150, and 200, defaulting to 50. This sets how many new mentions each run scrapes and adds to the datasets. A larger count means more data added per run, and more cost per run.

Schedule

Pick a Schedule: Daily or Weekly. Weekly adds a day picker. Then choose a time — note it is in (UTC), so convert from your local time. The agent's footer later renders this as, for example, Daily at 9:00 AM.

Next

Click Next to advance to the destinations step. (You can also use Back to return, or Cancel to discard.) The destinations step is optional — the next part of this tutorial covers it.

Connect Slack Workspace

In the Slack notifications card (subtitle Connect Slack channels for your alerts), click Connect Slack Workspace. This redirects you to Slack's OAuth screen to authorize the app. After install, the card shows a green Connected badge.

Only the account owner can do this. If you aren't the owner, ask them to connect the workspace once for the whole account.

Add Channel

With the workspace connected, click Add Channel to open the Add Slack Channel dialog (Post notifications to a Slack channel). In the Slack Channel dropdown (Select channel), pick the channel you want alerts in — for example #brand-mentions. The list is pulled live from the connected workspace; channels already wired to an integration are filtered out, and if every channel is taken you'll see All channels are already integrated.

Optionally click Test to send a test alert (you'll get a Test notification sent confirmation), then click Add Integration. When you add it from the destinations step, the new integration is automatically selected for the agent.

Add Webhook

In the Webhooks card (Send HTTP POST requests to custom endpoints), click Add Webhook. If your plan doesn't include webhook access, this button reads Upgrade plan instead, with the note Webhook integrations are available on Pro and Business plans. In the Add Webhook Integration modal, fill in two fields:

• Integration Name — a label for your own reference, for example Project-mentions to Zapier.
• Webhook URL — the endpoint that receives the POST, for example https://example.com/webhook. It must be a valid http or https URL; otherwise you'll see Please enter a valid webhook URL.

Optionally click Test to fire a test POST (toast Webhook test successful!), then click Add Integration. The webhook is account-scoped, so you can reuse it across multiple agents — select it on the destinations step to attach it.

The run payload

On each completed run the agent sends an HTTP POST with headers Content-Type: application/json and User-Agent: buzzabout/webhook-integration. The body is a tracking_agent.run_completed event — a condensed view:

{
  "event": "tracking_agent.run_completed",
  "agent": { "id": "...", "name": "Daily cold-brew mentions" },
  "run": { "id": "...", "new_mentions_count": 42, "new_comments_count": 11 },
  "short_description": "...",
  "cta_url": "...",
  "mentions_preview": [
    {
      "source": "reddit",
      "url": "https://reddit.com/...",
      "title": "...",
      "text": "...",
      "created_at": "2026-06-08T12:00:00Z"
    }
  ]
}

Every row in mentions_preview has a non-empty url, and created_at timestamps are ISO 8601 UTC. The Test button does not send this shape — it POSTs a minimal { "type": "test", "message": "Hello from buzzabout" } body — so write your handler against the real tracking_agent.run_completed event.

Create agent

Click Create agent to save (the button reads Save changes when editing an existing agent), and your selected destinations are persisted with the agent. You land back on the Listening agents page with the new agent in the side panel. From then on, each run delivers its digest to every destination you attached — and still posts in the chat.

Agent actions

Open the row dropdown labelled Agent actions to manage the agent: Trigger run, Pause or Resume, Edit agent, assign it to a project, or Delete. A manual Trigger run shows a toast — Agent triggered — and polls the agent's chat for about 30 seconds so the digest appears without a refresh. Use Trigger run to confirm the agent works (and that your destinations fire) before waiting for its first scheduled run.

Read run digests

The Listening agents page carries an account-wide summary: a strip of KPI tiles for Mentions, Comments, Engagements, and Words analysed (aggregated across all your agents), and a feed of recent assistant replies. Until any agent has posted its first digest, that feed shows No assistant replies yet — agents will post a digest here after their next run.

To read a specific agent's run digests as a conversation, click its row to open the agent's dedicated chat (/chat/<dedicatedChatId>). Each scheduled or manual run posts its summary there, so you can scroll the run history like any other chat.