Skip to content

Merge Fields

Understanding Merge Fields

Merge fields are placeholders used when configuring commands, recurring messages, channel-point rewards and similar features. They enable you to retrieve dynamic information from Twitch and other sources without manually entering each username or data point, streamlining the setup of bot functions and enhancing their versatility.

By incorporating merge fields, streamers can automatically pull in viewer-specific details—such as display names or local times—into any message. For instance, in a Twitch chat a viewer who sees “Hello {user}, welcome back!” will have {user} replaced with their own username in real time. This simple substitution transforms a generic prompt into a bespoke greeting, making the bot appear to recognise each viewer individually and fostering a more engaging, welcoming atmosphere.

Each feature has its own set of available merge fields and here is where we will list them:

::tip These are available to view in your dashboard under the corresponding tabs and remember these are case sensitive. These won’t work with capitalisations::

Commands:

  • Text/TTS: {message}, {user}, {streak_count} & {highest_streak}.
  • Audio: N/A
  • Image: N/A
  • Video: N/A
  • Switch Context: {message}, {user}, {streak_count} & {highest_streak}.
  • A.I. Generated Image: {message}, {user}, {streak_count} & {highest_streak}.
  • Multimedia: N/A
  • Random List Item: {selected_list_item}, {message}, {user}, {streak_count} & {highest_streak}.
  • OBS Control: N/A

Reactions:

  • Following: {user}.
  • Subscription: {tier}, {user} & {is_gift}.
  • Raids: {user} & {viewers}.
  • Cheers: <See Commands Section>
  • Gift Subscription: <See Commands Section>
  • First Message from User: {username} & {user}.
  • Ko-Fi: <See Commands Section>

Channel Point Rewards:

  • Queue Song: N/A
  • For all other rewards please see Commands Section
  • {reward_input} if the channel redemption requires an input.

Chat Streaks:

  • {user}, {streak_count} & {highest_streak}.

Recurring Messages:

  • While using the TTS toggle: {user} & {message}.

Music Player:

  • When using the Enable AI Remark Toggle: {song} & {user}.
  • Song Queued: {song}, {user} & {position}.
  • List: {list}.
  • Current Song: {song} & {user}.
  • No Current Song: N/A
  • Next Song: {song} & {user}.
  • No Next Song: N/A
  • Invalid Request: N/A
  • Queue Full: N/A
  • Max Requests: {count}.
  • Unlisted Song: N/A
  • Restricted Song: N/A
  • Requests Disabled: N/A
  • Song Too Short: {song} & {minutes}.
  • Song Too Long: {song} & {minutes}.
  • Moderation Command: {minutes} & {seconds}.

Multimedia (when adding Text fields):

  • Generic: {user}
  • Follow: {user}
  • Subscribe: {tier}, {user} & {is_gift}.
  • Raid: {user} & {viewers}.
  • Cheer: {user}, {bits} & {message}.
  • Gift Subscription: {user}, {total}, {tier} & {cumulative_total}.
  • First chat message on stream: {username} & {user}.
  • First ever chat message: {username} & {user}.
  • Ko-fi: {name}, {amount}, {message}, {currency} & {type}.

Variables:

  • {value}

Databases:

  • {content}, {added_by}, {id} & {date_added}.

Macros:

Random:

  • ${random:number} - Returns a random number
  • ${random:number:10} - Returns a random number between 0 and 10 (use any number you wish)
  • ${random:number:10:100} - Returns a random number between 10 and 100 (use any number you wish)
  • ${random:joke} - Returns a random joke from a third party API
  • ${random:database:xyz} - Return a random item from the database (replace ‘xyz’ with your databases command name). Will show as per your databases set up.
  • ${random:database:xyz:content} - As above, but will return just the content, not formatted (as per your databases current set up). Latest:
  • ${latest:follower} - Returns your latest follower
  • ${latest:subscriber} - Returns the latest subscriber Date & Time:
  • ${date} - Returns the current date
  • ${time} - Returns the current time Miscellaneous
  • ${repeat:text:1:10} - Will repeat the ‘text’ randomly from 1 to 10 times (use any numbers you wish). Replace ‘text’ with your text.

Discord Integration:

  • Go Live: {user}, {game}, {stream_title}
  • Post Clips: {clip_name} & {author}
  • AI Generative Images: {image_description} & {author}

Here is a key to help understand what some of these merge fields mean:

  • {user} & {username} – This refers to the user who used or triggered the command or the user who followed/subscribed/raided.
  • {streak_count} – This refers to the chat streak count and how many streams a user has chatted in consecutively.
  • {highest_streak} – Relates to the above merge field but shows the highest streak that the user has chatted.
  • {message} – This merge field shows the message. For example: if a user named HandsomeStrife types, for instance !tts say a thing, and your response field says {user} says: {message}, your final response will be HandsomeStrife says: say a thing.
  • {selected_list_item} – This is for Random List Item commands and refers to a specific item on that list.
  • {tier} – This highlights the tier of subscription or gift subscription to your channel.
  • {viewers} – The number of viewers joining your stream on a raid.
  • {is_gift} – Adds in whether it is a gift subscription.
  • {reward_input} – The input from the person redeeming the channel reward. For example if you have it enabled on Twitch that a person needs to type a message when redeeming, this will capture that message.
  • {song} – The song title.
  • {position} – The position of the song in the queue.
  • {list} – The list of songs in the queue.
  • {minutes} – The length of the song in minutes.
  • {count} – The maximum number of songs allowed per viewer.
  • {seconds} – The number of seconds. To be used in conjunction with {minutes}.
  • {bits} – The number of bits being donated to the streamer.
  • {total} – The total number of gift subscriptions being gifted.
  • {cumulative_total} – The total number of gift subscriptions given on the channel.
  • {name} – The name of the user donating on Ko-Fi.
  • {amount} – The amount donated on Ko-Fi.
  • {message} – Different from the merge field above, this captures the message left on Ko-Fi from the donator.
  • {currency} – The type of currency being donated.
  • {type} – The type of donation being donated on Ko-Fi.
  • {value} – The current value of your variable.
  • {content} – Refers to Database entries, such as quotes. This will provide the content from a Database entry you have set up.
  • {added_by} – This will tell you who added the database entry.
  • {id} – The ID number of the database entry.
  • {date_added} – The date the database entry was added.
  • {game} - The game you are playing on stream, set before you went live on Twitch.
  • {stream_title} - The stream title you set before going live.
  • {clip_name} - The name of the clip chosen by the editor of the clip.
  • {author} - The name of the user who clipped or redeemed the AI Generative Image.
  • {image_description} - The text input used to generate the AI Generative Image.

Should you need more clarification on merge fields, don’t hesitate to join our Discord where one of the team will be able to assist in any enquiry.