Twitch

Delivery: Source-only. Twitch is best treated as a live-channel companion. Fased joins Twitch chat through the IRC bridge, speaks as a Twitch bot account, and relies on allowlists or moderator roles to control who can trigger it. Status: source extension through Twitch chat over IRC.

Setup from Agent > Channels

Twitch is available from a source install. The lightweight hosted runtime does not currently include the Twurple dependencies, and Twitch does not yet have an official Fased add-on package. Use a maintained source install for this channel. Open Agents, select the Agent, then use Agent > Channels > Twitch. Enter the bot username, access token, client ID, and channel name, save the channel, then restart the gateway if the UI reports that the runtime still needs to load.

Quick setup (beginner)

Use a dedicated bot account when possible. It makes channel moderation, token rotation, and auditability cleaner than sharing your primary Twitch identity.

Create a dedicated Twitch account for the bot (or use an existing account).
Generate credentials: Twitch Token Generator
- Select Bot Token
- Verify scopes chat:read and chat:write are selected
- Copy the Client ID and Access Token
Find your Twitch user ID with a Twitch username-to-ID converter.
Configure the token in Agent > Channels > Twitch:
- Env: FASED_TWITCH_ACCESS_TOKEN=... (default account only)
- Or config: channels.twitch.accessToken
- If both are set, config takes precedence (env fallback is default-account only).
Start the gateway.

Important: add access control with allowFrom or allowedRoles before using the bot in a live channel. requireMention defaults to true. Minimal config:

{
  channels: {
    twitch: {
      enabled: true,
      username: "fased", // Bot's Twitch account
      accessToken: "oauth:abc123...", // or FASED_TWITCH_ACCESS_TOKEN
      clientId: "xyz789...", // Client ID from Token Generator
      channel: "vevisk", // Which Twitch channel's chat to join (required)
      allowFrom: ["123456789"], // recommended: your Twitch user ID
    },
  },
}

What it is

A Twitch channel owned by the Gateway.
Deterministic routing: replies always go back to Twitch.
Each account maps to an isolated session key: agent:<agentId>:twitch:<accountName>.
username is the bot’s account; channel is which chat room to join.

Setup (detailed)

Generate credentials

Use Twitch Token Generator:

Select Bot Token
Verify scopes chat:read and chat:write are selected
Copy the Client ID and Access Token

No manual app registration needed. Tokens expire after several hours.

Configure the bot

Env var (default account only):

FASED_TWITCH_ACCESS_TOKEN=oauth:abc123...

Or config:

{
  channels: {
    twitch: {
      enabled: true,
      username: "fased",
      accessToken: "oauth:abc123...",
      clientId: "xyz789...",
      channel: "vevisk",
    },
  },
}

If both env and config are set, config takes precedence.

Access control (recommended)

{
  channels: {
    twitch: {
      allowFrom: ["123456789"], // (recommended) Your Twitch user ID only
    },
  },
}

Prefer allowFrom for a hard allowlist. Use allowedRoles when you want role-based access. Available roles: "moderator", "owner", "vip", "subscriber", "all". Why user IDs? Usernames can change, allowing impersonation. User IDs are permanent. Find your Twitch user ID with a Twitch username-to-ID converter.

Token refresh (optional)

Tokens from Twitch Token Generator cannot be automatically refreshed. Regenerate them when expired. For automatic token refresh, create your own Twitch application at Twitch Developer Console and add to config:

{
  channels: {
    twitch: {
      clientSecret: "your_client_secret",
      refreshToken: "your_refresh_token",
    },
  },
}

The bot automatically refreshes tokens before expiration and logs refresh events.

Multi-account support

Use channels.twitch.accounts with per-account tokens. See gateway configuration for the shared pattern. Example (one bot account in two channels):

{
  channels: {
    twitch: {
      accounts: {
        channel1: {
          username: "fased",
          accessToken: "oauth:abc123...",
          clientId: "xyz789...",
          channel: "vevisk",
        },
        channel2: {
          username: "fased",
          accessToken: "oauth:def456...",
          clientId: "uvw012...",
          channel: "secondchannel",
        },
      },
    },
  },
}

Note: Each account needs its own token (one token per channel).

Access control

Role-based restrictions

{
  channels: {
    twitch: {
      accounts: {
        default: {
          allowedRoles: ["moderator", "vip"],
        },
      },
    },
  },
}

Allowlist by User ID (most secure)

{
  channels: {
    twitch: {
      accounts: {
        default: {
          allowFrom: ["123456789", "987654321"],
        },
      },
    },
  },
}

Role-based access (alternative)

allowFrom is a hard allowlist. When set, only those user IDs are allowed. If you want role-based access, leave allowFrom unset and configure allowedRoles instead:

{
  channels: {
    twitch: {
      accounts: {
        default: {
          allowedRoles: ["moderator"],
        },
      },
    },
  },
}

Disable @mention requirement

By default, requireMention is true. To disable and respond to all messages:

{
  channels: {
    twitch: {
      accounts: {
        default: {
          requireMention: false,
        },
      },
    },
  },
}

Troubleshooting

First, run diagnostic commands:

fased doctor
fased channels status --probe

Bot doesn’t respond to messages

Check access control: Ensure your user ID is in allowFrom, or temporarily remove allowFrom and set allowedRoles: ["all"] to test. Check the bot is in the channel: The bot must join the channel specified in channel.

Token issues

“Failed to connect” or authentication errors:

Verify accessToken is the OAuth access token value (typically starts with oauth: prefix)
Check token has chat:read and chat:write scopes
If using token refresh, verify clientSecret and refreshToken are set

Token refresh not working

Check logs for refresh events:

Using env token source for mybot
Access token refreshed for user 123456 (expires in 14400s)

If you see “token refresh disabled (no refresh token)”:

Ensure clientSecret is provided
Ensure refreshToken is provided

Config

Account config:

username - Bot username
accessToken - OAuth access token with chat:read and chat:write
clientId - Twitch Client ID (from Token Generator or your app)
channel - Channel to join (required)
enabled - Enable this account (default: true)
clientSecret - Optional: For automatic token refresh
refreshToken - Optional: For automatic token refresh
expiresIn - Token expiry in seconds
obtainmentTimestamp - Token obtained timestamp
allowFrom - User ID allowlist
allowedRoles - Role-based access control ("moderator" | "owner" | "vip" | "subscriber" | "all")
requireMention - Require @mention (default: true)

Provider options:

channels.twitch.enabled - Enable/disable channel startup
channels.twitch.username - Bot username (simplified single-account config)
channels.twitch.accessToken - OAuth access token (simplified single-account config)
channels.twitch.clientId - Twitch Client ID (simplified single-account config)
channels.twitch.channel - Channel to join (simplified single-account config)
channels.twitch.accounts.<accountName> - Multi-account config (all account fields above)

Full example:

{
  channels: {
    twitch: {
      enabled: true,
      username: "fased",
      accessToken: "oauth:abc123...",
      clientId: "xyz789...",
      channel: "vevisk",
      clientSecret: "secret123...",
      refreshToken: "refresh456...",
      allowFrom: ["123456789"],
      allowedRoles: ["moderator", "vip"],
      accounts: {
        default: {
          username: "mybot",
          accessToken: "oauth:abc123...",
          clientId: "xyz789...",
          channel: "your_channel",
          enabled: true,
          clientSecret: "secret123...",
          refreshToken: "refresh456...",
          expiresIn: 14400,
          obtainmentTimestamp: 1706092800000,
          allowFrom: ["123456789", "987654321"],
          allowedRoles: ["moderator"],
        },
      },
    },
  },
}

Tool actions

The agent can call twitch with action:

send - Send a message to a channel

Example:

{
  action: "twitch",
  params: {
    message: "Hello Twitch!",
    to: "#mychannel",
  },
}

Safety & ops

Treat tokens like passwords - Never commit tokens to git
Use automatic token refresh for long-running bots
Use user ID allowlists instead of usernames for access control
Monitor logs for token refresh events and connection status
Scope tokens minimally - Only request chat:read and chat:write
If stuck: Restart the gateway after confirming no other process owns the session

Limits

500 characters per message (auto-chunked at word boundaries)
Markdown is stripped before chunking
No rate limiting (uses Twitch’s built-in rate limits)

Overview

Common setup

Team and enterprise

Self-hosted and protocol

Optional and legacy

Configuration and behavior

Twitch

Twitch

Setup from Agent > Channels

Quick setup (beginner)

What it is

Setup (detailed)

Generate credentials

Configure the bot

Access control (recommended)

Token refresh (optional)

Multi-account support

Access control

Role-based restrictions

Allowlist by User ID (most secure)

Role-based access (alternative)

Disable @mention requirement

Troubleshooting

Bot doesn’t respond to messages

Token issues

Token refresh not working

Config

Tool actions

Safety & ops

Limits

​Twitch

​Setup from Agent > Channels

​Quick setup (beginner)

​What it is

​Setup (detailed)

​Generate credentials

​Configure the bot

​Access control (recommended)

​Token refresh (optional)

​Multi-account support

​Access control

​Role-based restrictions

​Allowlist by User ID (most secure)

​Role-based access (alternative)

​Disable @mention requirement

​Troubleshooting

​Bot doesn’t respond to messages

​Token issues

​Token refresh not working

​Config

​Tool actions

​Safety & ops

​Limits

Twitch

Setup from Agent > Channels

Quick setup (beginner)

What it is

Setup (detailed)

Generate credentials

Configure the bot

Access control (recommended)

Token refresh (optional)

Multi-account support

Access control

Role-based restrictions

Allowlist by User ID (most secure)

Role-based access (alternative)

Disable @mention requirement

Troubleshooting

Bot doesn’t respond to messages

Token issues

Token refresh not working

Config

Tool actions

Safety & ops

Limits