Proactive triggers

New to this? Start with Authoring proactive triggers for a step-by-step walkthrough of building your first trigger.

​

How it works in three steps

User actions → ProactiveTriggerContext → ProactiveTriggerRegistry.evaluate_first()
                                                        ↓
                                          ProactiveTriggerResult  (or None)
                                                        ↓
                                              Your delivery layer
                                         (Intercom quick_reply, modal, etc.)

1. Build context — On each tick, construct a ProactiveTriggerContext from your event buffer (recent actions, canonical URLs, session summary, etc.).
2. Evaluate — Call registry.evaluate_first(ctx). The registry walks its triggers in priority order and returns the first ProactiveTriggerResult whose predicate matches, or None.
3. Deliver — Pass the result’s body and optional reply_option_labels to your delivery layer. Gate on SessionState (v2) before sending.

​

Quickstart

from autoplay_sdk.proactive_triggers import (
    PredicateProactiveTrigger,
    ProactiveTriggerContext,
    ProactiveTriggerRegistry,
)

# 1. Define a trigger
trigger = PredicateProactiveTrigger(
    trigger_id="high_action_volume",
    body="Looks like you've been busy — need a hand?",
    predicate=lambda ctx: ctx.action_count >= 12,
)

# 2. Register it
registry = ProactiveTriggerRegistry([trigger])

# 3. Build context and evaluate on each tick
ctx = ProactiveTriggerContext(
    session_id="sess_abc",
    product_id="prod_xyz",
    action_count=14,
    # ... other fields
)

result = registry.evaluate_first(ctx)

if result:
    print(result.trigger_id)   # "high_action_volume"
    print(result.body)          # "Looks like you've been busy — need a hand?"

​

Module: autoplay_sdk.proactive_triggers

​

Core types

​

Proactive data structures (full map)

​

Default timing constants

​

Custom payload sources (RecentActionsPayloadSource)

​

Monitor cadence and context source

• build ProactiveTriggerContext from a recent, ordered action slice,
• run proactive delivery evaluation only when SessionState is eligible for unsolicited help (effectively THINKING),
• continue running idle-expiry checks for already-open proactive UI on each monitor sweep.

​

Built-in trigger IDs

​

user_page_dwell — time on page + sparse actions

1. Dwell time — The time span of that streak is at least dwell_threshold_seconds.
   • Default: 60 (one minute). This is the minimum time the user must stay on the same canonical URL before the trigger can match.
2. Sparse actions — The number of actions in that streak is at most user_page_dwell_max_actions.
   • Default: 5. If the user has more than this many actions on the same URL streak, the trigger does not fire (treats it as active exploration, not passive linger).

​

Section playbook — product_section_playbook + section_playbook

• integration_config.proactive_triggers.section_url_rules — ordered array of { "prefix": "<canonical_url_prefix>", "section_id": "<stable_id>" }. First matching prefix wins (put longer/more specific prefixes first).
• section_url_fallback_id — optional bucket id for URLs that match no prefix (defaults internally to other when resolving unmapped paths).

​

ProactiveTriggerContext fields

​

Event connector JSON (builtins)

{
  "proactive_triggers": {
    "builtins": [
      {
        "id": "canonical_url_ping_pong",
        "name": "URL hesitation",
        "description": "Fires when the user bounces between the same URLs"
      }
    ]
  }
}

• id must match an entry in the built-in catalog (see list_builtin_trigger_catalog()).
• name and description are required non-empty strings — used for display, analytics, and admin UIs.
• interaction_timeout_s and cooldown_s are optional; omit to use the catalog’s defaults.
• registry must be omitted or "default".
• mode: "ping_pong_only" restricts results to canonical_url_ping_pong only.
• Invalid rows raise SdkConfigError and log event=proactive_builtin_spec_invalid.

​

When a user chooses a proactive option

1. Delivery layer receives selected chip/option id from the user.
2. Resolve selected id to TriggerMessage.
3. Update SessionState interaction path (for example, record option interaction and keep session routing state current).
4. If TriggerMessage.user_tour_exists is true, resolve tour metadata in TourRegistry:
   • by chip id (TourDefinition.id) when ids are aligned, or
   • by user_tour_id (TourRegistry.get_by_user_tour_id(...)) when using provider flow IDs.
5. Start visual guidance and continue timeout/cooldown handling using session state + tour timing rules.

​

Related pages

• Authoring proactive triggers — Step-by-step: build a trigger, build context, register and evaluate, handle delivery.
• Agent session states — SessionState v2 gating and idle expiry behavior.
• Intercom integration — quick_reply HTTP shape, delete-conversation helpers.
• Typed payloads — SlimAction, ActionsPayload, SummaryPayload.