Heartbeat System

The heartbeat system automatically re-engages contacts who have not responded within a configurable time interval.

How It Works

When a conversation enters WAITING_FOR_REPLY and the contact does not respond within the configured heartbeat interval, the system:

1. Transitions the instance to HEARTBEAT_SCHEDULED
2. The agent composes and sends a follow-up message
3. The instance transitions back to WAITING_FOR_REPLY
4. The cycle repeats until the contact responds or max follow-ups are reached

Configuration

Set heartbeat parameters when creating a conversation:

relay create \
  --contact="+56912345678" \
  --objective="confirm delivery" \
  --todos="ask ETA" \
  --heartbeat-interval=1800000 \
  --max-followups=5

The agent can also override the next heartbeat delay dynamically using the schedule_next_heartbeat(delay_ms) tool during a conversation.

Behavior

• Follow-up content: the agent decides the follow-up message based on conversation context and objective
• Abandonment: when max follow-ups are reached and the contact still has not responded, the instance transitions to ABANDONED
• Pausing: when an instance is paused, heartbeat timers are suspended. They resume when the instance is resumed.

Monitoring

Check heartbeat state for an instance:

relay get <instance-id>

Output includes:

• Current follow-up count (e.g., 2/5)
• Heartbeat configuration (interval and max follow-ups)