Skip to main content
Hacktionbase.onTrigger(handler)
Hacktionbase.onTrigger(key, handler)
Subscribes to chat trigger events forwarded from the widget. Whenever a trigger is executed (the user clicked the CTA proposed by the chatbot), the handler runs in your host page with the extracted data. Returns an unsubscribe function. Call it to remove the listener.

​
Parameters

​
key
string
Optional. Scope the handler to a single trigger key. Omit to receive every executed trigger.
​
handler
(event: TriggerEvent) => void
required
Called once per matched execution. The event payload is described below.

​
Event shape

interface TriggerEvent {
  id: string;                       // Trigger document ID
  key: string;                      // Stable trigger key (e.g. "create_project")
  data: Record<string, string>;     // Fields extracted from the user message
  executionEventId: string;         // Unique ID for this execution (dedupe)
  userId: string | null;            // Set only when the session is identified
  anonymousId: string;              // Always present — the session identity
  occurredAt: string;               // ISO timestamp
  context: {
    tenantId: string;
    userId: string | null;          // Same as top-level userId
    anonymousId: string;            // Same as top-level anonymousId
    accountId: string | null;       // Current account (via identify({ account }))
  };
}
The session is always identified by anonymousId. When the user has been identified via Hacktionbase.identify(), userId is also set; otherwise it is null. To distinguish an identified vs. anonymous session, check whether userId is non-null.

​
Examples

​
Listen for a single trigger

const unsubscribe = Hacktionbase.onTrigger('open_billing', (event) => {
  window.location.href = '/billing';
});

// Later, when you no longer need the handler
unsubscribe();

​
Prefill a form from extracted data

Hacktionbase.onTrigger('create_project', (event) => {
  const { name, plan } = event.data;
  document.querySelector('#project-name').value = name ?? '';
  document.querySelector('#project-plan').value = plan ?? 'starter';
  Hacktionbase.close();
});

​
Catch every trigger (e.g. for analytics)

Hacktionbase.onTrigger((event) => {
  analytics.track('chat_trigger_fired', {
    key: event.key,
    executionEventId: event.executionEventId
  });
});

​
Security

  • Trigger events are scoped to the current session. Your handler will never receive an event from another user.
  • The same executionEventId is delivered to your backend webhook — use it to correlate the two, or to deduplicate retries.
  • For sensitive actions, prefer running the side effect in your backend webhook (where you can verify the HMAC signature) and use onTrigger only for UI side effects (redirect, prefill, toast).