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

# IM 集成

> 在空间设置中配置 Feishu 自建应用，让 CuppyClaw 机器人可以在飞书群组中工作。

**IM 集成**用于把当前空间中的 CuppyClaw 机器人连接到即时通讯平台。当前配置入口面向飞书自建应用。

路径：空间设置 → IM 集成

<Note>
  该设置是空间级配置。不同空间可以使用不同的飞书自建应用凭证。
</Note>

## 一、 创建飞书自建应用

1. 打开 [飞书开放平台](https://open.feishu.cn/app)
2. 创建企业自建应用
3. 在应用能力中启用 **机器人**

启用机器人后，后续才能把该应用添加到飞书群组中接收消息。

## 二、 填写应用凭证

在飞书应用的 **凭证与基础信息** 页面获取：

* **App ID**
* **App Secret**

回到 Teable 的 **IM 集成** 页面，填入凭证并保存。保存或更新配置时都需要填写 App Secret。

已保存过配置后，点击 **测试连接** 可以不重新填写 App Secret；系统会复用已保存的密钥。只有需要保存新的凭证或更换密钥时，才需要重新填写 App Secret 并保存。

## 三、 导入权限范围

在飞书应用的 **权限管理** 中，使用 **批量导入/导出权限** 导入页面中提供的 Scopes JSON。

这些权限用于让机器人处理所在会话中发给机器人的消息、访问必要的会话信息，并以机器人身份发送回复。导入后请按飞书页面要求提交或保存权限变更。

## 四、 配置事件订阅

在飞书应用的 **事件与回调** → **事件配置** 中配置事件订阅：

1. 订阅方式选择 **将事件发送至开发者服务器**，不要选择长连接。
2. 将请求地址设置为 Teable 页面中显示的 Webhook URL。格式通常是：

```text theme={null}
https://your-teable-domain.com/api/im-webhook/feishu
```

3. 添加事件：

```text theme={null}
im.message.receive_v1
```

该事件用于让 Teable 接收机器人收到的消息。

## 五、 发布应用并设置可用范围

在飞书应用的 **版本管理与发布** 中创建新版本并发布应用。

发布时请确认 **可用范围** 设置为 **全员**，这样空间成员才能搜索并添加机器人。

## 六、 测试连接

回到 Teable 的 **IM 集成** 页面，点击 **测试连接**。

测试通过后，将机器人添加到飞书群组，并在群内验证 CuppyClaw 是否能收到消息和响应。

## 七、 消息内容支持

CuppyClaw 可以处理飞书群组中的文字、图片、文件、音频、视频、表情和富文本消息。对于飞书卡片和分享类消息，它会提取其中可读的标题、正文和关键字段，作为 AI 对话上下文。

如果消息类型不在支持范围内，CuppyClaw 只能看到不支持的占位内容。遇到这种情况，可以改用文字说明，或把相关文件、图片直接给 CuppyClaw。

## 八、 常见排查

* **测试连接失败**：先确认 App ID 和 App Secret 是否来自同一个飞书应用。
* **群里无法使用机器人**：确认应用已发布，并且可用范围包含当前成员。
* **机器人收不到消息**：检查事件订阅方式是否为 **将事件发送至开发者服务器**，以及是否添加了 `im.message.receive_v1` 事件。
* **更换应用密钥**：在 IM 集成页面重新填写 App Secret 并保存。