Skip to content

Commit 083398a

Browse files
jamiepinejamiepine
committed
feat(messaging): add Twitch support and update documentation
- Updated messaging documentation to include Twitch as a supported platform, detailing connection setup and capabilities. - Added a new Twitch setup guide to assist users in connecting Spacebot to Twitch chat. - Modified existing documentation to reflect the addition of Twitch, including updates to the messaging overview and meta information. - Updated UI components to link to the new Twitch setup documentation for user assistance.
1 parent 55c452f commit 083398a

6 files changed

Lines changed: 262 additions & 38 deletions

File tree

‎docs/content/docs/(messaging)/messaging.mdx‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: Messaging
3-
description: How Spacebot connects to Discord, Slack, Telegram, and webhooks.
3+
description: How Spacebot connects to Discord, Slack, Telegram, Twitch, and webhooks.
44
---
55

66
# Messaging
@@ -14,6 +14,7 @@ Spacebot connects to chat platforms so your agent can talk to people where they
1414
| [Discord](/docs/discord-setup) | Supported | Bot token + gateway connection |
1515
| [Slack](/docs/slack-setup) | Supported | Bot token + app token via Socket Mode |
1616
| [Telegram](/docs/telegram-setup) | Supported | Bot token via BotFather |
17+
| [Twitch](/docs/twitch-setup) | Supported | OAuth token via Twitch IRC |
1718
| Webhook | Supported | HTTP endpoint for programmatic access |
1819
| Email | Coming soon | IMAP/SMTP |
1920
| WhatsApp | Coming soon | Meta Cloud API |
@@ -119,13 +120,14 @@ Each chat context maps to its own Spacebot conversation with isolated history:
119120
| Discord | Each channel, each thread, each DM |
120121
| Slack | Each channel, each thread, each DM |
121122
| Telegram | Each chat (group, DM, or channel) |
123+
| Twitch | Each channel |
122124
| Webhook | Each unique conversation ID in the request |
123125

124126
Threads are first-class on Discord and Slack — a thread gets its own conversation, separate from the parent channel.
125127

126128
## Streaming
127129

128-
Responses stream in real-time on platforms that support it. You see the reply being typed out word by word, similar to how ChatGPT works. Discord, Slack, and Telegram all support this.
130+
Responses stream in real-time on platforms that support it. You see the reply being typed out word by word, similar to how ChatGPT works. Discord, Slack, and Telegram all support this. Twitch sends the final response as a complete message since IRC doesn't support message editing.
129131

130132
## Webhook
131133

‎docs/content/docs/(messaging)/meta.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
{
22
"title": "Messaging",
3-
"pages": ["messaging", "discord-setup", "slack-setup", "telegram-setup"]
3+
"pages": ["messaging", "discord-setup", "slack-setup", "telegram-setup", "twitch-setup"]
44
}

‎docs/content/docs/(messaging)/twitch-setup.mdx‎

Lines changed: 212 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,212 @@
1+
---
2+
title: Twitch Setup
3+
description: Connect Spacebot to Twitch chat.
4+
---
5+
6+
# Twitch Setup
7+
8+
Connect Spacebot to Twitch chat. Takes about 5 minutes.
9+
10+
You need a **Twitch account** for the bot and an **OAuth token**.
11+
12+
## Step 1: Create a Twitch Account
13+
14+
Create a Twitch account for your bot (or use an existing one). The bot will send messages as this account.
15+
16+
## Step 2: Get an OAuth Token
17+
18+
Go to [twitchapps.com/tmi](https://twitchapps.com/tmi/) and authorize with the bot account. You'll get a token that looks like `oauth:abc123def456...`.
19+
20+
<Callout type="info">
21+
For production use, you can create a Twitch application at [dev.twitch.tv/console/apps](https://dev.twitch.tv/console/apps) and generate tokens with the `chat:read` and `chat:edit` scopes via the OAuth flow. The TMI token generator is fine for getting started.
22+
</Callout>
23+
24+
## Step 3: Add Credentials to Spacebot
25+
26+
<Tabs items={["Spacebot UI", "TOML Config"]}>
27+
<Tab value="Spacebot UI">
28+
29+
1. Open your Spacebot dashboard
30+
2. Go to **Settings** → **Messaging Platforms**
31+
3. Click **Setup** on the Twitch card
32+
4. Enter the bot's **username** and **OAuth token**
33+
5. Click **Save**
34+
35+
Spacebot connects immediately — no restart needed.
36+
37+
</Tab>
38+
<Tab value="TOML Config">
39+
40+
```toml
41+
[messaging.twitch]
42+
enabled = true
43+
username = "my_bot"
44+
oauth_token = "oauth:abc123def456..."
45+
channels = ["somechannel", "anotherchannel"]
46+
```
47+
48+
You can also reference environment variables:
49+
50+
```toml
51+
[messaging.twitch]
52+
enabled = true
53+
username = "env:TWITCH_BOT_USERNAME"
54+
oauth_token = "env:TWITCH_OAUTH_TOKEN"
55+
channels = ["somechannel"]
56+
```
57+
58+
Token changes in config require a restart.
59+
60+
</Tab>
61+
</Tabs>
62+
63+
## Step 4: Join Channels
64+
65+
Specify which Twitch channels the bot should join. Channel names are case-insensitive and should not include the `#` prefix.
66+
67+
<Tabs items={["Spacebot UI", "TOML Config"]}>
68+
<Tab value="Spacebot UI">
69+
70+
Add channel names in the **Channels** tag input on the Twitch binding form.
71+
72+
</Tab>
73+
<Tab value="TOML Config">
74+
75+
```toml
76+
[messaging.twitch]
77+
channels = ["streamer_name", "another_channel"]
78+
```
79+
80+
</Tab>
81+
</Tabs>
82+
83+
## Verify It's Working
84+
85+
The Twitch card on the Settings page shows a green status dot when connected. Send a message (or a trigger command if you configured one) in a joined channel — you should see the bot reply.
86+
87+
## Trigger Prefix
88+
89+
Twitch channels can be extremely high-volume. By default the bot responds to every message, which is probably not what you want in a busy stream.
90+
91+
Set a trigger prefix so the bot only responds to messages that start with it:
92+
93+
<Tabs items={["Spacebot UI", "TOML Config"]}>
94+
<Tab value="Spacebot UI">
95+
96+
The trigger prefix is configured in the TOML config file.
97+
98+
</Tab>
99+
<Tab value="TOML Config">
100+
101+
```toml
102+
[messaging.twitch]
103+
trigger_prefix = "!ask"
104+
```
105+
106+
With this config, the bot ignores all messages except those starting with `!ask`. The prefix is stripped before processing — if someone types `!ask what is rust?`, the bot sees `what is rust?`.
107+
108+
Set to an empty string or omit to respond to all messages.
109+
110+
</Tab>
111+
</Tabs>
112+
113+
## Filtering
114+
115+
### Restrict to specific channels
116+
117+
By default the bot responds in every channel it joins. To route specific channels to specific agents, add channel names to your bindings.
118+
119+
<Tabs items={["Spacebot UI", "TOML Config"]}>
120+
<Tab value="Spacebot UI">
121+
122+
Go to **Settings** → **Bindings** tab and add channel names to your Twitch binding.
123+
124+
</Tab>
125+
<Tab value="TOML Config">
126+
127+
```toml
128+
[[bindings]]
129+
agent_id = "main"
130+
channel = "twitch"
131+
channel_ids = ["streamer_name"]
132+
```
133+
134+
If `channel_ids` is empty or omitted, the bot responds in all joined channels.
135+
136+
</Tab>
137+
</Tabs>
138+
139+
### User filtering
140+
141+
Restrict which Twitch users can interact with the bot by adding login names to the binding's allowed users list.
142+
143+
<Tabs items={["Spacebot UI", "TOML Config"]}>
144+
<Tab value="Spacebot UI">
145+
146+
Add Twitch usernames to the **DM Allowed Users** list on the binding form.
147+
148+
</Tab>
149+
<Tab value="TOML Config">
150+
151+
```toml
152+
[[bindings]]
153+
agent_id = "main"
154+
channel = "twitch"
155+
dm_allowed_users = ["trusted_user", "another_mod"]
156+
```
157+
158+
When the list is empty (default), all users can interact. Permission changes hot-reload within a couple seconds — no restart needed.
159+
160+
</Tab>
161+
</Tabs>
162+
163+
### Multiple channels, multiple agents
164+
165+
Route different Twitch channels to different agents.
166+
167+
<Tabs items={["Spacebot UI", "TOML Config"]}>
168+
<Tab value="Spacebot UI">
169+
170+
Create multiple bindings in the **Bindings** tab, each with different channel names and agents.
171+
172+
</Tab>
173+
<Tab value="TOML Config">
174+
175+
```toml
176+
[[bindings]]
177+
agent_id = "main"
178+
channel = "twitch"
179+
channel_ids = ["my_stream"]
180+
181+
[[bindings]]
182+
agent_id = "support-bot"
183+
channel = "twitch"
184+
channel_ids = ["help_channel"]
185+
```
186+
187+
Each agent has its own memory, identity, and conversation history.
188+
189+
</Tab>
190+
</Tabs>
191+
192+
## Conversations
193+
194+
Each Twitch channel maps to a single conversation (`twitch:<channel_name>`). Unlike Discord or Slack, Twitch chat has no threads — all messages in a channel share one conversation context.
195+
196+
## Limitations
197+
198+
- **No streaming** — Twitch IRC doesn't support message editing, so responses are sent as complete messages rather than streamed word-by-word.
199+
- **Text only** — File attachments are sent as `[File: filename]` text notices since Twitch chat doesn't support media.
200+
- **500 character limit** — Long responses are automatically split into multiple messages.
201+
- **No history backfill** — Twitch IRC doesn't provide message history, so new conversations start fresh.
202+
- **Rate limits** — Twitch limits bots to ~20 messages per 30 seconds (100 if the bot account is a verified bot or moderator in the channel).
203+
204+
## Troubleshooting
205+
206+
| Symptom | Cause | Fix |
207+
|---------|-------|-----|
208+
| `Login authentication failed` | Invalid OAuth token | Generate a fresh token at [twitchapps.com/tmi](https://twitchapps.com/tmi/) |
209+
| Bot connects but doesn't respond | Trigger prefix set | Messages must start with the configured prefix (e.g. `!ask`) |
210+
| Bot responds to everything | No trigger prefix | Set `trigger_prefix` in the config to limit when the bot responds |
211+
| Messages getting dropped | Rate limit | Reduce response frequency or get the bot account verified |
212+
| Bot doesn't join channel | Wrong channel name | Use the login name (lowercase), not the display name |

0 commit comments

Comments
 (0)