> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vetox.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Twitch 通知

> 当 Twitch 主播开播或下播时在 Discord 中公告，配以完全可自定义的嵌入。

<Info>
  需要 **Basic**。每服务器最多 **10 位主播**。所有平台共享的规则请参见 [通知如何工作](/zh-CN/notifications/overview)。
</Info>

## 添加主播

按名字搜索频道 —— Vetox 会在 Twitch 上查询并在添加前确认它存在。无法解析的用户名会以 **Twitch user not found** 被拒绝。

用户名为 1–25 个字符，仅字母、数字和下划线。

## 设置

| 设置             | 默认值       | 说明                    |
| -------------- | --------- | --------------------- |
| **Discord 频道** | —         | 必需。按主播设置，不同主播可发布到不同频道 |
| **上线时通知**      | **开启**    | 直播公告                  |
| **下线时通知**      | **关闭**    | 直播结束时的第二条公告           |
| **提及角色**       | 无         | 随公告 ping              |
| **自定义通知嵌入**    | Twitch 默认 | 紫色，带直播标题、游戏和观众数       |

## 变量

| 变量                   | 解析为                 |
| -------------------- | ------------------- |
| `{streamer.name}`    | 主播的显示名              |
| `{streamer.url}`     | 他们的 Twitch 频道 URL   |
| `{streamer.avatar}`  | 他们的头像               |
| `{stream.title}`     | 直播标题 —— **仅直播公告**   |
| `{stream.game}`      | 正在直播的分类 —— **仅直播中** |
| `{stream.viewers}`   | 公告时的观众数 —— **仅直播中** |
| `{stream.thumbnail}` | 直播预览图 —— **仅直播中**   |

<Warning>
  四个 `{stream.*}` 变量在 **下线** 公告中没有值。由它们构建的任何嵌入字段会从该消息中消失。请让您的下线嵌入只用 `{streamer.*}` 变量。
</Warning>

## 如何检测开播

Vetox 每 **60 秒** 检查一次，并跟踪频道是否直播中。

<Steps>
  <Step title="离线 → 直播">
    公告触发，每个主播 **10 分钟冷却**。
  </Step>

  <Step title="仍在直播">
    无。状态仅刷新 —— 一次长直播只产生一次公告。
  </Step>

  <Step title="直播 → 离线">
    如果您启用了下线公告则会触发。
  </Step>
</Steps>

<Warning>
  **添加一位已经在直播的主播不会公告任何东西。** 跟踪器在转变时触发，而非当前状态。您的第一条公告将是他们的下一次直播。
</Warning>

<Note>
  在冷却窗口内短暂掉线并重连的直播只产生一次公告，而非两次 —— 这是有意的，也是冷却为 10 分钟而非 1 分钟的原因。
</Note>

## 实操设置

<Steps>
  <Step title="在服务器设置中启用 Twitch">
    默认关闭。在其开启之前什么都不工作。
  </Step>

  <Step title="添加主播">
    搜索他们的名字并从结果中选择。
  </Step>

  <Step title="选择频道和角色">
    大多数服务器采用的模式是一个专用 `#going-live` 频道，加上一个成员通过 [自助角色](/zh-CN/engagement/self-roles) 选择加入的 `@Stream Ping` 角色。
  </Step>

  <Step title="检查机器人在那里的权限">
    查看频道、发送消息和 **嵌入链接**。
  </Step>

  <Step title="等待他们的下一次直播">
    请不要通过在直播中途添加某人来判断它。
  </Step>
</Steps>

## 疑难解答

<AccordionGroup>
  <Accordion title="他们上线但什么都没发">
    请检查服务器设置的 Twitch 开关、高级会员是否有效，以及频道的嵌入链接权限。如果您是在他们已经在直播时添加的，这是预期行为 —— 请等待下一次直播。
  </Accordion>

  <Accordion title="游戏或观众数缺失">
    您在看下线公告。这些变量仅在直播中存在。
  </Accordion>

  <Accordion title="更改频道未生效">
    清空频道字段不会发送任何东西，会静默保留旧值。请选择另一个频道，而不是清空它。
  </Accordion>

  <Accordion title="两个服务器关注同一主播但只有一个收到 ping">
    两者都应触发。如果一个频道的权限失败，该项目会丢失且不重试 —— 请检查失败一侧的嵌入链接权限。
  </Accordion>
</AccordionGroup>

<Card title="Kick" icon="tower-broadcast" horizontal href="/zh-CN/notifications/kick">
  Kick 上相同的直播/离线模型。
</Card>