# Overlay widgets API

> KickBot API and MCP reference for the built-in overlays: chat, alerts, pinned message, emote spawner, viewer count, follower count and last sub.

Source: https://kickbot.com/docs/api/reference/overlays

Use these actions to get the browser source URL and change the settings of the built-in overlays.

Each action is a REST endpoint under `https://kickbot.com/api/v1` and an MCP tool with the same name. The MCP area name is `overlays`. Use it to load only this area: `https://kickbot.com/api/v1/mcp?areas=overlays`.

A team member needs the **Configure widgets** permission in Manage Team. Owners and admins have every permission. Write actions also need a read and write key or connection. See [Permissions and security](https://kickbot.com/docs/api/start/permissions-and-security).

How the feature works in the dashboard: [Widget library](https://kickbot.com/docs/widgets/widget-library).

> **Note:** The dashboard lists these built-in overlays under **Legacy widgets** on the Saved widgets page. New setups usually use widgets from the widget library. You manage those with the [Custom widgets](https://kickbot.com/docs/api/reference/widgets) actions.

## Actions

| Tool | REST | Access |
|---|---|---|
| [`list_overlays`](#list_overlays) | `GET /overlays` | Read |
| [`get_chat_overlay_settings`](#get_chat_overlay_settings) | `GET /overlays/chat` | Read |
| [`update_chat_overlay_settings`](#update_chat_overlay_settings) | `PATCH /overlays/chat` | Write |
| [`get_alert_overlay_settings`](#get_alert_overlay_settings) | `GET /overlays/alerts` | Read |
| [`update_alert_overlay_settings`](#update_alert_overlay_settings) | `PATCH /overlays/alerts/{alert_type}` | Write |
| [`create_alert_media_upload`](#create_alert_media_upload) | `POST /overlays/alerts/{alert_type}/media-uploads` | Write |
| [`test_overlay_alert`](#test_overlay_alert) | `POST /overlays/alerts/{alert_type}/test` | Write |
| [`get_pinned_message_overlay_settings`](#get_pinned_message_overlay_settings) | `GET /overlays/pinned-message` | Read |
| [`update_pinned_message_overlay_settings`](#update_pinned_message_overlay_settings) | `PATCH /overlays/pinned-message` | Write |
| [`get_emote_spawner_settings`](#get_emote_spawner_settings) | `GET /overlays/emote-spawner` | Read |
| [`update_emote_spawner_settings`](#update_emote_spawner_settings) | `PATCH /overlays/emote-spawner` | Write |
| [`get_viewer_count_overlay_settings`](#get_viewer_count_overlay_settings) | `GET /overlays/viewer-count` | Read |
| [`update_viewer_count_overlay_settings`](#update_viewer_count_overlay_settings) | `PATCH /overlays/viewer-count` | Write |
| [`get_follower_count_overlay_settings`](#get_follower_count_overlay_settings) | `GET /overlays/follower-count` | Read |
| [`update_follower_count_overlay_settings`](#update_follower_count_overlay_settings) | `PATCH /overlays/follower-count` | Write |
| [`get_last_subscriber_overlay_settings`](#get_last_subscriber_overlay_settings) | `GET /overlays/last-subscriber` | Read |
| [`update_last_subscriber_overlay_settings`](#update_last_subscriber_overlay_settings) | `PATCH /overlays/last-subscriber` | Write |

## list_overlays

**List the built-in overlays.** List the built-in overlays with their overlay_url and the tool that reads their settings. They work without setup (dashboard defaults). Add overlay_url as a Browser Source in OBS (or another streaming app). Settings changes show after the browser source reloads. The TTS widget URL is in get_tts_settings and the AI image widget URL in get_imagine_settings. The tip widget URL is secret and is only shown in the dashboard. For custom designs, see the widget library (list_library_widgets).

```http
GET /api/v1/overlays
```

No input fields.

## get_chat_overlay_settings

**Get the chat overlay settings.** The chat overlay shows Kick chat messages on stream. Returns the settings (dashboard defaults when never saved; configured tells which) and overlay_url. Add overlay_url as a Browser Source in OBS (or another streaming app). Settings changes show after the browser source reloads.

```http
GET /api/v1/overlays/chat
```

No input fields.

## update_chat_overlay_settings

**Update the chat overlay settings.** Change the chat overlay settings. Only the fields you send change; the others keep their current value (or the dashboard default).

```http
PATCH /api/v1/overlays/chat
```

Needs a read and write key or connection.

| Field | Type | Required | Description |
|---|---|---|---|
| `preset` | `"default"` or `"monochromatic"` or `"neon city"` or `"rectangles"` | No | Look of the chat: default, monochromatic, "neon city", or rectangles. |
| `font_size` | integer | No | Font size in pixels (10-40). Default 16. |
| `spacing` | integer | No | Space between messages in pixels (0-20). Default 1. |
| `boldness` | integer | No | Font weight. The dashboard offers 401 (light) to 700 (bold). Default 600. |
| `text_color` | string | No | Message text color. Hex color, for example "ffffff". Stored without "#". |
| `font` | `"open sans"` or `"orbitron"` or `"VT323"` or `"Silkscreen"` or `"Amatic SC"` or `"Codystar"` or `"Rampart One"` or `"Delicious Handrawn"` or `"Eater"` or `"creepster"` | No | Font: "open sans" (default), "orbitron" (futuristic), "VT323" (computer text), "Silkscreen" (pixel), "Amatic SC" (skinny), "Codystar" (dots), "Rampart One" (3D), "Delicious Handrawn" (hand drawn), "Eater", or "creepster" (creepy). |
| `slide_direction` | `"left-slide"` or `"right-slide"` or `"bottom-slide"` or `"disabled-slide"` | No | How new messages come in: left-slide (default), right-slide, bottom-slide, or disabled-slide (no animation). |
| `icons` | boolean | No | Show badges (moderator, VIP, subscriber). Default true. |
| `background_color` | string | No | Message background color. Hex color, for example "ffffff". Stored without "#". |
| `background_opacity` | integer | No | Message background opacity in percent. Default 30. |
| `background_type` | `"box"` or `"rounded-box"` or `"highlighter"` | No | Message background shape: box, rounded-box (default), or highlighter. |
| `pinned_message` | boolean | No | Show the pinned chat message at the top. Default true. |
| `pinned_opacity` | integer | No | Pinned message background opacity in percent. Default 50. |

## get_alert_overlay_settings

**Get the alerts overlay settings.** The alerts overlay plays an animation with text, an image or video, and a sound for new subscriptions, gifted subscriptions, and follows. Returns overlay_url (all alert types in one browser source) and the settings of each alert type, each with its own overlay_url if the streamer wants one source per type. Add overlay_url as a Browser Source in OBS (or another streaming app). Settings changes show after the browser source reloads.

```http
GET /api/v1/overlays/alerts
```

> **Legacy alerts:** This action controls the legacy alerts overlay. The dashboard says legacy alerts no longer work, because Kick's new API stopped this alert system. For follow, sub and gifted sub alerts on stream, install an alert widget from the widget library with the [Custom widgets](https://kickbot.com/docs/api/reference/widgets) actions.

No input fields.

## update_alert_overlay_settings

**Update an alert type.** Change the settings of one alert type on the alerts overlay. Only the fields you send change. Requires a verified account.

```http
PATCH /api/v1/overlays/alerts/{alert_type}
```

Needs a read and write key or connection.

> **Legacy alerts:** This action controls the legacy alerts overlay. The dashboard says legacy alerts no longer work, because Kick's new API stopped this alert system. For follow, sub and gifted sub alerts on stream, install an alert widget from the widget library with the [Custom widgets](https://kickbot.com/docs/api/reference/widgets) actions.

| Field | Type | Required | Description |
|---|---|---|---|
| `alert_type` (in the path) | `"sub"` or `"subgift"` or `"follow"` | Yes | sub (new or renewed subscription), subgift (gifted subscriptions), or follow. |
| `enabled` | boolean | No | Play this alert. Default true. |
| `text` | string | No | Alert text, up to 65 characters (the same as the dashboard). Placeholders: {{username}}, {{months}} (sub), {{sub_count}} (subgift). |
| `media_url` | string or null | No | Image or video shown with the alert. https URL, or null for none. Upload your own file with create_alert_media_upload. |
| `audio_url` | string or null | No | Sound played with the alert. https URL, or null for none. Upload your own file with create_alert_media_upload. |
| `text_size` | integer | No | Text size in pixels (10-100). Default 32. |
| `text_color` | string | No | Text color. Hex color with 3, 6, or 8 digits (8 = with transparency), for example "ffffff". Stored without "#". |
| `username_color` | string | No | Color of the username in the text. Hex color with 3, 6, or 8 digits (8 = with transparency), for example "ffffff". Stored without "#". |
| `duration` | integer | No | Seconds the alert stays on screen (3-20). Default 6. |

## create_alert_media_upload

**Upload an alert image, video, or sound.** Step 1 of 2 to use your own file in an alert. Send the file type and size; returns an upload_url that only accepts that exact file type and size. Step 2: send the file with HTTP PUT to upload_url within 30 minutes (body = the raw file, with the headers in `headers`: Content-Type must be exactly content_type, and the body must be exactly size_bytes long). Then set file_url as media_url (category image) or audio_url (category audio) with update_alert_overlay_settings. A new upload replaces the earlier file of the same alert type and category. Category image: Allowed types: image/png, image/jpeg, image/gif, image/webp, video/mp4, video/webm, video/quicktime. Max size: 50 MB (50000000 bytes). Category audio: Allowed types: audio/mpeg, audio/mp3, audio/wav, audio/wave, audio/x-wav, audio/vnd.wave, audio/ogg, audio/opus, audio/webm, audio/mp4, audio/x-m4a, audio/m4a, audio/aac, audio/x-aac, audio/flac, audio/x-flac. Max size: 5 MB (5000000 bytes).

```http
POST /api/v1/overlays/alerts/{alert_type}/media-uploads
```

Needs a read and write key or connection. This can delete or replace data, and you may not be able to undo it.

> **Legacy alerts:** This action controls the legacy alerts overlay. The dashboard says legacy alerts no longer work, because Kick's new API stopped this alert system. For follow, sub and gifted sub alerts on stream, install an alert widget from the widget library with the [Custom widgets](https://kickbot.com/docs/api/reference/widgets) actions.

| Field | Type | Required | Description |
|---|---|---|---|
| `alert_type` (in the path) | `"sub"` or `"subgift"` or `"follow"` | Yes | sub (new or renewed subscription), subgift (gifted subscriptions), or follow. |
| `category` | `"image"` or `"audio"` | Yes | image (image or video shown on stream) or audio (sound). |
| `content_type` | string | Yes | MIME type of the file, for example image/png, video/mp4, or audio/mpeg. Category image: image/png, image/jpeg, image/gif, image/webp, video/mp4, video/webm, video/quicktime. Category audio: audio/mpeg, audio/mp3, audio/wav, audio/wave, audio/x-wav, audio/vnd.wave, audio/ogg, audio/opus, audio/webm, audio/mp4, audio/x-m4a, audio/m4a, audio/aac, audio/x-aac, audio/flac, audio/x-flac. |
| `size_bytes` | integer | Yes | File size in bytes. Max 50 MB for category image, 5 MB for category audio. |

## test_overlay_alert

**Play a test alert on stream.** Plays a test alert (from the user "henryk89") on the LIVE alerts overlay, so viewers see it if the overlay is in the stream. Use it to check the alert settings. Nothing is posted in chat.

```http
POST /api/v1/overlays/alerts/{alert_type}/test
```

Needs a read and write key or connection. This has an effect outside your settings (for example on your live stream). Rate limit: 20 per minute.

> **Legacy alerts:** This action controls the legacy alerts overlay. The dashboard says legacy alerts no longer work, because Kick's new API stopped this alert system. For follow, sub and gifted sub alerts on stream, install an alert widget from the widget library with the [Custom widgets](https://kickbot.com/docs/api/reference/widgets) actions.

| Field | Type | Required | Description |
|---|---|---|---|
| `alert_type` (in the path) | `"sub"` or `"subgift"` or `"follow"` | Yes | sub (new or renewed subscription), subgift (gifted subscriptions), or follow. |

## get_pinned_message_overlay_settings

**Get the pinned message overlay settings.** The pinned message overlay shows the message pinned in Kick chat. Returns the settings (dashboard defaults when never saved; configured tells which) and overlay_url. Add overlay_url as a Browser Source in OBS (or another streaming app). Settings changes show after the browser source reloads.

```http
GET /api/v1/overlays/pinned-message
```

No input fields.

## update_pinned_message_overlay_settings

**Update the pinned message overlay settings.** Change the pinned message overlay settings. Only the fields you send change; the others keep their current value (or the dashboard default).

```http
PATCH /api/v1/overlays/pinned-message
```

Needs a read and write key or connection.

| Field | Type | Required | Description |
|---|---|---|---|
| `font_size` | integer | No | Font size in pixels (10-50). Default 30. |
| `boldness` | integer | No | Font weight. The dashboard offers 401 (light) to 700 (bold). Default 600. |
| `text_color` | string | No | Text color. Hex color, for example "ffffff". Stored without "#". |
| `font` | `"open sans"` or `"orbitron"` or `"VT323"` or `"Silkscreen"` or `"Amatic SC"` or `"Codystar"` or `"Rampart One"` or `"Delicious Handrawn"` or `"Eater"` or `"creepster"` | No | Font: "open sans" (default), "orbitron" (futuristic), "VT323" (computer text), "Silkscreen" (pixel), "Amatic SC" (skinny), "Codystar" (dots), "Rampart One" (3D), "Delicious Handrawn" (hand drawn), "Eater", or "creepster" (creepy). |
| `slide_direction` | `"left-slide"` or `"right-slide"` or `"bottom-slide"` or `"top-slide"` or `"disabled-slide"` | No | How the message comes in: left-slide, right-slide, bottom-slide, top-slide (default), or disabled-slide. |
| `background_color` | string | No | Background color. Hex color, for example "ffffff". Stored without "#". |
| `background_opacity` | integer | No | Background opacity in percent. Default 30. |
| `icons` | boolean | No | Show badges. Default true. |

## get_emote_spawner_settings

**Get the emote spawner settings.** The emote spawner shows emotes from chat messages at random places on stream. Returns the settings (dashboard defaults when never saved; configured tells which) and overlay_url. Add overlay_url as a Browser Source in OBS (or another streaming app). Settings changes show after the browser source reloads.

```http
GET /api/v1/overlays/emote-spawner
```

No input fields.

## update_emote_spawner_settings

**Update the emote spawner settings.** Change the emote spawner settings. Only the fields you send change; the others keep their current value (or the dashboard default).

```http
PATCH /api/v1/overlays/emote-spawner
```

Needs a read and write key or connection.

| Field | Type | Required | Description |
|---|---|---|---|
| `show_chance` | integer | No | Chance in percent that an emote in a chat message is shown. Default 10. |
| `emote_size` | integer | No | Emote size in pixels (4-96). Default 32. |
| `duration` | integer | No | Seconds an emote stays on screen (1-30). Default 4. |
| `fade` | boolean | No | Fade emotes out. Default true. |

## get_viewer_count_overlay_settings

**Get the viewer count overlay settings.** The viewer count overlay shows the live viewer count. Returns the settings (dashboard defaults when never saved; configured tells which) and overlay_url. Add overlay_url as a Browser Source in OBS (or another streaming app). Settings changes show after the browser source reloads.

```http
GET /api/v1/overlays/viewer-count
```

No input fields.

## update_viewer_count_overlay_settings

**Update the viewer count overlay settings.** Change the viewer count overlay settings. Only the fields you send change; the others keep their current value (or the dashboard default).

```http
PATCH /api/v1/overlays/viewer-count
```

Needs a read and write key or connection.

| Field | Type | Required | Description |
|---|---|---|---|
| `text` | string | No | The text. {{viewer_count}} is replaced with the live value. |
| `font_size` | integer | No | Font size in pixels (10-40). Default 32. |
| `boldness` | integer | No | Font weight. The dashboard offers 401 (light) to 700 (bold). Default 600. |
| `text_color` | string | No | Text color. Hex color, for example "ffffff". Stored without "#". |
| `font` | `"open sans"` or `"orbitron"` or `"VT323"` or `"Silkscreen"` or `"Amatic SC"` or `"Codystar"` or `"Rampart One"` or `"Delicious Handrawn"` or `"Eater"` or `"creepster"` | No | Font: "open sans" (default), "orbitron" (futuristic), "VT323" (computer text), "Silkscreen" (pixel), "Amatic SC" (skinny), "Codystar" (dots), "Rampart One" (3D), "Delicious Handrawn" (hand drawn), "Eater", or "creepster" (creepy). |
| `animate` | boolean | No | Count up and down smoothly. Default true. |

## get_follower_count_overlay_settings

**Get the follower count overlay settings.** The follower count overlay shows the follower count. Returns the settings (dashboard defaults when never saved; configured tells which) and overlay_url. Add overlay_url as a Browser Source in OBS (or another streaming app). Settings changes show after the browser source reloads.

```http
GET /api/v1/overlays/follower-count
```

No input fields.

## update_follower_count_overlay_settings

**Update the follower count overlay settings.** Change the follower count overlay settings. Only the fields you send change; the others keep their current value (or the dashboard default).

```http
PATCH /api/v1/overlays/follower-count
```

Needs a read and write key or connection.

| Field | Type | Required | Description |
|---|---|---|---|
| `text` | string | No | The text. {{follower_count}} is replaced with the live value. |
| `font_size` | integer | No | Font size in pixels (10-40). Default 32. |
| `boldness` | integer | No | Font weight. The dashboard offers 401 (light) to 700 (bold). Default 600. |
| `text_color` | string | No | Text color. Hex color, for example "ffffff". Stored without "#". |
| `font` | `"open sans"` or `"orbitron"` or `"VT323"` or `"Silkscreen"` or `"Amatic SC"` or `"Codystar"` or `"Rampart One"` or `"Delicious Handrawn"` or `"Eater"` or `"creepster"` | No | Font: "open sans" (default), "orbitron" (futuristic), "VT323" (computer text), "Silkscreen" (pixel), "Amatic SC" (skinny), "Codystar" (dots), "Rampart One" (3D), "Delicious Handrawn" (hand drawn), "Eater", or "creepster" (creepy). |
| `animate` | boolean | No | Count up and down smoothly. Default true. |

## get_last_subscriber_overlay_settings

**Get the last subscriber overlay settings.** The last subscriber overlay shows the name of the newest subscriber. Returns the settings (dashboard defaults when never saved; configured tells which) and overlay_url. Add overlay_url as a Browser Source in OBS (or another streaming app). Settings changes show after the browser source reloads.

```http
GET /api/v1/overlays/last-subscriber
```

No input fields.

## update_last_subscriber_overlay_settings

**Update the last subscriber overlay settings.** Change the last subscriber overlay settings. Only the fields you send change; the others keep their current value (or the dashboard default).

```http
PATCH /api/v1/overlays/last-subscriber
```

Needs a read and write key or connection.

| Field | Type | Required | Description |
|---|---|---|---|
| `text` | string | No | The text. {{sub_name}} is replaced with the live value. |
| `font_size` | integer | No | Font size in pixels (10-100). Default 36. |
| `boldness` | integer | No | Font weight. The dashboard offers 401 (light) to 700 (bold). Default 600. |
| `text_color` | string | No | Text color. Hex color, for example "ffffff". Stored without "#". |
| `font` | `"open sans"` or `"orbitron"` or `"VT323"` or `"Silkscreen"` or `"Amatic SC"` or `"Codystar"` or `"Rampart One"` or `"Delicious Handrawn"` or `"Eater"` or `"creepster"` | No | Font: "open sans" (default), "orbitron" (futuristic), "VT323" (computer text), "Silkscreen" (pixel), "Amatic SC" (skinny), "Codystar" (dots), "Rampart One" (3D), "Delicious Handrawn" (hand drawn), "Eater", or "creepster" (creepy). |