ContextQMD
Back to Eliza

@elizaos/plugin-twitch

plugins/plugin-twitch/README.md

2.0.14.0 KB
Original Source

@elizaos/plugin-twitch

Twitch chat integration plugin for ElizaOS agents.

Features

  • Real-time Chat: Connect to Twitch channels and participate in chat
  • Multi-channel Support: Join and monitor multiple channels simultaneously
  • Role-based Access Control: Filter interactions by user roles (broadcaster, moderator, VIP, subscriber)
  • Mention Detection: Optionally only respond when @mentioned
  • Token Refresh: Automatic OAuth token refresh (when configured)
  • Markdown Stripping: Automatically converts markdown to plain text for Twitch

Installation

bash
npm install @elizaos/plugin-twitch

Prerequisites

  1. Twitch Developer Account: Register your application at Twitch Developer Console
  2. OAuth Token: Generate a token with chat:read and chat:edit scopes at Twitch Token Generator

Configuration

Set the following environment variables:

Required

VariableDescription
TWITCH_USERNAMEBot's Twitch username
TWITCH_CLIENT_IDApplication client ID from Twitch Developer Console
TWITCH_ACCESS_TOKENOAuth access token with chat:read and chat:edit scopes
TWITCH_CHANNELPrimary channel to join (without # prefix)

Optional

VariableDescriptionDefault
TWITCH_CLIENT_SECRETApplication client secret (for token refresh)-
TWITCH_REFRESH_TOKENOAuth refresh token (for automatic refresh)-
TWITCH_CHANNELSComma-separated list of additional channels-
TWITCH_REQUIRE_MENTIONOnly respond when @mentionedfalse
TWITCH_ALLOWED_ROLESComma-separated roles allowed to interactall

Allowed Roles

  • all - Anyone can interact
  • owner / broadcaster - Channel owner only
  • moderator - Moderators
  • vip - VIP users
  • subscriber - Subscribers

Usage

Basic Setup

typescript
import twitchPlugin from "@elizaos/plugin-twitch";

const agent = new Agent({
  plugins: [twitchPlugin],
});

Actions

Twitch chat operations route through the canonical MESSAGE action using source: "twitch".

Primary actionOperationDescription
MESSAGEsendSend a message to a Twitch channel
MESSAGEjoin_channelJoin a Twitch channel
MESSAGEleave_channelLeave a Twitch channel
MESSAGElist_channelsList joined Twitch channels

Providers

Twitch does not register standalone planner providers. Channel and user context is exposed through the Twitch message connector hooks.

Events

The plugin emits the following events:

EventDescription
TWITCH_MESSAGE_RECEIVEDA chat message was received
TWITCH_MESSAGE_SENTA message was sent
TWITCH_JOIN_CHANNELBot joined a channel
TWITCH_LEAVE_CHANNELBot left a channel
TWITCH_CONNECTION_READYConnected to Twitch
TWITCH_CONNECTION_LOSTConnection lost

Message Limits

  • Maximum message length: 500 characters
  • Messages longer than 500 characters are automatically split

Security Considerations

  1. Token Security: Never expose your access token in client-side code
  2. Scope Limitation: Only request necessary OAuth scopes
  3. Role Filtering: Use TWITCH_ALLOWED_ROLES to restrict who can interact
  4. Mention Requirement: Enable TWITCH_REQUIRE_MENTION in busy channels

Troubleshooting

Connection Issues

  1. Verify your OAuth token is valid and not expired
  2. Check that the username matches the token owner
  3. Ensure the client ID is correct

Authentication Errors

  1. Regenerate your OAuth token
  2. Verify scopes include chat:read and chat:edit
  3. Check for typos in environment variables

Message Not Sending

  1. Verify you have joined the target channel
  2. Check that the channel name is correct (no # prefix)
  3. Ensure your token has chat:edit scope

License

MIT