@uStreamersBOT Documentation

What does the bot do today?

• Announces approved voice alerts: whenever you approve a viewer audio clip on your mobile app or OBS dashboard, the bot instantly posts an announcement in Twitch and Kick showing who sent the audio and how long it lasts.
• Responds to built-in commands: answers essential viewer queries including !followage, !uptime, !game, !title, !accountage, and !commands.
• Executes custom commands: create custom chat triggers (like !discord, !socials, or !specs) with user-level access controls, aliases, cooldowns, and real-time variables.
• Tracks atomic counters: manage death counters, win streaks, or community tally marks directly from chat or the mobile app without concurrency race conditions.
• Posts automated timers: dispatch periodic rotating announcements only when your channel is live and your chat meets your minimum activity threshold.
• Full in-chat moderator management: channel moderators can add, update, and remove commands or modify counters straight from chat.
• One-click migration: effortlessly import your existing configuration from Nightbot, StreamElements, Botrix, or CSV/JSON backup files with automatic syntax translation.
• Chat AI (uStreamers Plus+, optional): if you turn it on from Studio, it answers with artificial intelligence the questions your community types with the command you choose (!ia by default), always marked with 🤖.
• AI drawings (uStreamers Plus+ or MAX, optional): if you turn on the command (!dibujo by default), it replies in chat to every drawing request: whether it's on its way, whether it goes through your moderators first, or why it can't be done. See AI drawings and characters.
• Announces plan gifts: if someone gifts Plus+ or MAX to a viewer from their card in your channel's chat, the bot announces it. Turn it off with "Announce plan gifts" in its settings.

• Only messages starting with ! are processed: regular conversations are dropped immediately in memory. The bot never analyzes or stores casual viewer messages.
• Chat activity counter stores no content: to evaluate if a timer should trigger based on chat activity, the system increments a simple integer counter in volatile memory (1 per message). Message bodies, timestamps, and usernames are never stored. Once the timer fires, the count resets to zero.
• No actions from shared streams (Stream Together / Shared Chat): if your channel participates in a shared chat session with another channel, messages originating from external channels are ignored. Moderator badges from guest channels carry no authority on your bot.
• Loop prevention and ignoring other bots: the bot automatically ignores messages from known chatbot accounts (Nightbot, StreamElements, Botrix, etc.) and from its own account to prevent infinite loops.
• Kick follower records: Kick's official API does not provide a public endpoint to retrieve historical follower dates. When a user follows your Kick channel, uStreamers receives a secure webhook and stores the Kick User ID, username, and timestamp in an internal table. This record exists exclusively to power the !followage command accurately on Kick.
• Chat AI (only if you turn it on, with uStreamers Plus+): together with the drawings command, it is the only command whose text leaves uStreamers for an external provider. When someone types the AI command (!ia by default), their question and display name are sent to OpenAI to generate and moderate the answer and, if recent information is needed, a short keyword query, without the asker's name, is sent to Brave or Perplexity. We do not store questions or answers, and every answer is marked with 🤖. Details in section 17 of the Privacy Policy.
• AI drawings (only if you turn them on, with uStreamers Plus+ or MAX): when someone types the drawings command (!dibujo by default), the request text is sent to OpenAI, without the requester's name, to check it and generate the image. The request is deleted when the drawing is done. Speech bubbles on the character stage don't go through the bot: the OBS source shows them on the spot and they aren't stored. Details in section 23 of the Privacy Policy.

Editor configuration fields

• Command name: between 1 and 32 lowercase characters. Supports letters (a-z), numbers (0-9), underscores (_), and accented letters. Do not type the ! prefix.
• Response: message sent by the bot (up to 500 characters). Supports plain text and dynamic bracketed variables (e.g. {user}).
• Aliases (optional): up to 5 alternative keywords pointing to the same response (e.g. dc for !discord).
• Required permission: restricts who can trigger the command:
  • Everyone: any viewer in chat.
  • Subscribers: subscribers and founders (plus VIPs, mods, and broadcaster).
  • VIPs: viewers with VIP status (plus mods and broadcaster).
  • Moderators: channel moderators and broadcaster.
  • Streamer only (Broadcaster): exclusively the channel owner.
• Global cooldown: minimum seconds between uses by any viewer (0 to 3,600s; default: 5 seconds).
• User cooldown: cooldown per specific viewer (0 to 3,600s; default: 15 seconds).
• Platforms: choose whether the command runs on Twitch, Kick, or Both.
• Only when live: if enabled, the bot remains silent when the stream is offline.
• Enabled: master toggle to pause or reactivate a command without deleting it.

Command syntax reference

• Create new command:
  !addcom <name> [-cd=seconds] [-ul=level] [-a=alias1,alias2] <response>
  Simple example: !addcom discord Join our community at discord.gg/example
  Advanced example: !addcom giveaway -cd=30 -ul=sub -a=prize Sub giveaway active!
• Edit existing command:
  !editcom <name> [-cd=seconds] [-ul=level] [-a=alias1,alias2] <response>
  Example: !editcom discord New link: discord.gg/newlink
• Delete command:
  !delcom <name>
  Example: !delcom giveaway
• Nightbot command aliases:
  !commands add <name> ..., !commands edit <name> ..., and !commands delete <name> (or !commands del) are also fully supported.
• Counter management:
  !counter <name> → Reads current counter value.
  !counter <name> +N or -N (or + / -) → Adds or subtracts.
  !counter <name> set <N> → Sets counter to a fixed number.

How counters work

• From the mobile app: navigate to Counters to inspect your counter list, create new entries with custom initial values, update numbers, or delete them.
• From live chat: moderators can adjust counts with !counter <name> +1 or reset them with !counter <name> set 0.
• Inside custom commands: use {count:name} to increment and display the count in one step, or {getcount:name} to read the number without adding to it.
• Automatic creation: referencing {count:newcounter} in a command automatically registers the counter initialized at 1 if it did not exist previously.
• Safety and limits: each channel can create up to 100 custom counters. Increments are performed atomically in the database, preventing race conditions if multiple viewers trigger commands at the same time.

Trigger conditions

To avoid cluttering an inactive chat or posting when your stream is offline, the background worker evaluates timers every 30 seconds and only triggers when all three conditions are met simultaneously:

1. Channel is live: your broadcast must be actively live on that specific platform.
2. Interval elapsed: the configured Interval (5 to 240 minutes) must have passed since the timer last fired (or since the stream started if it hasn't fired yet).
3. Minimum chat activity: chat must have received at least the number of messages specified in Minimum chat lines (0 to 500 lines) from real viewers (bots excluded) since the last message was posted.

What happens with 0 minimum lines? If you configure 0 lines, the timer will dispatch strictly based on elapsed time without requiring chat activity.

Rotating messages and behavior

• 1 to 5 rotating messages: each timer can store up to 5 different message templates. The bot sends them in round-robin order, alternating one message on each trigger.
• Collision prevention: if two timers become eligible at the exact same moment on your channel, the bot sends one and waits 30 seconds before sending the second, ensuring messages never crowd your chat.
• Timer variables: viewer-specific variables (like {user} or {touser}) evaluate empty inside timers. Channel variables such as {channel}, {uptime}, {game}, {title}, {time:...}, {random:...}, {pick:...}, and counters {getcount:...} work seamlessly.
• Capacity: each channel can configure up to 20 automated timers.

Available import sources

• Nightbot (Official OAuth2 Connection):
  Connect your Nightbot account securely. uStreamers only requests read-only scopes for commands and timers. The temporary access token is used once in memory to pull your list and immediately discarded; it is never stored in a database or recorded in logs. If Nightbot is not configured on the server, it will display a "Coming soon" badge.
• StreamElements (JWT Token):
  Paste your StreamElements personal JWT token. You can find it in your StreamElements dashboard → Account Settings → Channel → Show secrets / JWT Token.
  Security note: uStreamers never saves or logs your JWT token. It is used strictly in volatile memory during the request. We recommend regenerating your token in StreamElements after the import completes.
• Botrix / Text / File Import:
  Paste command lists in 4 accepted formats:
  !name response
!name - response
!name: response
!name<TAB>response
  You can also upload or paste a CSV file (up to 1,000 rows and 1 MB) with headers name,response,userlevel,globalcooldown,usercooldown,aliases,platforms,onlywhenlive, or an official uStreamers backup JSON file (format: "ustreamers-bot", version: 1).

Preview and conflict resolution

Before applying any changes, the app displays a clear preview screen indicating the status of each item:

• Ready: 100% compatible and ready to import.
• Ready with warnings: compatible with minor adjustments (e.g. truncated long response, clamped timer interval to 5–240m, or converted Nightbot "Regular" level to VIP).
• Already exists (Conflict): name conflicts with an existing command, alias, counter, or timer. You can choose:
  • Skip: keeps your current command and ignores the imported item.
  • Overwrite: updates your existing command with imported settings.
  • Rename: appends a numeric suffix (e.g. !socials_2).
• Unsupported: the item cannot be imported and is omitted.

What is omitted and why?

• External requests: variables like $(urlfetch), $(customapi), $(eval), or StreamElements equivalents are rejected for security reasons (protection against SSRF attacks and remote execution).
• StreamElements keywords / regex: in uStreamers, commands always start with !name.
• StreamElements whispers: imported commands are converted to standard public chat responses.
• Offline-only timers: discarded because uStreamers only runs timers while live.

Preview session and limits: preview sessions expire after 30 minutes and can only be committed once. Streamers can submit up to 10 import requests per hour.

Variable translation matrix

This table lists the exact variable translations implemented by the import engine:

We're here to help

Our support team reviews inquiries daily. Reach out directly via email and we'll gladly assist you with your channel setup.