> 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/tts.md). # Text-to-speech KickBot API and MCP reference for Text-to-speech. TTS settings, voices, voice commands, moderation, queue, and voice cloning. TTS settings, voices, voice commands, moderation, queue, and voice cloning. MCP area name: `tts`. | Tool | REST | Access | | ------------------------------------------------------------------- | --------------------------------------------- | ------ | | [`get_tts_settings`](#get-tts-settings) | `GET /tts/settings` | Read | | [`update_tts_settings`](#update-tts-settings) | `PATCH /tts/settings` | Write | | [`get_tts_preview_settings`](#get-tts-preview-settings) | `GET /tts/preview` | Read | | [`update_tts_preview_settings`](#update-tts-preview-settings) | `PATCH /tts/preview` | Write | | [`get_tts_moderation_settings`](#get-tts-moderation-settings) | `GET /tts/moderation` | Read | | [`update_tts_moderation_settings`](#update-tts-moderation-settings) | `PATCH /tts/moderation` | Write | | [`list_tts_blocked_messages`](#list-tts-blocked-messages) | `GET /tts/moderation/blocked-messages` | Read | | [`list_tts_voices`](#list-tts-voices) | `GET /tts/voices` | Read | | [`get_tts_voice`](#get-tts-voice) | `GET /tts/voices/{voice_id}` | Read | | [`add_tts_voice`](#add-tts-voice) | `POST /tts/voices` | Write | | [`update_tts_voice`](#update-tts-voice) | `PATCH /tts/voices/{voice_id}` | Write | | [`update_tts_voice_permissions`](#update-tts-voice-permissions) | `PATCH /tts/voices` | Write | | [`remove_tts_voice`](#remove-tts-voice) | `DELETE /tts/voices/{voice_id}` | Write | | [`enable_all_tts_voices`](#enable-all-tts-voices) | `POST /tts/voices/enable-all` | Write | | [`disable_all_tts_voices`](#disable-all-tts-voices) | `POST /tts/voices/disable-all` | Write | | [`list_tts_library_voices`](#list-tts-library-voices) | `GET /tts/library` | Read | | [`list_tts_library_filters`](#list-tts-library-filters) | `GET /tts/library/filters` | Read | | [`get_tts_stats`](#get-tts-stats) | `GET /tts/stats` | Read | | [`list_recent_tts_messages`](#list-recent-tts-messages) | `GET /tts/messages` | Read | | [`skip_tts_message`](#skip-tts-message) | `POST /tts/queue/skip` | Write | | [`clear_tts_queue`](#clear-tts-queue) | `POST /tts/queue/clear` | Write | | [`list_custom_tts_voices`](#list-custom-tts-voices) | `GET /tts/custom-voices` | Read | | [`create_custom_tts_voice`](#create-custom-tts-voice) | `POST /tts/custom-voices` | Write | | [`train_custom_tts_voice`](#train-custom-tts-voice) | `POST /tts/custom-voices/{voice_id}/train` | Write | | [`finalize_custom_tts_voice`](#finalize-custom-tts-voice) | `POST /tts/custom-voices/{voice_id}/finalize` | Write | | [`delete_custom_tts_voice`](#delete-custom-tts-voice) | `DELETE /tts/custom-voices/{voice_id}` | Write | | [`get_auto_read_settings`](#get-auto-read-settings) | `GET /tts/auto-read` | Read | | [`update_auto_read_settings`](#update-auto-read-settings) | `PATCH /tts/auto-read` | Write | | [`list_auto_read_rules`](#list-auto-read-rules) | `GET /tts/auto-read/rules` | Read | | [`create_auto_read_rule`](#create-auto-read-rule) | `POST /tts/auto-read/rules` | Write | | [`update_auto_read_rule`](#update-auto-read-rule) | `PATCH /tts/auto-read/rules/{id}` | Write | | [`delete_auto_read_rule`](#delete-auto-read-rule) | `DELETE /tts/auto-read/rules/{id}` | Write | | [`reorder_auto_read_rules`](#reorder-auto-read-rules) | `PUT /tts/auto-read/rules/order` | Write | ## get\_tts\_settings **Get TTS settings.** Get the channel TTS settings: on/off, cooldowns, volume, max length, delay, read sender, public voice list, and on-screen preview. Also the TTS widget URL (add it as a browser source in OBS), when the widget was last open, and the public voice list URL. Null means the value was never set. Auto read has its own tools (get\_auto\_read\_settings). `GET /api/v1/tts/settings` No input fields. ## update\_tts\_settings **Update TTS settings.** Change some TTS settings. Only the fields you send change. Requires a verified account. The TTS widget gets the new on/off, volume, and delay at once. `PATCH /api/v1/tts/settings` Needs a read and write key or connection. | Field | Type | Required | Description | | ------------------------ | ------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tts_enabled` | boolean | No | Master switch. When false, TTS commands and Auto read do nothing. | | `auto_tts` | boolean | No | Deprecated: use `enabled` in update\_auto\_read\_settings. Auto read on or off (the same setting). | | `auto_tts_voice` | `"male"` or `"female"` or `"male_us"` or `"female_us"` | No | Deprecated: use `voice` in update\_auto\_read\_settings, which takes any voice id. Setting this old field also sets "read everyone" on and replaces the Auto read voice for everyone. | | `global_tts_cooldown` | integer | No | Seconds between any two TTS commands in the channel, 0-120. | | `user_tts_cooldown` | integer | No | Seconds a viewer must wait before using another TTS command, 0-120. | | `global_tts_volume` | number | No | Volume of all TTS voices, 0 (mute) to 1 (full). | | `global_tts_max_chars` | integer | No | Longest TTS message, 0 to 300 characters. Longer messages are not read (they are not cut off). | | `tts_delay` | integer | No | Seconds of silence between TTS messages, 0-30. | | `tts_read_sender` | boolean | No | Read the sender name before the message. | | `tts_voice_list_enabled` | boolean | No | Public voice list page where viewers see the enabled voices, recent messages, and a leaderboard. | | `on_screen_preview` | boolean | No | Show the message text on the TTS widget while it plays. Change its look with update\_tts\_preview\_settings. | ## get\_tts\_preview\_settings **Get the TTS on-screen preview look.** Get how the on-screen TTS preview looks (position, animation, text, background). Turn the preview on or off with on\_screen\_preview in update\_tts\_settings. `GET /api/v1/tts/preview` No input fields. ## update\_tts\_preview\_settings **Update the TTS on-screen preview look.** Change how the on-screen TTS preview looks. Only the fields you send change. To show or hide the preview, use on\_screen\_preview in update\_tts\_settings. `PATCH /api/v1/tts/preview` Needs a read and write key or connection. | Field | Type | Required | Description | | -------------------- | ---------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------- | | `position` | `"center"` or `"top"` or `"bottom"` | No | Where the text shows: center, top, or bottom. Default center. | | `animation` | `"none"` or `"fade"` or `"slide-left"` or `"slide-right"` or `"slide-top"` or `"slide-bottom"` | No | How the text appears: none, fade, slide-left, slide-right, slide-top, or slide-bottom. Default fade. | | `text_size` | integer | No | Text size in pixels, 8 to 48. Default 24. | | `text_color` | string | No | Text color as a 6-digit hex, for example FFFFFF (a leading # is removed). Default white. | | `background` | boolean | No | Show a dark box behind the text. Default true. | | `background_opacity` | integer | No | Background opacity in percent, 0 to 100. Default 100. | | `show_sender` | boolean | No | Show who sent the message. Default true. | | `show_voice` | boolean | No | Show the voice name. Default true. | ## get\_tts\_moderation\_settings **Get TTS moderation filters.** Get the filters that block TTS messages before they play: bad words, repeats, links, custom words and regex, banned usernames, and AI filters. `GET /api/v1/tts/moderation` No input fields. ## update\_tts\_moderation\_settings **Update TTS moderation filters.** Change some TTS moderation filters. Only the fields you send change. The list fields replace the whole list: read it with get\_tts\_moderation\_settings first, then send the full new list (one entry per line). `PATCH /api/v1/tts/moderation` Needs a read and write key or connection. | Field | Type | Required | Description | | -------------------------- | ------- | -------- | ------------------------------------------------------------------------------- | | `bad_word_filter` | boolean | No | Block messages with common bad words. | | `excessive_repeat_filter` | boolean | No | Block messages with lots of repeated characters or words. | | `url_filter` | boolean | No | Block messages that contain links. | | `custom_bad_words` | string | No | Extra words to block. One entry per line. | | `custom_regex` | string | No | Regular expressions; a message that matches one is blocked. One entry per line. | | `banned_usernames` | string | No | Kick usernames that can never use TTS. One entry per line. | | `ai_filter_sexual` | boolean | No | AI filter: sexual content. | | `ai_filter_hate` | boolean | No | AI filter: hate speech. | | `ai_filter_violence` | boolean | No | AI filter: violence. | | `ai_filter_harassment` | boolean | No | AI filter: harassment. | | `ai_filter_illicit` | boolean | No | AI filter: illicit activity. | | `ai_filter_self_harm` | boolean | No | AI filter: self-harm. | | `ai_filter_gibberish` | boolean | No | AI filter: gibberish or spam. | | `ai_filter_offensive_name` | boolean | No | AI filter: offensive sender names. | ## list\_tts\_blocked\_messages **List blocked TTS messages.** List TTS messages the moderation filters blocked, newest first, with the reason. `GET /api/v1/tts/moderation/blocked-messages` | Field | Type | Required | Description | | ---------------- | ------- | -------- | ---------------------------------------- | | `limit` (query) | integer | No | Max items to return (1-100, default 50). | | `offset` (query) | integer | No | Number of items to skip (default 0). | ## list\_tts\_voices **List the TTS voices on the channel.** List the voices added to the channel. Each one has a chat command (for example !male hello) and who can use it. Add more with add\_tts\_voice (find them with list\_tts\_library\_voices). `GET /api/v1/tts/voices` | Field | Type | Required | Description | | ----------------- | ------- | -------- | ---------------------------------------------------- | | `enabled` (query) | boolean | No | Only enabled (true) or only disabled (false) voices. | | `limit` (query) | integer | No | Max items to return (1-100, default 50). | | `offset` (query) | integer | No | Number of items to skip (default 0). | ## get\_tts\_voice **Get a TTS voice on the channel.** Get one voice added to the channel, with its chat command and permissions. `GET /api/v1/tts/voices/{voice_id}` | Field | Type | Required | Description | | ------------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------ | | `voice_id` (in the path) | integer | Yes | Voice id (voice\_id from list\_tts\_voices, list\_tts\_library\_voices, or list\_custom\_tts\_voices). | ## add\_tts\_voice **Add a TTS voice to the channel.** Add a voice from the library to the channel. It starts enabled for everyone with its default command. Premium voices need a premium plan. Change the command with update\_tts\_voice. `POST /api/v1/tts/voices` Needs a read and write key or connection. | Field | Type | Required | Description | | ---------- | ------- | -------- | ------------------------------------------------------------------------------------------------------ | | `voice_id` | integer | Yes | Voice id (voice\_id from list\_tts\_voices, list\_tts\_library\_voices, or list\_custom\_tts\_voices). | ## update\_tts\_voice **Update a TTS voice command.** Change the chat command, on/off, or who can use one voice on the channel. Only the fields you send change. Premium voices need a premium plan. `PATCH /api/v1/tts/voices/{voice_id}` Needs a read and write key or connection. | Field | Type | Required | Description | | ------------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------ | | `voice_id` (in the path) | integer | Yes | Voice id (voice\_id from list\_tts\_voices, list\_tts\_library\_voices, or list\_custom\_tts\_voices). | | `command` | string | No | Chat command without "!", letters and digits only, max 15 characters. For example "goku" for !goku. | | `enabled` | boolean | No | Turn the voice command on or off. | | `everyone_only` | boolean | No | Everyone can use the command. | | `sub_only` | boolean | No | Subscribers can use the command. | | `vip_only` | boolean | No | VIPs can use the command. | | `mod_only` | boolean | No | Moderators can use the command. | ## update\_tts\_voice\_permissions **Set who can use several TTS voices.** Bulk edit: set everyone\_only, sub\_only, vip\_only, and mod\_only on several voices at once. Flags you do not send are not changed. `PATCH /api/v1/tts/voices` Needs a read and write key or connection. | Field | Type | Required | Description | | --------------- | ---------------- | -------- | --------------------------------------------------------------------------------------- | | `voice_ids` | array of integer | Yes | Voice ids to change (from list\_tts\_voices). Up to 500 per call; send more in batches. | | `everyone_only` | boolean | No | Everyone can use the command. | | `sub_only` | boolean | No | Subscribers can use the command. | | `vip_only` | boolean | No | VIPs can use the command. | | `mod_only` | boolean | No | Moderators can use the command. | ## remove\_tts\_voice **Remove a TTS voice from the channel.** Remove a premium voice and its command from the channel. The voice stays in the library and can be added again. Free voices and your own clones stay on the channel, the same as on the dashboard: turn them off with update\_tts\_voice, or delete a clone with delete\_custom\_tts\_voice. `DELETE /api/v1/tts/voices/{voice_id}` Needs a read and write key or connection. This cannot be undone. | Field | Type | Required | Description | | ------------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------ | | `voice_id` (in the path) | integer | Yes | Voice id (voice\_id from list\_tts\_voices, list\_tts\_library\_voices, or list\_custom\_tts\_voices). | ## enable\_all\_tts\_voices **Enable all TTS voices.** Turn on every voice on the channel. Requires a verified account. On the free plan only the free voices (male, female, brian, tiktok) are turned on and every other voice is turned off. `POST /api/v1/tts/voices/enable-all` Needs a read and write key or connection. No input fields. ## disable\_all\_tts\_voices **Disable all TTS voices.** Turn off every voice command on the channel. The voices stay added. `POST /api/v1/tts/voices/disable-all` Needs a read and write key or connection. This cannot be undone. No input fields. ## list\_tts\_library\_voices **Browse the TTS voice library.** Search the voice library: public voices and your own cloned voices. Filter by category, language, and gender (get the values with list\_tts\_library\_filters). `added` tells if the voice is on the channel; `can_add` tells if add\_tts\_voice will work (premium voices need a premium plan). `installs` is how many channels added the voice; `messages_sent` is how many TTS messages it read. KickBot tags voices with AI: `categories` (category keys), `gender` (male or female), `voice_language` (ISO 639-1 code of the language spoken in the training audio), and `identity` (who the voice imitates). They are empty or null until a voice is tagged. `tags` is the old user-chosen tag list (deprecated, kept for old clients). `GET /api/v1/tts/library` | Field | Type | Required | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `search` (query) | string | No | Find voices whose name, default command, or identity (who the voice is, and other names for it) contains this text. Only letters, numbers, spaces, and - \_ ' are used; other characters count as spaces. | | `category` (query) | `"streamers"` or `"musicians"` or `"athletes"` or `"politicians"` or `"actors_tv"` or `"cartoons"` or `"anime"` or `"video_games"` or `"tv_movie_characters"` or `"memes"` or `"narrators"` | No | Only voices in this AI category (a key from list\_tts\_library\_filters). | | `language` (query) | string | No | Only voices made in this language: an ISO 639-1 code such as en, es, or tr (see list\_tts\_library\_filters). | | `gender` (query) | `"male"` or `"female"` | No | Only male or only female voices. | | `tag` (query) | string | No | Deprecated: use category. Only voices with this old user-chosen tag, for example: cartoon, content creator, politics, celebrity, movie, video game, TV, anime, fantasy, male, female. | | `sort` (query) | `"popular"` or `"most_installed"` or `"newest"` or `"trending"` | No | popular (most TTS messages, default), most\_installed (on the most channels: the dashboard library "Popular"), newest (the dashboard "Recent"), or trending (the top 50 public voices this week). | | `premium` (query) | boolean | No | Only premium (true) or only free (false) voices. | | `added` (query) | boolean | No | Only voices already on the channel (true) or not yet added (false). | | `limit` (query) | integer | No | Max items to return (1-100, default 50). | | `offset` (query) | integer | No | Number of items to skip (default 0). | ## list\_tts\_library\_filters **List the TTS voice library filters.** List the values for the list\_tts\_library\_voices filters: the categories (key and English label), the languages that have library voices (ISO 639-1 code, English name, and number of voices, most voices first), and the genders. `GET /api/v1/tts/library/filters` No input fields. ## get\_tts\_stats **Get TTS usage stats.** Number of TTS messages in the last 24 hours, 7 days, 30 days, and all time. `GET /api/v1/tts/stats` No input fields. ## list\_recent\_tts\_messages **List recent TTS messages.** List recent TTS messages, newest first. Use an id with skip\_tts\_message to skip a message that has not played yet. `GET /api/v1/tts/messages` | Field | Type | Required | Description | | ---------------- | ------- | -------- | ------------------------------------------- | | `limit` (query) | integer | No | Max messages to return (1-100, default 20). | | `offset` (query) | integer | No | Number of items to skip (default 0). | ## skip\_tts\_message **Skip a TTS message.** Skip one TTS message in the live queue on the TTS widget (stops it if it is playing). Use the id from list\_recent\_tts\_messages. A message that already played is not affected. `POST /api/v1/tts/queue/skip` Needs a read and write key or connection. This has an effect outside your settings (for example on your live stream). | Field | Type | Required | Description | | -------- | ------- | -------- | ------------------------------------------------ | | `tts_id` | integer | Yes | TTS message id from list\_recent\_tts\_messages. | ## clear\_tts\_queue **Clear the TTS queue.** Remove every waiting TTS message from the live queue on the TTS widget. `POST /api/v1/tts/queue/clear` Needs a read and write key or connection. This cannot be undone. This has an effect outside your settings (for example on your live stream). No input fields. ## list\_custom\_tts\_voices **List your cloned TTS voices.** List the custom voices you cloned (premium) and how many clone slots you have. ready = true once the voice has a sample (finalize\_custom\_tts\_voice done). KickBot tags each new clone with AI in the background: `categories`, `gender`, `voice_language`, and `identity` appear a little after finalize\_custom\_tts\_voice (usually within a few minutes). Until then, or when KickBot cannot tell, they are empty or null. `GET /api/v1/tts/custom-voices` No input fields. ## create\_custom\_tts\_voice **Start cloning a TTS voice (step 1 of 4).** Premium only. Clone a voice from audio samples. This is step 1 of 4: 1) create\_custom\_tts\_voice: creates the voice and returns upload URLs (valid for 30 minutes). 2) Upload each audio file with HTTP PUT to its upload\_url: body = the raw file, with the headers in its `headers` (Content-Type must be exactly the content\_type you sent, and the body must be exactly size\_bytes long, or the upload fails). Upload the square icon (200x200 is enough) to icon\_upload.upload\_url the same way. Audio files: 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: 10 MiB (10485760 bytes). Icon: Allowed types: image/png, image/jpeg, image/gif, image/webp. Max size: 5 MiB (5242880 bytes). 3) train\_custom\_tts\_voice with the audio\_url values. Each file must be under 10 MB; use 10 to 90 seconds of clear speech in total, up to 5 files. 4) finalize\_custom\_tts\_voice: makes the sample clip and sets the icon (takes about 10 to 20 seconds). The voice also gets a disabled command on the channel; enable it with update\_tts\_voice after step 4. After step 4 KickBot tags the voice with AI (categories, gender, and the language spoken in the audio) in the background; the tags show in list\_custom\_tts\_voices and list\_tts\_library\_voices a little later. You do not need to send tags. `POST /api/v1/tts/custom-voices` Needs a read and write key or connection. Rate limit: 5 per minute, 30 per day. | Field | Type | Required | Description | | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Yes | Voice name shown in the library, max 20 characters. | | `command` | string | Yes | Default chat command without "!", letters and digits only, max 20 characters. | | `tags` | array of `"cartoon"` or `"content creator"` or `"politics"` or `"celebrity"` or `"movie"` or `"video game"` or `"TV"` or `"anime"` or `"fantasy"` or `"male"` or `"female"` | No | Deprecated and optional: KickBot now sets AI categories after the voice is finished. Old tags you may still send: cartoon, content creator, politics, celebrity, movie, video game, TV, anime, fantasy, male, female. | | `audio_files` | array of object | Yes | The audio samples you will upload (1 to 5), for example \[{ "file\_name": "take1.mp3", "content\_type": "audio/mpeg", "size\_bytes": 812345 }]. | | `icon` | object | Yes | The voice icon you will upload (a square image). Required, the same as on the dashboard: finalize\_custom\_tts\_voice sets it as the voice picture. | | `public` | boolean | No | Ask KickBot to make the voice public for all users (reviewed by staff). Default false. | | `consent` | boolean | Yes | Must be true: you confirm that you have the rights to upload and clone these voice samples. | ## train\_custom\_tts\_voice **Train a cloned TTS voice (step 3 of 4).** Premium only. After you uploaded the audio files from create\_custom\_tts\_voice, send them to the voice clone service. Files of 10 MB or more are skipped. Then call finalize\_custom\_tts\_voice. `POST /api/v1/tts/custom-voices/{voice_id}/train` Needs a read and write key or connection. This has an effect outside your settings (for example on your live stream). Rate limit: 5 per minute, 30 per day. | Field | Type | Required | Description | | ------------------------ | --------------- | -------- | ------------------------------------------------------------------------------------------------------ | | `voice_id` (in the path) | integer | Yes | Voice id (voice\_id from list\_tts\_voices, list\_tts\_library\_voices, or list\_custom\_tts\_voices). | | `audio_urls` | array of string | Yes | The audio\_url values from create\_custom\_tts\_voice for the files you uploaded. | ## finalize\_custom\_tts\_voice **Finish a cloned TTS voice (step 4 of 4).** Premium only. After train\_custom\_tts\_voice, make the sample clip and set the uploaded icon. Takes about 10 to 20 seconds. If it fails, wait a minute and call it again. The voice command starts disabled; enable it with update\_tts\_voice. KickBot then tags the voice with AI in the background, so `categories`, `gender`, `voice_language`, and `identity` are still empty in this answer; read them later with list\_custom\_tts\_voices. `POST /api/v1/tts/custom-voices/{voice_id}/finalize` Needs a read and write key or connection. This has an effect outside your settings (for example on your live stream). Rate limit: 5 per minute, 30 per day. | Field | Type | Required | Description | | ------------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------ | | `voice_id` (in the path) | integer | Yes | Voice id (voice\_id from list\_tts\_voices, list\_tts\_library\_voices, or list\_custom\_tts\_voices). | ## delete\_custom\_tts\_voice **Delete a cloned TTS voice.** Delete a custom voice you cloned and remove its command from your channel. This frees a clone slot. It cannot be undone. `DELETE /api/v1/tts/custom-voices/{voice_id}` Needs a read and write key or connection. This cannot be undone. | Field | Type | Required | Description | | ------------------------ | ------- | -------- | ------------------------------------------------------------------------------------------------------ | | `voice_id` (in the path) | integer | Yes | Voice id (voice\_id from list\_tts\_voices, list\_tts\_library\_voices, or list\_custom\_tts\_voices). | ## get\_auto\_read\_settings **Get Auto read settings.** Auto read: KickBot reads chat messages that are not commands aloud. Returns the settings, the filters, and the voice rules for viewers and Kick badges. KickBot uses the first rule that matches: viewer rules first, then badge rules in their order, then the voice for everyone else. rules\_active is false without Premium: the rules stay saved but are not used. `GET /api/v1/tts/auto-read` No input fields. ## update\_auto\_read\_settings **Update Auto read settings.** Change some Auto read settings or filters. Only the fields you send change. Requires a verified account. `PATCH /api/v1/tts/auto-read` Needs a read and write key or connection. | Field | Type | Required | Description | | ---------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enabled` | boolean | No | Auto read on or off. It also needs TTS on (update\_tts\_settings tts\_enabled) and the TTS widget open in OBS. | | `read_everyone` | boolean | No | false = "Do not read" for everyone without a rule, so only viewers and badges with a rule are read. Premium only. | | `voice_id` | null or integer | No | Voice for everyone without a rule (voice\_id from list\_tts\_voices, list\_tts\_library\_voices, or list\_custom\_tts\_voices). Free plans can use free voices only. null = use legacy\_voice. | | `max_reads_per_minute` | integer | No | Most messages read per minute, 0 to 60. 0 = no limit. | | `read_sender` | boolean | No | Read the sender name before the message. | | `min_chars` | integer | No | Shorter messages are not read, 0 to 300. 0 = no minimum. | | `max_chars` | integer | No | Longer messages are not read (they are not cut off), 1 to 300. | | `skip_links` | boolean | No | true = a message with a link is not read. false = the link is removed and the rest is read. | | `skip_emote_only` | boolean | No | true = a message with only emotes is not read. false = emote names are read. | | `skip_bots` | boolean | No | Skip known bot accounts (BotRix, Kicklet, Lumia Stream, ...) and accounts with the Kick bot badge. | | `ignored_viewers` | array of string | No | Kick usernames that are never read, up to 100. Replaces the whole list. | ## list\_auto\_read\_rules **List Auto read voice rules.** List the Auto read voice rules in the order KickBot checks them. KickBot uses the first rule that matches: viewer rules first, then badge rules in their order, then the voice for everyone else. `GET /api/v1/tts/auto-read/rules` No input fields. ## create\_auto\_read\_rule **Add an Auto read voice rule.** Give one viewer (kind "user") or a Kick badge (kind "badge") its own voice, or "Do not read" (voice\_id null). Premium only. Up to 100 viewer rules; one rule per badge (subscriber can have one per length). A new badge rule goes last, except a subscriber length, which goes above the shorter subscriber rules. `POST /api/v1/tts/auto-read/rules` Needs a read and write key or connection. | Field | Type | Required | Description | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `kind` | `"user"` or `"badge"` | Yes | "user" for one viewer, "badge" for a Kick badge. | | `username` | string | No | For kind "user": the Kick username. | | `badge` | `"broadcaster"` or `"moderator"` or `"vip"` or `"og"` or `"founder"` or `"subscriber"` or `"sub_gifter"` or `"verified"` or `"staff"` or `"sidekick"` | No | For kind "badge": broadcaster, moderator, vip, og, founder, subscriber, sub\_gifter, verified, staff, sidekick. | | `min_months` | null or integer | No | For badge "subscriber" only: subscribed for at least this many months. 0 or null = every subscriber. | | `voice_id` | null or integer | Yes | Voice for this rule (voice\_id from list\_tts\_voices, list\_tts\_library\_voices, or list\_custom\_tts\_voices). Any public voice or your own voices. null = "Do not read". | ## update\_auto\_read\_rule **Update an Auto read voice rule.** Change the voice, the username, the badge, or the subscriber length of a rule. Only the fields you send change. Premium only. `PATCH /api/v1/tts/auto-read/rules/{id}` Needs a read and write key or connection. | Field | Type | Required | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` (in the path) | integer | Yes | The item id. | | `username` | string | No | For kind "user": the Kick username. | | `badge` | `"broadcaster"` or `"moderator"` or `"vip"` or `"og"` or `"founder"` or `"subscriber"` or `"sub_gifter"` or `"verified"` or `"staff"` or `"sidekick"` | No | For kind "badge": broadcaster, moderator, vip, og, founder, subscriber, sub\_gifter, verified, staff, sidekick. | | `min_months` | null or integer | No | For badge "subscriber" only: subscribed for at least this many months. 0 or null = every subscriber. | | `voice_id` | null or integer | No | Voice for this rule (voice\_id from list\_tts\_voices, list\_tts\_library\_voices, or list\_custom\_tts\_voices). Any public voice or your own voices. null = "Do not read". | ## delete\_auto\_read\_rule **Remove an Auto read voice rule.** Remove a voice rule. Works without Premium too, so saved rules can be cleaned up. `DELETE /api/v1/tts/auto-read/rules/{id}` Needs a read and write key or connection. This cannot be undone. | Field | Type | Required | Description | | ------------------ | ------- | -------- | ------------ | | `id` (in the path) | integer | Yes | The item id. | ## reorder\_auto\_read\_rules **Reorder Auto read badge rules.** Set the order of the badge rules: send every badge rule id, first = checked first. Viewer rules always come before badge rules and are not in this list. Premium only. `PUT /api/v1/tts/auto-read/rules/order` Needs a read and write key or connection. | Field | Type | Required | Description | | ----- | ---------------- | -------- | -------------------------------------- | | `ids` | array of integer | Yes | Every badge rule id, in the new order. | ## 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/tts.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.