> For the complete documentation index, see [llms.txt](https://docs.kickbot.com/dashboard/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kickbot.com/dashboard/api/reference/overlays.md). # Overlay widgets KickBot API and MCP reference for Overlay widgets. Built-in stream overlays: chat, alerts, pinned message, emote spawner, viewer and follower counts, last subscriber. Built-in stream overlays: chat, alerts, pinned message, emote spawner, viewer and follower counts, last subscriber. MCP area name: `overlays`. | 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). `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. `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). `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. `GET /api/v1/overlays/alerts` 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. `PATCH /api/v1/overlays/alerts/{alert_type}` Needs a read and write key or connection. | 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). `POST /api/v1/overlays/alerts/{alert_type}/media-uploads` Needs a read and write key or connection. | 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. `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. | 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. `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). `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. `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). `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. `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). `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. `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). `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. `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). `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). | ## Need help? Email or ask in the `#support` channel on [Discord](https://discord.gg/MAg3gBbc89). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.kickbot.com/dashboard/api/reference/overlays.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.