> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hacktionbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chat Triggers

> Turn natural-language chat messages into actions inside your product.

## Overview

Chat triggers let your widget chatbot **drive concrete actions** in your product instead of just answering questions. When a user message matches a trigger you've defined, the chatbot proposes a call-to-action button in the conversation. If the user confirms, Hacktionbase fires a signed webhook to your backend and a real-time event to the originating session so your app can react instantly — redirect the user, prefill a form, create a resource, anything you wire up.

## How a trigger flows

```
1. User types a message in the widget
2. Vector search pre-filters trigger candidates by intent description
3. LLM extracts the declared fields from the message
4. Chatbot proposes a CTA button under its reply (e.g. "Create project")
5. User clicks the CTA (explicit confirmation)
6. Hacktionbase fires the signed webhook + emits a WS event to the session
7. Your SDK handler (or backend) runs the action
```

Confirmation is **mandatory** in v1 — nothing executes without the user clicking the CTA. This protects against accidental side effects from a misread intent.

## Anatomy of a trigger

| Field                  | Description                                                                                                                                     |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Key**                | Stable identifier used by your SDK handler (e.g. `create_project`).                                                                             |
| **Intent description** | Plain-text description of when the trigger should match. Embedded for vector search — write it the way you'd describe the user's goal.          |
| **Fields**             | Typed parameters the LLM extracts from the message. Each field has a `name`, `type` (`string`, `number`, `boolean`, `enum`), and `description`. |
| **CTA label**          | The button text shown under the bot's reply (e.g. "Open billing").                                                                              |
| **Audience scope**     | `authenticated` (identified users only) or `anonymous` (allowed for everyone).                                                                  |
| **Channels**           | Webhook URL (signed HMAC), WebSocket event (forwarded to the SDK), or both.                                                                     |
| **State**              | `draft` or `active`. Only active triggers participate in detection.                                                                             |

## Audience scope

* **Authenticated** — the trigger only matches when the user has called `Hacktionbase.identify(...)`. Use this when the action depends on knowing who the user is (create a record under their account, redirect to their dashboard, etc.).
* **Anonymous** — allowed for visitors who haven't been identified. The WS event is routed by `anonymousId`. Use for low-stakes navigation or generic prefill.

## Plan gating

Chat triggers are available on the **growth**, **scale**, and **galaxy** plans. The free plan can read trigger configuration but cannot activate any.

## Limits

| Limit                      | Value                             |
| -------------------------- | --------------------------------- |
| Active triggers per tenant | 50                                |
| Fields per trigger         | 10                                |
| Webhook payload            | 64 KB                             |
| Webhook timeout            | 5 s                               |
| Webhook retries            | 3 (exponential backoff, then DLQ) |

## Webhook delivery

Webhooks are dispatched asynchronously via SQS so your endpoint's latency never blocks the chat reply. Each request is signed with an HMAC header your backend can verify to ensure authenticity. Failed deliveries are retried with backoff and end up in a dead-letter queue you can inspect from the dashboard.

## What's next

* See [`Hacktionbase.onTrigger`](/sdk/on-trigger) to handle trigger events in your frontend.
* See [Trigger pipeline](/concepts/triggers) for the platform-level architecture.