# Heartbeat: Proactive AI Outreach

Have your AVCodex agent check in on a schedule, review what is happening in each room, ticket, or programmer queue, and send a personalized message only when something needs attention.

Heartbeat turns your AVCodex agent from reactive to proactive. Instead of waiting for a tech to start a chat, the agent runs on a schedule, reviews each user's context, memories, and your instructions, and reaches out via email, WhatsApp, Slack, webchat, or webhook when there is something worth saying.

## How It Works

```
On each scheduled run, for each consumer:
  1. The agent reviews the user's memories, recent messages, and your instructions.
  2. It uses every available tool (knowledge search, integrations, web, MCP).
  3. If something needs attention, it delivers a personalized message.
  4. If nothing is worth raising, it stays silent (no noise).
```

The point: a Heartbeat is not a canned drip. It is a full agent evaluation that can search your AS-built docs, query your room-monitoring system, and pull live data before deciding what (or whether) to say.

## Getting Started

**1. Open Heartbeat Settings**

In your agent's **Publish** tab, click **Heartbeat** in the sub-navigation.

**2. Enable Heartbeat**

Toggle on **Enable heartbeat**. The first time you do this, a setup wizard walks you through templates, channels, and schedule.

**3. Write Your Instructions**

Tell the agent what to look for. Treat it like a checklist the agent runs against each user:

```
- Has the room shown DSP errors in Q-SYS Reflect in the last 24 hours?
- Are there programmer tickets older than 5 days with no update?
- Is the commissioning checklist for the BOS-14 refresh missing sign-offs?
- Are any Crestron firmware updates published that affect rooms in this user's portfolio?
```

The agent uses its tools to evaluate each item and only writes a message when something is actually relevant.

**4. Choose Delivery Channels**

Pick one or more channels. The agent generates the message once and delivers it to every selected channel:

| Channel | Best for |
|---------|----------|
| **Email** | Field techs, programmers, and clients who are not always logged in |
| **Webchat** | In-app nudges for users currently in the agent |
| **WhatsApp** | Personal, high-engagement messages (requires WhatsApp integration) |
| **Slack** | Team and workspace notifications (requires Slack integration) |
| **Webhook** | Trigger external workflows (PSA ticketing, dispatch tools) via JSON POST |

You can select more than one. Many AV ops teams pick **Slack** plus **Email** so dispatch sees it in the team channel and the on-call tech sees it in their inbox.

If no channels are selected, the system auto-detects from each user's most recent conversation channel.

**5. Set the Schedule**

Choose how often heartbeats run:

- **Interval**: every N hours (e.g. every 4 hours).
- **Daily**: at a specific time (e.g. 7:30 AM Eastern, before the first morning standup).
- **Weekly**: on a specific day and time (e.g. Monday at 8:00 AM).

## Curated Email Recipients

When email is one of your channels, decide who actually receives email heartbeats:

- **All consumers** (default): every eligible consumer with an email address.
- **Curated list**: only users whose emails match your list.

Useful when you want email going only to senior programmers or account managers, while still pushing to webchat and Slack for everyone else.

To set up a curated list:
1. Select **Email** as a delivery channel.
2. Click **Curated list** on the toggle that appears.
3. Add the email addresses you want to include.

Other channels (webchat, WhatsApp, Slack) still reach all eligible users regardless of the curated email list.

## Additional Recipients

You can add **additional email recipients** who receive heartbeat messages even though they have not chatted with your agent. Useful for:

- An ops manager who wants the same daily room-health digest the techs get.
- A client-side IT director who wants weekly summaries.
- An internal AV-ops mailing list.

Additional recipients receive one shared message (no per-user personalization, because they have no conversation history or memories).

## Slack Channel Broadcasts

If your agent has a Slack integration, you can broadcast Heartbeat output directly to Slack channels. One LLM call generates the message and posts it to every configured channel. Pair this with a `#av-ops-pulse` channel and you have a daily heartbeat for the whole team.

## Testing Heartbeats

Before going live, test the configuration:

1. In the **Test** section, pick a user (your own account is pinned at the top).
2. Click **Run test heartbeat**.
3. The test runs the full agent loop with real tools and delivers on the resolved channel.

> **Note:** Test heartbeats skip scheduling checks (budget, active hours, consecutive OK limits) so you can test anytime. They do not count against your daily or monthly budget and do not affect sweep eligibility.

## Quiet Hours and Anti-Spam

Heartbeat ships with safeguards built in:

- **Active hours**: send only during business hours (for example 7 AM to 7 PM in your timezone).
- **Interaction recency**: skip users who just chatted (default 60 minute cooldown).
- **Consecutive OK limit**: stop checking a user after N consecutive "nothing to say" evaluations (default 5).
- **Deduplication**: do not send the same message text within 24 hours.
- **Daily and monthly budget caps**: hard ceilings on total heartbeat runs per agent.

## How the Agent Decides What to Say

When the agent evaluates a user and has nothing useful to add, it returns `HEARTBEAT_OK` internally. That is silently suppressed. The user never sees it. The result:

- **No noise**: users hear from the agent only when something is real.
- **Cost efficient**: silent check-ins use tokens but are much cheaper than full outreach.
- **Natural follow-up**: when a user replies to a heartbeat, it starts a full conversation with the same context and tools.

## Webhook Delivery

When webhook is a delivery channel, heartbeat output is POSTed as JSON to your URL:

```json
{
  "event": "heartbeat.message",
  "applicationId": "...",
  "applicationName": "Room Health Pulse",
  "consumerId": "...",
  "consumer": { "name": "Jordan", "email": "jordan@yourintegrator.com" },
  "text": "The heartbeat output message",
  "timestamp": "2026-03-19T15:00:00.000Z"
}
```

You can set a **webhook secret** that is sent in the `X-Webhook-Secret` header so you can verify the request.

## Pricing and Limits

Heartbeat is available on **Builder** plans and above. Each tier has its own ceiling:

| Tier | Min Interval | Daily Cap | Users/Sweep |
|------|-------------|-----------|-----------------|
| Free | 60 min | 5 | 5 |
| Builder | 30 min | 50 | 25 |
| Studio | 15 min | 200 | 50 |
| Studio Pro | 5 min | 1,000 | 100 |
| Enterprise | 1 min | 10,000 | 500 |

Each heartbeat evaluation uses tokens from your billing credits (billed per token via Stripe Token Billing). Silent `HEARTBEAT_OK` check-ins are cheaper than full outreach because the agent writes less output.

## Tips for Good Heartbeats

- **Be specific in your instructions.** "Check the calling tech's open tickets in ServiceNow and surface anything older than 5 days" beats "follow up with the user."
- **Lean on your tools.** Design the checklist around what your integrations can actually see: Q-SYS Reflect alerts, Crestron XiO room status, ServiceNow tickets, your AS-built database, manufacturer firmware feeds.
- **Start daily.** A morning briefing is the right cadence for most AV ops teams. Tighten or relax based on the Stats tab.
- **Watch the run history.** The Runs tab shows every evaluation. Look for patterns in skips, failures, and deliveries.
- **Use a smaller model for evaluations.** A model override (for example a fast mini model) keeps cost down while still catching the things that matter.

*AVCodex · Your AV expertise. Amplified by AI.*