Tipping API

Use these actions to manage tipping on your channel: the tip page, tip alerts, filters, the queue and your earnings. Billing, payouts, refunds and the Stripe setup are not in the API.

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 tipping. Use it to load only this area: https://kickbot.com/api/v1/mcp?areas=tipping.

A team member needs one of these permissions in Manage Team: Tipping configuration or Tipping moderation. Some actions need a specific one (the action says so). Owners and admins have every permission. Write actions also need a read and write key or connection. See Permissions and security.

How the feature works in the dashboard: Set up tipping, Tip page, Tip queue, Tip moderation.

Actions

Tool	REST	Access
get_tipping_status	GET /tipping/status	Read
get_tip_queue	GET /tipping/queue	Read
get_tip_queue_settings	GET /tipping/queue/settings	Read
update_tip_queue_settings	PATCH /tipping/queue/settings	Write
resume_tip_queue	POST /tipping/queue/resume	Write
pause_tip_queue	POST /tipping/queue/pause	Write
clear_tip_queue	POST /tipping/queue/clear	Write
approve_tip	POST /tipping/queue/{id}/approve	Write
reject_tip	POST /tipping/queue/{id}/reject	Write
replay_tip	POST /tipping/transactions/{id}/replay	Write
get_tip_moderation_settings	GET /tipping/moderation	Read
update_tip_moderation_settings	PATCH /tipping/moderation	Write
list_blocked_tip_messages	GET /tipping/moderation/blocked-messages	Read
get_tip_widget_settings	GET /tipping/widget	Read
update_tip_widget_settings	PATCH /tipping/widget	Write
get_tip_page_settings	GET /tipping/payment-page	Read
update_tip_page_settings	PATCH /tipping/payment-page	Write
create_tip_banner_upload_url	POST /tipping/payment-page/banner-upload	Write
list_tip_transactions	GET /tipping/transactions	Read
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

This has an effect outside your settings (for example on your live stream).

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. This can delete or replace data, and you may not be able to undo it.

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 can delete or replace data, and you may not be able to undo it. 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 can delete or replace data, and you may not be able to undo it. 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 can delete or replace data, and you may not be able to undo it. 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 can delete or replace data, and you may not be able to undo it. 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. This can delete or replace data, and you may not be able to undo it.

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/<name>): 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. This can delete or replace data, and you may not be able to undo it. This has an effect outside your settings (for example on your live stream).

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 “<name> 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/<custom_slug>. 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. This can delete or replace data, and you may not be able to undo it.

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

This has an effect outside your settings (for example on your live stream).

No input fields.