---
title: "Chat Compact API Reference and Examples"
canonical_url: "https://apidocs.sportradar.com/resources/widgets/docs/chat-compact/api"
markdown_url: "https://apidocs.sportradar.com/resources/widgets/docs/chat-compact/api.md"
last_updated: "2026-08-10T09:41:36Z"
---

# Chat Compact API Reference and Examples

Complete property reference and integration examples for the Chat Compact widget (`chatCompact`). For product context and layout variants, see [Overview](https://apidocs.sportradar.com/resources/widgets/docs/chat-compact/overview.md).

## Authentication

Chat Compact uses the same Virtual Stadium (VS) authentication model as the full Virtual Stadium web widget. Every integration requires **`channelId`** plus **either** **`jwt`** or **`apiKey`**. Either auth mode works with any layout.

| Mode          | Property | Use case                                                                  |
| ------------- | -------- | ------------------------------------------------------------------------- |
| Authenticated | `jwt`    | Logged-in users who can post messages and use user-specific chat features |
| Read-only     | `apiKey` | Anonymous or preview access—users can view chat without posting           |

> **Info**
>
> You must provide **one of** `jwt` or `apiKey`. The widget validates at runtime that at least one is set together with `channelId`.

**JWT:** Create tokens on your backend (never in browser JavaScript). Include Virtual Stadium scope and product claims.

- [JSON Web Token (JWT)](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/jwt.md) — base claims, `scope: 'vs'`, and VS-specific claims (`apiKey`, `userId`, `displayName`, `userType`, …)
- [Virtual Stadium JWT Authentication](https://apidocs.sportradar.com/resources/virtual-stadium/gettingStarted/authentication.md)

**API key:** Virtual Stadium API key for read-only access (provided during onboarding / moderation setup).

## Properties

| Property       | Type                          | Default        | Description                                                                                                                     |
| -------------- | ----------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `channelId`    | `string`                      | —              | **Required.** Virtual Stadium channel identifier.                                                                               |
| `jwt`          | `string`                      | —              | User JWT for authenticated chat (posting and user-specific features). **Required** unless `apiKey` is set.                      |
| `apiKey`       | `string`                      | —              | API key for read-only chat. **Required** unless `jwt` is set.                                                                   |
| `layoutMode`   | `'compact' \| 'full'`         | `'compact'`    | Compact strip or full chat UI. Full layout (and in-session expanded compact) stretches to fill the parent height.               |
| `variant`      | `'single-row' \| 'three-row'` | `'single-row'` | Compact strip style; applies when `layoutMode` is `'compact'`.                                                                  |
| `onAction`     | `function`                    | —              | Optional callback for user actions (expand/collapse chat, channel switch). See [The onAction callback](#the-onaction-callback). |
| `onDataChange` | `function`                    | —              | Called when widget state changes (loading, errors, licensing).                                                                  |

**Advanced (specialized embeds)**

These props exist for specialized embeds (for example casino lobby shells). They are not required for typical standalone `chatCompact` integration.

| Property                  | Type       | Description                                                                                                        |
| ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------ |
| `drawerPortalContainerId` | `string`   | When set, channel menus render as sheet drawers portaled into the element with this id. Omit for inline dropdowns. |
| `onJackpotWinTrigger`     | `function` | Registration callback for jackpot win effects inside the chat surface.                                             |

## The onAction callback

Pass `onAction` when you need to react to user interactions—for example analytics, or resizing the parent page when the user expands or collapses chat from compact mode.

The widget calls your callback with **one argument**: an object `{ type, data }`.

- **`type`** — Which action occurred. Use this in a `switch` (or equivalent) as the first branch.
- **`data`** — Payload for that action. The shape depends on `type`.

### Action types

| `type`            | When it fires                                | `data` shape                                     |
| :---------------- | :------------------------------------------- | :----------------------------------------------- |
| `'Click'`         | User expands compact strip to full chat      | `{ channelId: string, source: 'ChatExpanded' }`  |
| `'Click'`         | User collapses expanded chat back to compact | `{ channelId: string, source: 'ChatCollapsed' }` |
| `'SwitchChannel'` | User selects a different channel             | Channel tag (`channelId`, …)                     |

For expand and collapse, both actions use `type: 'Click'`. Branch on `data.source`.

Example: coordinate parent layout when chat expands or collapses.

```javascript
function onAction(action) {
    switch (action.type) {
        case 'Click':
            if (action.data.source === 'ChatExpanded') {
                document.getElementById('chat-shell').classList.add('is-chat-expanded');
            } else if (action.data.source === 'ChatCollapsed') {
                document.getElementById('chat-shell').classList.remove('is-chat-expanded');
            }
            break;
        case 'SwitchChannel':
            console.log('Switched to channel', action.data.channelId);
            break;
    }
}

SIR('addWidget', '#sr-chat-compact', 'chatCompact', {
    jwt: 'your-jwt-token',
    channelId: 'your-channel-id',
    layoutMode: 'compact',
    onAction
});
```

## Examples

> **Info**
>
> Provide **either** `jwt` or `apiKey` together with `channelId`. JWT must include Virtual Stadium scope and claims as described in [JSON Web Token (JWT)](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/jwt.md).

### Property names in HTML data attributes

Properties do not always transfer from the above table directly into integration code. Properties must be transformed differently for each integration method:

#### JavaScript/Programmatic Integration

- Property names remain unchanged in camelCase
- Properties become members of the 4th parameter object in `SIR()` call
- Example: `cardVariant: "compact"`

> **Info**
>
> In javascript integration, the properties go into an object which is passed as the 4th argument of the call ti `SIR()` function. Please see  [Global SIR API](https://apidocs.sportradar.com/resources/widgets/docs/tutorials/SIR.md)

#### HTML/Declarative Integration

- Convert camelCase to lowercase with dashes, e.g. cardVariant becomes card-variant
- Add `data-sr-` prefix
- Example: `cardVariant` → `data-sr-card-variant`
- Example: `filters.sport.hidden` → Complex objects must be passed as JSON strings

> **Info**
>
> In HTML integration, the properties go into the parent HTML object as object properties, prefixed with `data-sr-` as explained above.

> **Only base property support**
>
> This method supports only simple (base) properties and does not support properties that require functions.

> **Info**
>
> In all examples replace `sportradar` in the widgetloader URL path with your clientId.
>
> Example if your clientId is `client1`:
>
> - This URL: `https://widgets.sir.sportradar.com/sportradar/widgetloader`
> - becomes: `https://widgets.sir.sportradar.com/client1/widgetloader`

### Widget setup

**Compact single-row**

Default compact strip with channel header and a single visible message row.

**JavaScript**

### JavaScript (Programmatic)

Initialize the widget programmatically using the JavaScript API. The widget renders in the specified container element.

```javascript
SIR('addWidget', '#sr-chat-compact', 'chatCompact', {
    apiKey: 'your-api-key',
    channelId: 'your-channel-id',
    layoutMode: 'compact',
    variant: 'single-row'
});
```

**HTML (data attributes)**

### HTML (Declarative)

Insert the following HTML code at the target widget location. Complex object properties must be passed as JSON-encoded strings.

```html
<div
    id="sr-chat-compact"
    class="sr-widget"
    data-sr-widget="chatCompact"
    data-sr-api-key="your-api-key"
    data-sr-channel-id="your-channel-id"
    data-sr-layout-mode="compact"
    data-sr-variant="single-row"
></div>
```

**Compact three-row**

Headerless compact stack showing up to three message rows—suited to narrow sidebars.

**JavaScript**

```javascript
SIR('addWidget', '#sr-chat-compact', 'chatCompact', {
    apiKey: 'your-api-key',
    channelId: 'your-channel-id',
    layoutMode: 'compact',
    variant: 'three-row'
});
```

**HTML (data attributes)**

```html
<div
    id="sr-chat-compact"
    class="sr-widget"
    data-sr-widget="chatCompact"
    data-sr-api-key="your-api-key"
    data-sr-channel-id="your-channel-id"
    data-sr-layout-mode="compact"
    data-sr-variant="three-row"
></div>
```

**Full layout**

Full message list and composer. Give the widget host a defined height so the chat can fill the available space.

**JavaScript**

```javascript
SIR('addWidget', '#sr-chat-compact', 'chatCompact', {
    jwt: 'your-jwt-token',
    channelId: 'your-channel-id',
    layoutMode: 'full'
});
```

**HTML (data attributes)**

```html
<div
    id="sr-chat-compact"
    class="sr-widget"
    data-sr-widget="chatCompact"
    data-sr-jwt="your-jwt-token"
    data-sr-channel-id="your-channel-id"
    data-sr-layout-mode="full"
></div>
```

## Tips

- Rotate and refresh JWTs on your backend; pass a new token to the widget when the user session changes.
- Read-only `apiKey` integrations cannot enable composer posting until you switch to JWT for that user.
- Chat Compact does **not** require an adapter; authentication is independent of bet-share or odds adapter setup.
- For full layout or in-session expanded compact chat, ensure the widget container has a defined height so the chat can fill the available space.