跳转至

pins

feishu.im.pins

PinsNamespace

Bases: Namespace

消息 Pin 接口命名空间。

通过 client.im.pins 访问，封装飞书会话中 Pin（置顶标记）相关的服务端接口：将某条消息 Pin 到会话、 取消 Pin、以及列举会话内的 Pin 消息。

通常无需直接实例化，应通过 client.im.pins 访问。

飞书文档

Pin 概述

源代码位于： feishu/im/pins.py
Python
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
class PinsNamespace(Namespace):
    r"""
    消息 Pin 接口命名空间。

    通过 `client.im.pins` 访问，封装飞书会话中 Pin（置顶标记）相关的服务端接口：将某条消息 Pin 到会话、
    取消 Pin、以及列举会话内的 Pin 消息。

    通常无需直接实例化，应通过 `client.im.pins` 访问。

    飞书文档:
        [Pin 概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/pin/create)
    """

    async def create(self, message_id: str) -> NestedDict:
        r"""
        将一条消息 Pin 到其所在会话。

        Args:
            message_id: 待 Pin 的消息 ID（`om_` 开头）。

        Returns:
            Pin 结果数据，含 `pin` 字段，内含 `message_id`、`chat_id`、`operator_id`、`create_time` 等信息。

        Raises:
            feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

        飞书文档:
            [Pin 一条消息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/pin/create)

        Examples:
            >>> await client.im.pins.create("om_xxx")  # doctest:+SKIP
            {'pin': {'message_id': 'om_xxx', 'chat_id': 'oc_xxx'}}
        """
        return await self._request_data("POST", "im/v1/pins", json={"message_id": message_id})

    async def delete(self, message_id: str) -> NestedDict:
        r"""
        移除一条消息的 Pin。

        Args:
            message_id: 待取消 Pin 的消息 ID。

        Returns:
            空数据体（接口成功时不返回额外字段）。

        Raises:
            feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

        飞书文档:
            [移除 Pin 消息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/pin/delete)

        Examples:
            >>> await client.im.pins.delete("om_xxx")  # doctest:+SKIP
            {}
        """
        return await self._request_data("DELETE", f"im/v1/pins/{quote_segment(message_id)}")

    async def list(
        self,
        chat_id: str,
        *,
        start_time: str | None = None,
        end_time: str | None = None,
        page_size: int = 50,
        max_items: int | None = None,
    ) -> builtins.list[NestedDict]:
        r"""
        列举会话内的 Pin 消息。

        自动翻页并汇总指定会话中的 Pin 消息，可选按时间窗过滤。

        Args:
            chat_id: 会话 ID（`oc_` 开头）。
            start_time: 起始时间（毫秒时间戳，字符串）；为空时不限制。
            end_time: 结束时间（毫秒时间戳，字符串）；为空时不限制。
            page_size: 每页数量。默认为 50；超过 [feishu.consts.MAX_PAGE_SIZE][] 时由客户端收敛。
            max_items: 最多返回的 Pin 数量，`None` 表示不限制。默认为 `None`。

        Returns:
            Pin 消息对象列表（`data.items`），每项含 `message_id`、`chat_id`、`operator_id`、`create_time` 等；
            无 Pin 时返回空列表。

        Raises:
            feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

        飞书文档:
            [获取群内 Pin 消息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/pin/list)

        Examples:
            >>> await client.im.pins.list("oc_xxx")  # doctest:+SKIP
            [{'message_id': 'om_xxx', 'operator_id': 'ou_xxx'}]
        """
        params: dict[str, Any] = {"chat_id": chat_id}
        if start_time is not None:
            params["start_time"] = start_time
        if end_time is not None:
            params["end_time"] = end_time
        return await self._client.paginate_get("im/v1/pins", params=params, page_size=page_size, max_items=max_items)

create async

Python
create(message_id: str) -> NestedDict

将一条消息 Pin 到其所在会话。

参数：

名称 类型 描述 默认
message_id
str

待 Pin 的消息 ID（om_ 开头）。

 必需

返回：

类型 描述
NestedDict

Pin 结果数据，含 pin 字段，内含 message_id、chat_id、operator_id、create_time 等信息。

引发：

类型 描述
FeishuError

请求失败或返回错误码时抛出。
飞书文档

Pin 一条消息

示例：

Python Console Session
1
2
>>> await client.im.pins.create("om_xxx")
{'pin': {'message_id': 'om_xxx', 'chat_id': 'oc_xxx'}}
源代码位于： feishu/im/pins.py
Python
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
async def create(self, message_id: str) -> NestedDict:
    r"""
    将一条消息 Pin 到其所在会话。

    Args:
        message_id: 待 Pin 的消息 ID（`om_` 开头）。

    Returns:
        Pin 结果数据，含 `pin` 字段，内含 `message_id`、`chat_id`、`operator_id`、`create_time` 等信息。

    Raises:
        feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

    飞书文档:
        [Pin 一条消息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/pin/create)

    Examples:
        >>> await client.im.pins.create("om_xxx")  # doctest:+SKIP
        {'pin': {'message_id': 'om_xxx', 'chat_id': 'oc_xxx'}}
    """
    return await self._request_data("POST", "im/v1/pins", json={"message_id": message_id})

delete async

Python
delete(message_id: str) -> NestedDict

移除一条消息的 Pin。

参数：

名称 类型 描述 默认
message_id
str

待取消 Pin 的消息 ID。

 必需

返回：

类型 描述
NestedDict

空数据体（接口成功时不返回额外字段）。

引发：

类型 描述
FeishuError

请求失败或返回错误码时抛出。
飞书文档

移除 Pin 消息

示例：

Python Console Session
1
2
>>> await client.im.pins.delete("om_xxx")
{}
源代码位于： feishu/im/pins.py
Python
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
async def delete(self, message_id: str) -> NestedDict:
    r"""
    移除一条消息的 Pin。

    Args:
        message_id: 待取消 Pin 的消息 ID。

    Returns:
        空数据体（接口成功时不返回额外字段）。

    Raises:
        feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

    飞书文档:
        [移除 Pin 消息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/pin/delete)

    Examples:
        >>> await client.im.pins.delete("om_xxx")  # doctest:+SKIP
        {}
    """
    return await self._request_data("DELETE", f"im/v1/pins/{quote_segment(message_id)}")

list async

Python
list(chat_id: str, *, start_time: str | None = None, end_time: str | None = None, page_size: int = 50, max_items: int | None = None) -> list[NestedDict]

列举会话内的 Pin 消息。

自动翻页并汇总指定会话中的 Pin 消息，可选按时间窗过滤。

参数：

名称 类型 描述 默认
chat_id
str

会话 ID（oc_ 开头）。

 必需
start_time
str | None

起始时间（毫秒时间戳，字符串）；为空时不限制。

 None
end_time
str | None

结束时间（毫秒时间戳，字符串）；为空时不限制。

 None
page_size
int

每页数量。默认为 50；超过 [feishu.consts.MAX_PAGE_SIZE][] 时由客户端收敛。

 50
max_items
int | None

最多返回的 Pin 数量，None 表示不限制。默认为 None。

 None

返回：

类型 描述
list[NestedDict]

Pin 消息对象列表（data.items），每项含 message_id、chat_id、operator_id、create_time 等；
list[NestedDict]

无 Pin 时返回空列表。

引发：

类型 描述
FeishuError

请求失败或返回错误码时抛出。
飞书文档

获取群内 Pin 消息

示例：

Python Console Session
1
2
>>> await client.im.pins.list("oc_xxx")
[{'message_id': 'om_xxx', 'operator_id': 'ou_xxx'}]
源代码位于： feishu/im/pins.py
Python
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
async def list(
    self,
    chat_id: str,
    *,
    start_time: str | None = None,
    end_time: str | None = None,
    page_size: int = 50,
    max_items: int | None = None,
) -> builtins.list[NestedDict]:
    r"""
    列举会话内的 Pin 消息。

    自动翻页并汇总指定会话中的 Pin 消息，可选按时间窗过滤。

    Args:
        chat_id: 会话 ID（`oc_` 开头）。
        start_time: 起始时间（毫秒时间戳，字符串）；为空时不限制。
        end_time: 结束时间（毫秒时间戳，字符串）；为空时不限制。
        page_size: 每页数量。默认为 50；超过 [feishu.consts.MAX_PAGE_SIZE][] 时由客户端收敛。
        max_items: 最多返回的 Pin 数量，`None` 表示不限制。默认为 `None`。

    Returns:
        Pin 消息对象列表（`data.items`），每项含 `message_id`、`chat_id`、`operator_id`、`create_time` 等；
        无 Pin 时返回空列表。

    Raises:
        feishu.errors.FeishuError: 请求失败或返回错误码时抛出。

    飞书文档:
        [获取群内 Pin 消息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/pin/list)

    Examples:
        >>> await client.im.pins.list("oc_xxx")  # doctest:+SKIP
        [{'message_id': 'om_xxx', 'operator_id': 'ou_xxx'}]
    """
    params: dict[str, Any] = {"chat_id": chat_id}
    if start_time is not None:
        params["start_time"] = start_time
    if end_time is not None:
        params["end_time"] = end_time
    return await self._client.paginate_get("im/v1/pins", params=params, page_size=page_size, max_items=max_items)