> 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/tipping.md). # Tipping KickBot API and MCP reference for Tipping. Tip settings, payment page, tip widget, moderation, queue, and earnings. Tip settings, payment page, tip widget, moderation, queue, and earnings. MCP area name: `tipping`. | Tool | REST | Access | | ------------------------------------------------------------------- | ------------------------------------------ | ------ | | [`get_tipping_status`](#get-tipping-status) | `GET /tipping/status` | Read | | [`get_tip_queue`](#get-tip-queue) | `GET /tipping/queue` | Read | | [`get_tip_queue_settings`](#get-tip-queue-settings) | `GET /tipping/queue/settings` | Read | | [`update_tip_queue_settings`](#update-tip-queue-settings) | `PATCH /tipping/queue/settings` | Write | | [`resume_tip_queue`](#resume-tip-queue) | `POST /tipping/queue/resume` | Write | | [`pause_tip_queue`](#pause-tip-queue) | `POST /tipping/queue/pause` | Write | | [`clear_tip_queue`](#clear-tip-queue) | `POST /tipping/queue/clear` | Write | | [`approve_tip`](#approve-tip) | `POST /tipping/queue/{id}/approve` | Write | | [`reject_tip`](#reject-tip) | `POST /tipping/queue/{id}/reject` | Write | | [`replay_tip`](#replay-tip) | `POST /tipping/transactions/{id}/replay` | Write | | [`get_tip_moderation_settings`](#get-tip-moderation-settings) | `GET /tipping/moderation` | Read | | [`update_tip_moderation_settings`](#update-tip-moderation-settings) | `PATCH /tipping/moderation` | Write | | [`list_blocked_tip_messages`](#list-blocked-tip-messages) | `GET /tipping/moderation/blocked-messages` | Read | | [`get_tip_widget_settings`](#get-tip-widget-settings) | `GET /tipping/widget` | Read | | [`update_tip_widget_settings`](#update-tip-widget-settings) | `PATCH /tipping/widget` | Write | | [`get_tip_page_settings`](#get-tip-page-settings) | `GET /tipping/payment-page` | Read | | [`update_tip_page_settings`](#update-tip-page-settings) | `PATCH /tipping/payment-page` | Write | | [`create_tip_banner_upload_url`](#create-tip-banner-upload-url) | `POST /tipping/payment-page/banner-upload` | Write | | [`list_tip_transactions`](#list-tip-transactions) | `GET /tipping/transactions` | Read | | [`get_tip_earnings_summary`](#get-tip-earnings-summary) | `GET /tipping/earnings` | Read | ## get\_tipping\_status **Get the tipping status.** Start here for tipping. Shows if the Stripe payout account is connected and can receive tips, if tipping is on, and the tip page URL. Connecting Stripe, payouts, and refunds are only in the KickBot dashboard (Tipping > Settings and Earnings), not in the API. `GET /api/v1/tipping/status` No input fields. ## get\_tip\_queue **Get the tip queue.** List the tips waiting to play on stream (newest first), with the queue state (playing or paused, automatic or manual). Each item: id (use it with approve\_tip / reject\_tip), amount\_cents (US cents), tipper\_name, message, approval\_status (pending = waits for approval, approved = will play), is\_replay, is\_test, gif\_url, tts\_audio\_url, tts\_voice {id, label}, created\_at. `recent_tips` are the last 8 tips that played (the dashboard "Recent tips"); play one again with replay\_tip and its id. `GET /api/v1/tipping/queue` | 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). | ## get\_tip\_queue\_settings **Get the tip queue settings.** Get the tip queue settings: tipping on or off, automatic or manual approval, the delay between tips, and if the queue is playing or paused. `GET /api/v1/tipping/queue/settings` No input fields. ## update\_tip\_queue\_settings **Update the tip queue settings.** Change tipping on/off, the queue mode (automatic or manual approval), or the delay between tips. Only the fields you send change. To play or pause the queue use resume\_tip\_queue / pause\_tip\_queue. `PATCH /api/v1/tipping/queue/settings` Needs a read and write key or connection. | Field | Type | Required | Description | | ----------------- | --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- | | `tipping_enabled` | boolean | No | Viewers can send tips on the tip page. Same switch as tipping\_enabled in update\_tip\_page\_settings. | | `queue_mode` | `"automatic"` or `"manual"` | No | automatic: paid tips play on stream by themselves. manual: each tip waits until you approve it (approve\_tip). | | `queue_delay` | integer | No | Minimum seconds between two tips on stream, 0-100. | ## resume\_tip\_queue **Resume the tip queue.** Start playing tips on stream again after pause\_tip\_queue. Approved tips in the queue start to play. `POST /api/v1/tipping/queue/resume` Needs a read and write key or connection. This has an effect outside your settings (for example on your live stream). No input fields. ## pause\_tip\_queue **Pause the tip queue.** Stop playing tips on stream. New tips still come in and wait in the queue until resume\_tip\_queue. `POST /api/v1/tipping/queue/pause` Needs a read and write key or connection. This has an effect outside your settings (for example on your live stream). No input fields. ## clear\_tip\_queue **Clear the tip queue (reject all).** Reject ALL tips that are not paid yet (every pending and approved tip in the queue) and cancel their Stripe payments, so those viewers are NOT charged and the streamer does not get that money. This cannot be undone. Ask the streamer before you use it. `POST /api/v1/tipping/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. ## approve\_tip **Approve a tip.** Approve a tip in the queue (get\_tip\_queue) so it plays on stream with its message and TTS. The viewer is charged when the tip plays. Use it for pending tips when the queue mode is manual. `POST /api/v1/tipping/queue/{id}/approve` 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 | | ------------------ | ------- | -------- | -------------------------------- | | `id` (in the path) | integer | Yes | The tip id from get\_tip\_queue. | ## reject\_tip **Reject a tip.** Reject a tip in the queue (get\_tip\_queue): it does not play, and its Stripe payment is canceled, so the viewer is NOT charged and the streamer does not get the money. For a replay (is\_replay = true) it only removes the replay. This cannot be undone. `POST /api/v1/tipping/queue/{id}/reject` 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). | Field | Type | Required | Description | | ------------------ | ------- | -------- | -------------------------------- | | `id` (in the path) | integer | Yes | The tip id from get\_tip\_queue. | ## replay\_tip **Replay a tip on stream.** Play an approved tip again on stream, with its message, GIF, and TTS. It does not charge the viewer again or move money. Use the id from list\_tip\_transactions. Only approved tips that already played can be replayed. The replay waits in the tip queue (is\_replay = true); reject\_tip removes it. `POST /api/v1/tipping/transactions/{id}/replay` 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 | | ------------------ | ------- | -------- | ---------------------------------------- | | `id` (in the path) | integer | Yes | The tip id from list\_tip\_transactions. | ## get\_tip\_moderation\_settings **Get the tip moderation settings.** Get the filters that block tips before checkout: profanity, repeated text, links, blocked terms, regex patterns, smart filtering, and AI content filters. A blocked tip is never charged and never plays. `GET /api/v1/tipping/moderation` No input fields. ## update\_tip\_moderation\_settings **Update the tip moderation settings.** Change the tip filters. Only the fields you send change; blocked\_terms and regex\_patterns replace the whole list. Needs the tipping configuration permission. `PATCH /api/v1/tipping/moderation` Needs a read and write key or connection. | Field | Type | Required | Description | | ------------------------- | --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `bad_word_filter` | boolean | No | Block messages with strong profanity (AI check). | | `excessive_repeat_filter` | boolean | No | Block messages with too many repeated characters or words. | | `url_filter` | boolean | No | Block messages that contain links. | | `smart_filter_enabled` | boolean | No | Use AI to also catch attempts to get around blocked\_terms (changed letters, similar sounds). Beta. | | `blocked_terms` | array of string | No | Words or phrases to block in the tipper name and the message. Replaces the whole list. Up to 200 entries, 150 characters each. Matching ignores case. | | `regex_patterns` | array of string | No | JavaScript regular expressions; a tip that matches any of them is blocked. Replaces the whole list. Example: "discord\\.gg/\w+". | | `ai_filters` | object | No | AI content filters. Send only the filters you want to change. | ## list\_blocked\_tip\_messages **List blocked tip messages.** List tips that the moderation filters blocked, newest first: amount\_cents, message, reason, created\_at. `GET /api/v1/tipping/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). | ## get\_tip\_widget\_settings **Get the tip widget settings.** Get the on-stream tip widget settings. The widget URL for OBS is not in the API: it contains a secret key. The streamer copies it from Tipping > Widget in the KickBot dashboard. `GET /api/v1/tipping/widget` No input fields. ## update\_tip\_widget\_settings **Update the tip widget settings.** Change how tips look on stream: text, animation, colors, background, and TTS volume. Only the fields you send change. Open widgets reload the settings at once. `PATCH /api/v1/tipping/widget` Needs a read and write key or connection. | Field | Type | Required | Description | | -------------------- | ---------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------ | | `enabled` | boolean | No | Show the tip message text on the widget while the tip plays. | | `animation` | `"none"` or `"fade"` or `"slide-left"` or `"slide-right"` or `"slide-top"` or `"slide-bottom"` | No | How the tip message appears. Default fade. | | `text_size` | integer | No | Font size in pixels, 24-60. Default 24. | | `text_color` | string | No | Text color as a hex code, for example #FFFFFF. | | `background` | boolean | No | Show a dark background behind the text. Default true. | | `background_opacity` | integer | No | Background opacity in percent, 0-100. Default 100. | | `show_sender_amount` | boolean | No | Show the tipper name and the amount. Default true. | | `tts_volume` | integer | No | Volume of the tip TTS audio in percent, 0-100. Default 70. | ## get\_tip\_page\_settings **Get the tip page settings.** Get the public tip page settings (kickbot.com/tips/): on/off, amounts in US cents, presets, message length, allowed TTS voices, GIFs, test mode, custom URL, and banner. `GET /api/v1/tipping/payment-page` No input fields. ## update\_tip\_page\_settings **Update the tip page settings.** Change the tip page. Only the fields you send change. Amounts are US cents: the minimum is $1-$499, the maximum up to $500, and the suggested amount and presets must be between them. custom\_slug needs Premium. `PATCH /api/v1/tipping/payment-page` Needs a read and write key or connection. | Field | Type | Required | Description | | ------------------------ | ------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tipping_enabled` | boolean | No | Viewers can send tips on the tip page. | | `custom_message` | string | No | Text shown on the tip page, for example "Thanks for the support!". | | `minimum_amount_cents` | integer | No | Smallest tip in US cents, 100-49900 ($1-$499). Example: 500 = $5.00. | | `maximum_amount_cents` | integer | No | Largest tip in US cents, 100-50000 ($1-$500). | | `suggested_amount_cents` | integer | No | Amount filled in by default on the tip page, in US cents. Must be between the minimum and the maximum. | | `payment_presets_cents` | array of integer | No | Up to 5 quick-pick amounts in US cents, each between the minimum and the maximum. Replaces the whole list. | | `max_message_length` | integer | No | Max characters in a tip message, 1-150. Default 150. | | `tts_voice_mode` | `"all"` or `"official"` or `"custom"` | No | Which TTS voices tippers can pick: all voices, official voices only (Premium), or the list in tts\_voice\_ids. | | `tts_voice_ids` | array of integer | No | TTS voice ids tippers can pick when tts\_voice\_mode is custom: any public library voice or your own clone (voice\_id from list\_tts\_library\_voices). Premium voices work only on Premium. Replaces the whole list. | | `gifs_allowed` | boolean | No | Tippers can attach a GIF. | | `read_username` | boolean | No | TTS reads " tipped $5" before the message. | | `test_mode_active` | boolean | No | Test mode: no real payments; use it to see how tips look on stream. Turn it off before going live. | | `custom_slug` | string | No | Premium only. Custom tip page address: kickbot.com/tips/\. 4-50 characters: letters, numbers, - and \_. Saved in lower case. | | `banner_enabled` | boolean | No | Show the uploaded banner image on the tip page. Set true after you upload a banner (create\_tip\_banner\_upload\_url). Set false to remove the banner. | ## create\_tip\_banner\_upload\_url **Get an upload URL for the tip page banner.** Step 1 of 2 to set the tip page banner. Send the image type and size; returns upload\_url, which only accepts that exact type and size. Upload the image with HTTP PUT to upload\_url within 30 minutes: body = the raw image bytes, with the headers in `headers` (Content-Type must be exactly content\_type; the body must be exactly size\_bytes long). Use a wide image (4:1, for example 1200x300). Allowed types: image/png, image/jpeg, image/gif, image/webp. Max size: 10 MiB (10485760 bytes). Step 2: call update\_tip\_page\_settings with banner\_enabled: true. A new upload replaces the old banner. `POST /api/v1/tipping/payment-page/banner-upload` Needs a read and write key or connection. | Field | Type | Required | Description | | -------------- | ------- | -------- | --------------------------------------------------------------------- | | `content_type` | string | Yes | MIME type of the image: image/png, image/jpeg, image/gif, image/webp. | | `size_bytes` | integer | Yes | Image size in bytes, max 10 MiB. | ## list\_tip\_transactions **List tip transactions.** List received tips, newest first (test tips are not included). status is what the earnings page shows: approved, pending, rejected, refunded, disputed, expired, canceled, failed. payment\_collected tells if the money was taken. Amounts are US cents before fees. Read only: refunds are only in the dashboard. Use replay\_tip to play a tip again. `GET /api/v1/tipping/transactions` | 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). | ## get\_tip\_earnings\_summary **Get the tip earnings summary.** The numbers on the earnings page: Stripe balances (pending, available, in transit; in the smallest unit of `currency`, for example cents), tip counts for 7 days, 30 days, and all time, and estimated earnings per day for the last 30 days after fees (8.9% + $0.30 per tip). Read only: payouts are only in the dashboard. `GET /api/v1/tipping/earnings` No input fields. ## 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/tipping.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.