# Heartbeat - Proactive AI Outreach

Set up your AI to automatically check in with users on a schedule, delivering personalized messages via email, WhatsApp, Slack, webchat, or webhooks.

---

Heartbeat turns your AI from reactive to proactive. Instead of waiting for users to start a conversation, your agent periodically checks in with each consumer -- reviewing their context, memories, and your instructions -- and sends a personalized message when something needs attention.

## How It Works

```
On each scheduled run, for each consumer:
  1. Your AI reviews the consumer's memories, recent messages, and your instructions
  2. It uses all available tools (knowledge search, integrations, web browsing, etc.)
  3. If something needs attention → delivers a personalized message
  4. If nothing needs attention → stays silent (no spam)
```

The key insight: your AI has access to **all the same tools** as a normal conversation. A heartbeat isn't just a canned message -- it's a full agent evaluation that can search knowledge, check integrations, and gather real-time data before deciding what to say.

## Getting Started


  **1.** 
    <strong>Open Heartbeat Settings</strong>

    Navigate to your app's **Publish** tab and click **Heartbeat** in the sub-navigation.
  


  **2.** 
    <strong>Enable Heartbeat</strong>

    Toggle on **Enable heartbeat**. If this is your first time, a setup wizard walks you through choosing a template, delivery channels, and schedule.
  


  **3.** 
    <strong>Write Your Instructions</strong>

    Tell your AI what to check for. Think of it as a checklist the AI evaluates for each consumer:

    ```
    - Has the user been active in the last 7 days?
    - Any unresolved questions from their last conversation?
    - Is there a relevant product update to share?
    - Are there upcoming deadlines they should know about?
    ```

    Your AI will use its tools to evaluate each item and compose a message only when something is relevant.
  


  **4.** 
    <strong>Choose Delivery Channels</strong>

    Select one or more channels for delivery. Your AI generates the message once and delivers it to all selected channels simultaneously:

    | Channel | Best For |
    |---------|----------|
    | **Email** | Broadest reach -- works even when users aren't online |
    | **Webchat** | In-app nudges for users who are currently active |
    | **WhatsApp** | Personal, high-engagement messages (requires WhatsApp integration) |
    | **Slack** | Team and workspace notifications (requires Slack integration) |
    | **Webhook** | Triggering external workflows via JSON POST |

    You can select multiple channels at once. For example, select both **Email** and **Webchat** to reach users wherever they are.

    If no channels are selected, the system auto-detects from each consumer's last conversation channel.
  


  **5.** 
    <strong>Set the Schedule</strong>

    Choose how often heartbeats run:

    - **Interval**: Every N hours (e.g., every 4 hours)
    - **Daily**: At a specific time each day (e.g., 9:00 AM Eastern)
    - **Weekly**: On a specific day and time (e.g., Monday at 9:00 AM)
  


## Curated Email Recipients

When email is one of your selected channels, you can choose who receives email heartbeats:

- **All consumers** (default): Every eligible consumer with an email address gets the heartbeat
- **Curated list**: Only consumers whose emails match your curated list receive email heartbeats

This is useful when you want to target specific users for email outreach while still delivering to all users on other channels like webchat.

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

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

## Additional Recipients

Beyond your existing consumers, you can add **additional email recipients** who receive heartbeat messages even though they haven't chatted with your app. This is great for:

- Team members who want to stay informed
- Stakeholders who need regular updates
- Email lists for broadcast-style outreach

Additional recipients get a single shared message (no per-user personalization since they have no conversation history or memories).

## Slack Channel Broadcasts

If your app has a Slack integration, you can broadcast heartbeat messages directly to Slack channels. This works independently of per-consumer delivery -- one LLM call generates the message, and it's posted to all configured channels.

## Testing Heartbeats

Before going live, test your heartbeat configuration:

1. In the **Test** section, select a consumer (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 to the resolved channel

> **Note:** Test heartbeats bypass scheduling checks (budget, active hours, consecutive OK limits) so you can test anytime. They don't count toward your daily/monthly budget or affect sweep eligibility.

## Quiet Hours & Anti-Spam

Heartbeat includes several built-in safeguards:

- **Active hours**: Only send during business hours (e.g., 9 AM - 10 PM in your timezone)
- **Interaction recency**: Skip consumers who just chatted (default: 60 min cooldown)
- **Consecutive OK limit**: Stop checking consumers after N consecutive "nothing to say" evaluations (default: 5)
- **Deduplication**: Don't send the same message text within 24 hours
- **Daily/monthly budget caps**: Hard limits on total heartbeat runs per app

## How the AI Decides What to Say

When the AI evaluates a consumer and has nothing useful to say, it responds with `HEARTBEAT_OK` internally. This is silently suppressed -- the consumer never sees it. This means:

- **No spam**: Consumers only hear from your AI when something is genuinely relevant
- **Cost efficient**: Silent check-ins use tokens but are much cheaper than full outreach messages
- **Natural conversations**: When a consumer replies to a heartbeat message, it starts a full conversation with complete context and tools

## Webhook Delivery

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

```json
{
  "event": "heartbeat.message",
  "applicationId": "...",
  "applicationName": "My App",
  "consumerId": "...",
  "consumer": { "name": "Jane", "email": "jane@example.com" },
  "text": "The heartbeat output message",
  "timestamp": "2026-03-19T15:00:00.000Z"
}
```

You can optionally set a **webhook secret** that's sent in the `X-Webhook-Secret` header for request verification.

## Pricing & Limits

Heartbeat is available on **Builder** plans and above. Each tier has different limits:

| Tier | Min Interval | Daily Cap | Consumers/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 through Stripe Token Billing). Silent `HEARTBEAT_OK` check-ins are cheaper than full outreach messages since the AI generates less output.

## Tips for Great Heartbeats

- **Be specific in your instructions**: "Check if the user has unresolved support tickets" is better than "Follow up with the user"
- **Use your tools**: Design instructions around what your integrations can check -- calendar events, knowledge base updates, CRM data
- **Start with daily**: Begin with a daily schedule and adjust based on the analytics in the Stats section
- **Monitor the run history**: The Runs tab shows every heartbeat evaluation -- check for patterns in skips, failures, and deliveries
- **Use a cheaper model**: Set a model override (e.g., GPT-4.1 mini) for heartbeat evaluations to reduce cost while maintaining quality