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:
| Feature | Available Merge Fields |
|---|
| 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:
| Feature | Available Merge Fields |
|---|
| 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:
| Feature | Available Merge Fields |
|---|
| Queue Song | N/A |
| Other rewards | See Commands Section |
| Channel redemption input | {reward_input} |
Chat Streaks:
| Available Merge Fields |
|---|
| {user} |
| {streak_count} |
| {highest_streak} |
Recurring Messages:
| Feature | Available Merge Fields |
|---|
| TTS toggle | {user}, {message} |
Music Player:
| Feature | Available Merge Fields |
|---|
| 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):
| Feature | Available Merge 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:
| Available Merge Fields |
|---|
| {value} |
Databases:
| Available Merge Fields |
|---|
| {content} |
| {added_by} |
| {id} |
| {date_added} |
Macros:
| Type | Format | Description |
|---|
| Random | ${random:number} | Returns a random number |
| Random | ${random:number:10} | Returns a random number between 0 and 10 |
| Random | ${random:number:10:100} | Returns a random number between 10 and 100 |
| Random | ${random:joke} | Returns a random joke from a third party API |
| Random | ${random:database:xyz} | Return a random item from the database |
| Random | ${random:database:xyz:content} | Return just the content from database |
| Latest | ${latest:follower} | Returns your latest follower |
| Latest | ${latest:subscriber} | Returns the latest subscriber |
| Date & Time | ${date} | Returns the current date |
| Date & Time | ${time} | Returns the current time |
| Miscellaneous | ${repeat:text:1:10} | Will repeat the ‘text’ randomly from 1 to 10 times |
Discord Integration:
| Feature | Available Merge Fields |
|---|
| 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:
| Merge Field | Description |
|---|
| {user} & {username} | The user who used or triggered the command or the user who followed/subscribed/raided |
| {streak_count} | The chat streak count and how many streams a user has chatted in consecutively |
| {highest_streak} | The highest streak that the user has chatted |
| {message} | The message content |
| {selected_list_item} | A specific item on the Random List Item command list |
| {tier} | The tier of subscription or gift subscription |
| {viewers} | The number of viewers joining your stream on a raid |
| {is_gift} | Whether it is a gift subscription |
| {reward_input} | The input from the person redeeming the channel reward |
| {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 (used with {minutes}) |
| {bits} | The number of bits being donated |
| {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} | 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} | The content from a Database entry |
| {added_by} | 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 |
| {stream_title} | The stream title you set before going live |
| {clip_name} | The name of the clip chosen by the editor |
| {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.
