# informat.wework 企业微信相关操作

## 概述

使用 `informat.wework` 对象调用企业微信 API，覆盖客户联系、客户群、群发、欢迎语等常用接口。所有方法自动使用当前团队的企业微信配置（需先在团队后台完成集成），内部会自动处理 `access_token` 获取与刷新。

返回值均为 `Map<String, Object>`（JSON 对象），字段含义与企业微信官方文档保持一致。

## getAccessToken

获取企业微信 `access_token`。

```javascript
informat.wework.getAccessToken();
```

**返回** `String`

**示例**

```javascript
const token = informat.wework.getAccessToken();
console.log(token);
```

## getGroupChatList

获取客户群列表。参考 [官方文档](https://developer.work.weixin.qq.com/document/path/92120)。

```javascript
informat.wework.getGroupChatList(statusFilter, userIdList, partyIdList, limit, cursor);
```

| 参数           | 类型         | 描述                                                         |
|--------------|------------|------------------------------------------------------------|
| statusFilter | `Integer`  | 群状态过滤：0-所有，1-离职待继承，2-离职继承中，3-离职继承完成。可为 `null`          |
| userIdList   | `String[]` | 群主 userid 列表，可为 `null`                                     |
| partyIdList  | `String[]` | 群主部门 id 列表，可为 `null`                                       |
| limit        | `Integer`  | 每次拉取的群数量，默认 100，最大 1000                                    |
| cursor       | `String`   | 分页游标，首次查询传 `null` 或空串                                     |

**示例**

```javascript
const result = informat.wework.getGroupChatList(0, null, null, 100, null);
result.group_chat_list.forEach(g => console.log(g.chat_id, g.status));
```

## getGroupChat

获取客户群详情。参考 [官方文档](https://developer.work.weixin.qq.com/document/path/92122)。

```javascript
informat.wework.getGroupChat(chatId, needName);
```

| 参数       | 类型        | 描述                                |
|----------|-----------|-----------------------------------|
| chatId   | `String`  | 客户群 ID                             |
| needName | `Integer` | 是否返回群成员名字：0-否，1-是                |

**示例**

```javascript
const chat = informat.wework.getGroupChat('wrqVPjDAAAAb8SqvAfi3OuABDqviLKzg', 1);
console.log(chat.name, chat.owner, chat.member_list);
```

## addMsgTemplate

创建企业群发。参考 [官方文档](https://developer.work.weixin.qq.com/document/path/92135)。

```javascript
informat.wework.addMsgTemplate(msgTemplate);
```

| 参数          | 类型       | 描述                     |
|-------------|----------|------------------------|
| msgTemplate | `Object` | 群发模板，结构参考官方文档          |

**示例**

```javascript
const template = {
    chat_type: 'single',//single-发送给客户  group-发送到客户群
    external_userid: ['external_userid_xxx'],
    sender: 'DuZhanYang',
    text: { content: '您好，感谢您的关注！' },
    attachments: [
        {
            msgtype: 'link',
            link: {
                title: '欢迎链接',
                picurl: 'https://example.com/pic.jpg',
                desc: '点击查看',
                url: 'https://example.com'
            }
        }
    ]
};
const result = informat.wework.addMsgTemplate(template);
console.log(result.msgid, result.fail_list);
```

## getUnassignedList

获取离职成员的客户列表。参考 [官方文档](https://developer.work.weixin.qq.com/document/path/92124)。

```javascript
informat.wework.getUnassignedList(pageId, pageSize, cursor);
```

| 参数       | 类型        | 描述                    |
|----------|-----------|-----------------------|
| pageId   | `Integer` | 分页 id，首次传 0           |
| pageSize | `Integer` | 每页数量，默认 100，最大 1000   |
| cursor   | `String`  | 分页游标，首次查询传 `null`     |

**示例**

```javascript
const result = informat.wework.getUnassignedList(0, 100, null);
result.info.forEach(item => console.log(item.handover_userid, item.external_userid));
```

## getUserBehaviorData

获取「联系客户统计」数据。参考 [官方文档](https://developer.work.weixin.qq.com/document/path/92132)。

```javascript
informat.wework.getUserBehaviorData(userIdList, partyIdList, startTime, endTime);
```

| 参数          | 类型         | 描述                           |
|-------------|------------|------------------------------|
| userIdList  | `String[]` | 成员 userid 列表，可为 `null`        |
| partyIdList | `String[]` | 部门 id 列表，可为 `null`            |
| startTime   | `long`     | 起始时间戳（秒）                     |
| endTime     | `long`     | 结束时间戳（秒）                     |

::: warning 注意
`userIdList` 与 `partyIdList` 至少传一个；起止时间跨度不能超过 30 天。
:::

**示例**

```javascript
const end = Math.floor(Date.now() / 1000);
const start = end - 7 * 86400;
const result = informat.wework.getUserBehaviorData(['DuZhanYang'], null, start, end);
console.log(result.behavior_data);
```

## getGroupMsgResult

获取企业群发成员执行结果。参考 [官方文档](https://developer.work.weixin.qq.com/document/path/93338)。

```javascript
informat.wework.getGroupMsgResult(msgid, userid, limit, cursor);
```

| 参数     | 类型        | 描述                                   |
|--------|-----------|--------------------------------------|
| msgid  | `String`  | 群发消息的 id                              |
| userid | `String`  | 发送者的 userid                           |
| limit  | `Integer` | 每次拉取数量，默认 500                        |
| cursor | `String`  | 分页游标，首次查询传 `null`                    |

**示例**

```javascript
const result = informat.wework.getGroupMsgResult('msg_xxx', 'DuZhanYang', 500, null);
console.log(result.detail_list);
```

## getGroupMsgListV2

获取企业的全部群发记录。参考 [官方文档](https://developer.work.weixin.qq.com/document/path/93338)。

```javascript
informat.wework.getGroupMsgListV2(chatType, startTime, endTime, creator, filterType, limit, cursor);
```

| 参数         | 类型        | 描述                                            |
|------------|-----------|-----------------------------------------------|
| chatType   | `String`  | 聊天类型：`single` 或 `group`                        |
| startTime  | `long`    | 起始时间戳（秒）                                      |
| endTime    | `long`    | 结束时间戳（秒）                                      |
| creator    | `String`  | 创建人 userid，可为 `null`                           |
| filterType | `Integer` | 发送方式过滤：0-所有(默认)、1-企业发送、2-成员发送                  |
| limit      | `Integer` | 每次拉取数量，默认 50，最大 100                           |
| cursor     | `String`  | 分页游标，首次查询传 `null`                              |

**示例**

```javascript
const end = Math.floor(Date.now() / 1000);
const start = end - 7 * 86400;
const result = informat.wework.getGroupMsgListV2('single', start, end, null, 0, 50, null);
result.groupmsg_list.forEach(m => console.log(m.msgid, m.creator, m.create_time));
```

## sendWelcomeMsg

发送新客户欢迎语。参考 [官方文档](https://developer.work.weixin.qq.com/document/path/92137)。

```javascript
informat.wework.sendWelcomeMsg(welcomeCode, text, attachments);
```

::: warning 注意
`welcomeCode` 来自「添加外部联系人事件」或「入群事件」推送的事件回调，且每个 `welcomeCode` 仅能使用一次，有效期 20 秒。`text` 和 `attachments` 不能都为空。
:::

| 参数          | 类型        | 描述                                       |
|-------------|-----------|------------------------------------------|
| welcomeCode | `String`  | 事件推送携带的欢迎语 code                           |
| text        | `Object`  | 文本消息对象 `{ content: '...' }`，可为 `null`     |
| attachments | `Array`   | 附件列表，支持 image/link/miniprogram/video/file |

**示例**

```javascript
const text = { content: '欢迎添加，感谢关注！' };
const attachments = [
    {
        msgtype: 'link',
        link: {
            title: '欢迎链接',
            picurl: 'https://example.com/pic.jpg',
            desc: '点击查看',
            url: 'https://example.com'
        }
    }
];
informat.wework.sendWelcomeMsg('welcome_code_xxx', text, attachments);
```
