Brand advocate discovery board for influencer outreach

Build me a brand advocate discovery board. Our influencer marketing lead needs to browse the people who are actually talking about us and build an outreach shortlist from them, instead of exporting mentions out of Brandwatch and pivoting them in a spreadsheet.

At the top of the app, put a controls bar with a Brandwatch project picker, a query picker, and a date range. Populate the project picker from the Brandwatch List Projects operation, and populate the query picker from List Queries scoped to the selected project. Next to those, put a Refresh button and a label showing when the data was last pulled.

When the user refreshes, a handler pulls mentions for the selected query and date range using the Brandwatch Retrieve Mentions operation, following cursor pagination until the pages run out or a sane page cap is reached. This is the single most important design constraint: Brandwatch limits the entire organization to roughly 30 API requests per 10 minutes, so the app must pull the mention set once per refresh and then serve the table, the filters and the row expansion from that one snapshot. Never fetch per author and never re-query Brandwatch when the user changes a filter or opens a row. Keep the pulled mentions server side for the current refresh, show the last refreshed time in the UI, and if Brandwatch returns a rate limit error, show a plain message telling the user to wait a few minutes rather than silently retrying in a loop.

Do the aggregation in the app. Group the pulled mentions by author and build one row per author with: total mentions, combined reach summed across their mentions, dominant sentiment (the most common of positive, neutral and negative, with the underlying counts available), and main channel (their most common page type). Render these as a ranked table sorted by combined reach descending by default, with sortable columns so the lead can flip to ranking by mention count instead.

Give the table three filters plus a search box: a positive-only toggle that narrows the list to advocates, a minimum mention count so one-off posters drop away, and a page type filter covering the channels present in the data such as X, Instagram, blogs and forums. The search box filters by author name or handle. All filtering happens against the already-pulled snapshot.

Clicking a row expands it to show that author's recent mentions from the same snapshot. For each mention show the date, the page type, its sentiment, a snippet of the text, and a link out to the original post so the lead can read it in context.

Every author has a status the user can set: New, Shortlisted, Contacted or Passed. Persist status in the app's own storage keyed by the author's identity, not in Brandwatch. It must survive between sessions and be shared across the whole team, so anyone opening the board sees the same pipeline rather than their own private copy. Default authors with no saved status to New, let the user change status straight from the table row, and add a status filter plus a count per status so the lead can pull up just the shortlist.

Let the user maintain an exclusion list so our own brand accounts, news wires and syndicated republishers never pollute the advocate ranking. Add an Exclude action on each row, and a small settings view listing everything currently excluded with the ability to remove entries. Excluded authors are dropped from the ranking and the aggregation entirely. Persist the exclusion list in app storage and share it across the team the same way statuses are shared.

Each author row also gets an Add to HubSpot action. The handler first calls the HubSpot Search Contacts operation to look for an existing contact matching that author so we do not create duplicates. If a match exists, reuse it; if not, create the person with the HubSpot Create Contact operation. Then use the HubSpot Create Note operation to attach outreach context to that contact: their top mentions with links, their combined reach, their dominant sentiment, their main channel, and the query and date range the numbers came from. Associate the note with the contact. Once an author has been added, show an In HubSpot badge on their row linking to the contact record, and do not silently change their status, since adding someone to the CRM is not the same as having contacted them.

Handle the obvious states properly: a first-run state before any project and query are chosen, a loading state during the mention pull that makes clear it may take a moment, an empty state when the query and date range return no mentions, and a clear error state if Brandwatch or HubSpot rejects the call.