> ## 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.

# Widget Overview

> How the Hacktionbase widget works on your site.

## Architecture

The Hacktionbase widget is an **iframe** embedded in your page by the SDK. It communicates with the SDK via the browser's `postMessage` API.

```
┌──────────────────────────────────┐
│         Your Website             │
│                                  │
│   ┌────────────────────────┐     │
│   │   Hacktionbase SDK     │     │
│   │   (bubble + listeners) │     │
│   └──────────┬─────────────┘     │
│              │ postMessage        │
│   ┌──────────▼─────────────┐     │
│   │   Widget iframe        │     │
│   │   ({tenant}.hacktionbase.com) │
│   │   - Conversations      │     │
│   │   - In-app messages    │     │
│   └────────────────────────┘     │
└──────────────────────────────────┘
```

## Components

The widget consists of two visible elements:

1. **Bubble** — a floating button in the corner of the page. Clicking it toggles the panel open/closed.
2. **Panel** — the iframe containing the widget UI (conversations, messages).

## Lifecycle

1. `Hacktionbase.init()` fetches the widget configuration from the API
2. The SDK injects CSS, creates the bubble, and creates a hidden iframe
3. When the iframe loads, it sends `hacktionbase:ready`
4. The SDK responds with config and session context
5. The widget authenticates via the widget auth endpoint and receives a JWT
6. The user can now open the panel, view conversations, and receive in-app messages

## PostMessage protocol

All messages between the SDK and widget use a `hacktionbase:` prefix:

### SDK → Widget

| Message                       | Description                                                        |
| ----------------------------- | ------------------------------------------------------------------ |
| `hacktionbase:widget_context` | Session data (sessionId, anonymousId, userId, sdkKey, device info) |
| `hacktionbase:config`         | Widget appearance configuration                                    |
| `hacktionbase:identify`       | User identification data                                           |

### Widget → SDK

| Message                            | Description                                      |
| ---------------------------------- | ------------------------------------------------ |
| `hacktionbase:ready`               | Widget iframe has loaded                         |
| `hacktionbase:close`               | User clicked close button in the widget          |
| `hacktionbase:widget_auth_success` | Authentication complete (includes widget JWT)    |
| `hacktionbase:show_modal`          | Trigger an in-app message modal in the host page |
| `hacktionbase:resize`              | Request panel height change                      |

<Note>
  All postMessage communication is origin-verified. The SDK only accepts messages from your tenant's widget origin (`{tenant}.hacktionbase.com`).
</Note>