# douyin-im-group-open-capabilities

**Repository Path**: ByteDance/douyin-im-group-open-capabilities

## Basic Information

- **Project Name**: douyin-im-group-open-capabilities
- **Description**: Douyin IM's group chat capabilities.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-03
- **Last Updated**: 2025-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 「抖音群聊开放能力」内测用户火热招募

>  **🎺抖音群聊支持主动消息推送能力啦！**
>
> 你是否想要和抖音群聊IM  一起共建开放生态呢？我们将试点开放群聊小助手能力，你可以通过 OpenAPI 主动向群内推送消息，让你的应用或授权服务直接以“群聊小助手”代发的方式出现在你自己的抖音公开群中。无论是资讯播报、活动提醒、内容订阅还是互动娱乐，你的创意都能在这里快速落地，被更多人看见和喜爱！未来我们将开放更多的能力，满足各位的诉求，欢迎大家前来体验，并向我们提出宝贵意见。[活动链接](https://bytedance.larkoffice.com/docx/ZK5IdZalgoawkPxWkIuca5pPn8U)

# 主动消息触达

通过该接口允许用户以群聊小助手（官方 AI）身份发消息至指定群聊内。群聊小助手将标注信息来源，该信息来源为提交申请人对应账号信息。

需要通过「[内测申请](https://wj.toutiao.com/q/360631/38vmO229/965f/#/)」提交指定群聊的申请，我们将在审核通过后为您提供对应授权。授权后您将获得 access-token 以使用该能力。

## 使用场景

主动消息触达至指定群聊：每群每自然日可调用至多 10 次本接口进行文本私信发送，超过将被系统拦截。

## 接口说明

### 基本信息

| **名称**        | **描述**                                                     |
| :-------------- | :----------------------------------------------------------- |
| **HTTP URL**    | [https://im-open.douyin.com/im/send/msg](https://im-open.douyin.com/im/send/msg/) |
| **HTTP Method** | POST                                                         |
| **权限要求**    | 通过申请权限xx的用户                                         |

### 请求

#### 请求头

| **名称**         | **类型** | **是否必填** | **描述**                        | 示例                                                         |
| :--------------- | :------- | :----------- | :------------------------------ | :----------------------------------------------------------- |
| **Content-Type** | string   | TRUE         | 使用固定值 "application/jsonst" | application/json                                             |
| **access-token** | string   | TRUE         | 通过“内测申请”通过的回复获取    | bus_act.1d1021d2aee3d41fee2d2adfwdf56badMFZnrhFhfWotu3Ecuiuka27L56lr |

#### 请求参数

Query

| **名称** | **类型** | **是否必填** | **描述** | **示例** |
| :------- | :------- | :----------- | :------- | :------- |
| -        | -        | -            | -        | -        |

Body

| **名称**        | **类型** | **是否必填** | **描述**                    | **示例**                                                     |
| :-------------- | :------- | :----------- | :-------------------------- | :----------------------------------------------------------- |
| conversation_id | string   | TRUE         | 会话ID                      | @9fdVxXwOOLDZg4JyKuOM0+Qc7912foPP+BPpJ3qw2uLFARa/H760zdRmYqig357zEBqu7zZ/C7rfG4tqP82908PQ== |
| content         | struct   | FALSE        | 消息体，见下方 content 构造 | {"msg_type":1,"text":"文本消息"}                             |

### Content 构造

#### 文本 Content

text 长度限制为 1000 字，不可包含不合规的外部 URL 链接：

```JSON
"content": { 
    "msg_type": 1,
    "text": "hello douyin"
}
```

### 请求示例

发送文本消息请求示例：

```
curl -X POST https://im-open.douyin.com/im/send/msg \
     -H "Content-Type: application/json" \
     -H "access-token: xxx4ulTL33iJs5mnCXU6SLJko="   \
     -d '{"content":{"text":"hello douyin", "msg_type":1},"conversation_id":"xxxxxxx"}'
```

## 响应

### 响应参数

| **名称**    | **类型**    | **描述**          | **示例**                                              |                      |
| :---------- | :---------- | :---------------- | :---------------------------------------------------- | -------------------- |
| extra       | description | string            | 错误码描述                                            | 系统内部错误，请重试 |
| logid       | string      | 标识请求的唯一 ID | 02172526999995100000000000000000000ffff0a7aab6399e422 |                      |
| now         | string      | 毫秒级时间戳      | 1725270001                                            |                      |
| data        | error_code  | string            | 错误码                                                | 28001005             |
| description | string      | 错误描述          | 系统内部错误，请重试                                  |                      |

### 响应示例

```JSON
{"data":{"error_code":"0"},"extra":{"description":"","logid":"202508261809564DC76251A2CCA90A900","now":"1756202996200"}}
```

## 错误码

| **HTTP 状态码** | **错误码** | **描述**                                 | **排查建议**                                   |
| :-------------- | :--------- | :--------------------------------------- | :--------------------------------------------- |
| 200             | 2190002    | access_token 无效或 conversation_id 错误 | 检查用户为对应群主，若依然报错请向平台提交反馈 |
| 200             | 28001005   | 系统内部错误，请重试                     | 请求重试，若依然报错请向平台提交反馈           |
| 200             | 28001006   | content 过长                             | unicode 字符集数量 <=500                       |
| 200             | 28001007   | text 为空                                | 根据错误信息检查请求频率是否正常               |
| 200             | 28001008   | 群聊 AI 开关已关闭                       | 打开设置页的群聊 AI 开关                       |
| 200             | 28001009   | 消息达到每日限额（10 条 / 天）           |                                                |