Hot Lead Alert System — tRPC Router

Version 1.0.17 introduces the tRPC router that backs the Hot Lead Alert System. These endpoints are consumed by the alerts page UI, the contact detail page, and dashboard widgets.

Overview

The Hot Lead Alert System surfaces high-intent contacts to agents in real time. The tRPC router provides three core alert procedures and two intent score procedures.

Alert Procedures

`alerts.list`

Returns a paginated list of hot lead alerts. Supports filtering by acknowledgement state.

Input

Parameter	Type	Required	Description
`cursor`	`string`	No	Pagination cursor from a previous response
`limit`	`number`	No	Number of results per page (default: 20)
`acknowledged`	`boolean`	No	Filter by acknowledged (`true`) or unacknowledged (`false`) alerts. Omit to return all.

Output

{
  items: Alert[],
  nextCursor: string | null
}

Used by: Alerts page UI, Dashboard widgets (unacknowledged filter)

`alerts.acknowledge`

Marks a single alert as acknowledged. Idempotent — acknowledging an already-acknowledged alert is a no-op.

Input

Parameter	Type	Required	Description
`alertId`	`string`	Yes	The ID of the alert to acknowledge

Output

{
  success: boolean
}

Used by: Alerts page UI

`alerts.getDetail`

Returns full detail for a single alert, including a summary of the associated contact.

Input

Parameter	Type	Required	Description
`alertId`	`string`	Yes	The ID of the alert to retrieve

Output

{
  alert: Alert,
  contact: ContactSummary
}

ContactSummary includes the contact's name, assigned category, current intent score, and CRM reference.

Used by: Alerts page UI, Contact detail page

Intent Score Procedures

`alerts.getIntentScoreHistory`

Returns the full intent score history for a given contact, ordered chronologically. Suitable for rendering a trend chart on the contact detail page.

Input

Parameter	Type	Required	Description
`contactId`	`string`	Yes	The ID of the contact

Output

{
  history: Array<{
    score: number,      // 0–100
    recordedAt: string  // ISO 8601 timestamp
  }>
}

Used by: Contact detail page

`alerts.getCurrentIntentScore`

Returns the most recent intent score for a contact. Lightweight endpoint designed for dashboard widget polling.

Input

Parameter	Type	Required	Description
`contactId`	`string`	Yes	The ID of the contact

Output

{
  contactId: string,
  score: number,       // 0–100
  updatedAt: string    // ISO 8601 timestamp
}

Used by: Contact detail page, Dashboard widgets

UI Surface Map

Page / Widget	Procedures Used
Alerts page	`alerts.list`, `alerts.acknowledge`, `alerts.getDetail`
Contact detail page	`alerts.getDetail`, `alerts.getIntentScoreHistory`, `alerts.getCurrentIntentScore`
Dashboard widgets	`alerts.list` (unacknowledged), `alerts.getCurrentIntentScore`

Pagination

The alerts.list endpoint uses cursor-based pagination. Pass the nextCursor value from a response as the cursor input on the next request to retrieve the following page. A null value for nextCursor indicates there are no further results.

// Example: fetch the next page
const nextPage = await trpc.alerts.list.query({
  cursor: previousResponse.nextCursor,
  limit: 20,
  acknowledged: false
});

Notes

All procedures require an authenticated session. Unauthenticated requests will return a 401 UNAUTHORIZED error.
Intent scores are expressed as integers in the range 0–100.
This router does not include write access to intent scores; scores are computed and written by the AI scoring engine separately.