# 接收消息 机器人接收到用户发送的消息后触发此事件。 ## 前提条件 - 应用需要开启[机器人能力](https://open.feishu.cn/document/uAjLw4CM/ugTN1YjL4UTN24CO1UjN/trouble-shooting/how-to-enable-bot-ability) - 你需要在应用中配置事件订阅，订阅 ==消息与群组== 分类下的 ==接收消息v2.0== 事件才可接收推送。了解事件订阅可参见[事件订阅概述](https://open.feishu.cn/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM) ## 注意事项 - **系统会根据应用接收消息相关权限，判断可推送的信息**： - 接收用户消息 - 接收单聊消息（用户发给机器人的单聊消息）：需具备 ==获取用户发给机器人的单聊消息（im:message.p2p_msg）== 或 ==读取用户发给机器人的单聊消息（im:message.p2p_msg:readonly）== 权限 - 接收群聊中所有用户消息（不含机器人消息）：需具备 ==获取群组中所有消息（im:message.group_msg）== 权限 - 接收群聊中用户 @ 机器人的消息（不含机器人消息）：需具备 ==获取用户在群组中@机器人的消息（im:message.group_at_msg）== 或 ==接收群聊中@机器人消息事件（im:message.group_at_msg:readonly）== 权限 - 接收机器人和用户的@消息 - 接收群聊中用户及群内机器人 @ 当前机器人的消息：需具备 ==获取群组中其他机器人和用户@当前机器人的消息（im:message.group_at_msg.include_bot:readonly）== 权限 - 可以通过sender_type字段来区分消息发送者是user还是bot - 获取附加信息相关权限： - 获取消息中的 user_agent 用户代理信息：需具备 ==获取客户端用户代理信息（im:user_agent:read）== 权限 - 特殊情况下可能会收到重复的推送，如有幂等需求请使用 ==message_id==去重，不要依赖event_id ## 事件 基本 |   ---|--- 事件类型 | im.message.receive_v1 支持的应用类型 | Custom App、Store App 权限要求
**订阅该事件所需的权限，开启其中任意一项权限即可订阅**
开启任一权限即可 | 读取用户发给机器人的单聊消息(im:message.p2p_msg:readonly)
获取群组中用户@机器人消息(im:message.group_at_msg:readonly)
获取群组中所有消息（敏感权限）(im:message.group_msg)
获取群组中其他机器人和用户@当前机器人的消息(im:message.group_at_msg.include_bot:readonly)
获取用户在群组中@机器人的消息（历史版本）(im:message.group_at_msg)
获取群聊中所有的用户聊天消息(im:message.group_msg:readonly)
获取用户发给机器人的单聊消息（历史版本）(im:message.p2p_msg) 字段权限要求 | **注意事项**：该接口返回体中存在下列敏感字段，仅当开启对应的权限后才会返回；如果无需获取这些字段，则不建议申请
获取用户 user ID(contact:user.employee_id:readonly) 推送方式 | [Webhook](https://open.feishu.cn/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM) ### 事件体 名称 | 类型 | 描述 ---|---|--- schema | string | 事件模式 header | event_header | 事件头 event_id | string | 事件 ID event_type | string | 事件类型 create_time | string | 事件创建时间戳（单位：毫秒） token | string | 事件 Token app_id | string | 应用 ID tenant_key | string | 租户 Key event | \- | \- sender | event_sender | 事件的发送者 sender_id | user_id | 用户 ID。调用[获取单个用户信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/get)接口，可通过 ID 获取用户信息。 union_id | string | 用户的 union id user_id | string | 用户的 user id
**字段权限要求**：
获取用户 user ID(contact:user.employee_id:readonly) open_id | string | 用户的 open id sender_type | string | 消息发送者类型。"user"（用户）或"bot"（机器人） tenant_key | string | tenant key，为租户在飞书上的唯一标识，用来换取对应的tenant_access_token，也可以用作租户在应用里面的唯一标识 message | event_message | 事件中包含的消息内容 message_id | string | 消息 ID。由系统生成的唯一 ID 标识，基于该 ID 可以[回复消息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/reply) 或其他管理消息的操作。 root_id | string | 根消息 ID，仅在回复消息场景会有返回值。了解 root_id 可参见[消息管理概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/intro)。 parent_id | string | 父消息 ID，仅在回复消息场景会有返回值。了解 parent_id 可参见[消息管理概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/intro)。 create_time | string | 消息发送时间（毫秒） update_time | string | 消息更新时间（毫秒） chat_id | string | 消息所在的群组 ID。调用[获取群信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/get)接口，可通过 ID 获取群组信息。 thread_id | string | 消息所属的话题 ID（不返回说明该消息非话题消息）。了解话题可参见[话题概述](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/thread-introduction)。 chat_type | string | 消息所在的群组类型
**可能值有**：
- `p2p`：单聊
- `group`： 群组 message_type | string | 消息类型，可能返回的消息类型以及详细介绍，参见[接收消息内容](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/im-v1/message/events/message_content)。 content | string | 消息内容，JSON 结构序列化后的字符串，不同消息类型（`msg_type`）对应不同内容。 mentions | mention_event\[\] | 被提及用户的信息 key | string | 被提及用户序号。例如，第 3 个被 @ 到的成员，取值为 `@_user_3` id | user_id | 被提及用户 ID。调用[获取单个用户信息](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/contact-v3/user/get)接口，可通过 ID 获取用户信息。 union_id | string | 用户的 union id user_id | string | 用户的 user id
**字段权限要求**：
获取用户 user ID(contact:user.employee_id:readonly) open_id | string | 用户的 open id mentioned_type | string | 被at者身份，user（用户）或bot（机器人） name | string | 被提及用户姓名 tenant_key | string | tenant key，为租户在飞书上的唯一标识，用来换取对应的tenant_access_token，也可以用作租户在应用里面的唯一标识 user_agent | string | 用户代理数据，仅在接收事件的机器人具备==获取客户端用户代理信息（im:user_agent:read）==权限时返回 ### 事件体示例 ```json { "schema": "2.0", "header": { "event_id": "5e3702a84e847582be8db7fb73283c02", "event_type": "im.message.receive_v1", "create_time": "1608725989000", "token": "rvaYgkND1GOiu5MM0E1rncYC6PLtF7JV", "app_id": "cli_9f5343c580712544", "tenant_key": "2ca1d211f64f6438" }, "event": { "sender": { "sender_id": { "union_id": "on_8ed6aa67826108097d9ee143816345", "user_id": "e33ggbyz", "open_id": "ou_84aad35d084aa403a838cf73ee18467" }, "sender_type": "user", "tenant_key": "736588c9260f175e" }, "message": { "message_id": "om_5ce6d572455d361153b7cb51da133945", "root_id": "om_5ce6d572455d361153b7cb5xxfsdfsdfdsf", "parent_id": "om_5ce6d572455d361153b7cb5xxfsdfsdfdsf", "create_time": "1609073151345", "update_time": "1687343654666", "chat_id": "oc_5ce6d572455d361153b7xx51da133945", "thread_id": "omt_d4be107c616", "chat_type": "group", "message_type": "text", "content": "{\"text\":\"@_user_1 hello\"}", "mentions": [ { "key": "@_user_1", "id": { "union_id": "on_8ed6aa67826108097d9ee143816345", "user_id": "e33ggbyz", "open_id": "ou_84aad35d084aa403a838cf73ee18467" }, "mentioned_type": "user", "name": "Tom", "tenant_key": "736588c9260f175e" } ], "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 13_2_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/101.0.4951.53 Safari/537.36 Lark/6.7.5 LarkLocale/en_US ttnet SDK-Version/6.7.8" } } } ``` ### 事件订阅示例代码 事件订阅流程可参考：[事件订阅概述](https://open.feishu.cn/document/ukTMukTMukTM/uUTNz4SN1MjL1UzM)，新手入门可参考：[教程](https://open.feishu.cn/document/uAjLw4CM/uMzNwEjLzcDMx4yM3ATM/develop-an-echo-bot/introduction) ** package main import ( "context" "fmt" larkcore "github.com/larksuite/oapi-sdk-go/v3/core" larkevent "github.com/larksuite/oapi-sdk-go/v3/event" "github.com/larksuite/oapi-sdk-go/v3/event/dispatcher" "github.com/larksuite/oapi-sdk-go/v3/service/im/v1" larkws "github.com/larksuite/oapi-sdk-go/v3/ws" ) // SDK 使用说明 SDK user guide：https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/server-side-sdk/golang-sdk-guide/preparations func main() { // 注册事件 Register event eventHandler := dispatcher.NewEventDispatcher("", ""). OnP2MessageReceiveV1(func(ctx context.Context, event *larkim.P2MessageReceiveV1) error { fmt.Printf("[ OnP2MessageReceiveV1 access ], data: %s\n", larkcore.Prettify(event)) return nil }) // 构建 client Build client cli := larkws.NewClient("YOUR_APP_ID", "YOUR_APP_SECRET", larkws.WithEventHandler(eventHandler), larkws.WithLogLevel(larkcore.LogLevelDebug), ) // 建立长连接 Establish persistent connection err := cli.Start(context.Background()) if err != nil { panic(err) } } # SDK 使用说明 SDK user guide：https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/server-side-sdk/python--sdk/preparations-before-development import lark_oapi as lark def do_p2_im_message_receive_v1(data: lark.im.v1.P2ImMessageReceiveV1) -> None: print(f'[ do_p2_im_message_receive_v1 access ], data: {lark.JSON.marshal(data, indent=4)}') # 注册事件 Register event event_handler = lark.EventDispatcherHandler.builder("", "") \ .register_p2_im_message_receive_v1(do_p2_im_message_receive_v1) \ .build() def main(): # 构建 client Build client cli = lark.ws.Client("APP_ID", "APP_SECRET", event_handler=event_handler, log_level=lark.LogLevel.DEBUG) # 建立长连接 Establish persistent connection cli.start() if __name__ == "__main__": main() package com.example.sample; import com.lark.oapi.core.utils.Jsons; import com.lark.oapi.service.im.ImService; import com.lark.oapi.service.im.v1.model.P2MessageReceiveV1; import com.lark.oapi.event.EventDispatcher; import com.lark.oapi.ws.Client; // SDK 使用说明 SDK user guide：https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/server-side-sdk/java-sdk-guide/preparations public class Sample { // 注册事件 Register event private static final EventDispatcher EVENT_HANDLER = EventDispatcher.newBuilder("", "") .onP2MessageReceiveV1(new ImService.P2MessageReceiveV1Handler() { @Override public void handle(P2MessageReceiveV1 event) throws Exception { System.out.printf("[ onP2MessageReceiveV1 access ], data: %s\n", Jsons.DEFAULT.toJson(event.getEvent())); } }) .build(); public static void main(String[] args) { // 构建 client Build client Client client = new Client.Builder("APP_ID", "APP_SECRET") .eventHandler(EVENT_HANDLER) .build(); // 建立长连接 Establish persistent connection client.start(); } } // SDK 使用说明 SDK user guide：https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/server-side-sdk/nodejs-sdk/preparation-before-development import * as Lark from '@larksuiteoapi/node-sdk'; const baseConfig = { appId: 'APP_ID', appSecret: 'APP_SECRET' } // 构建 client Build client const wsClient = new Lark.WSClient(baseConfig); // 建立长连接 Establish persistent connection wsClient.start({ // 注册事件 Register event eventDispatcher: new Lark.EventDispatcher({}).register({ 'im.message.receive_v1': async (data) => { console.log(data); } }) }); package main import ( "context" "fmt" "net/http" larkcore "github.com/larksuite/oapi-sdk-go/v3/core" "github.com/larksuite/oapi-sdk-go/v3/core/httpserverext" larkevent "github.com/larksuite/oapi-sdk-go/v3/event" "github.com/larksuite/oapi-sdk-go/v3/event/dispatcher" "github.com/larksuite/oapi-sdk-go/v3/service/im/v1" ) // SDK 使用说明 SDK user guide：https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/server-side-sdk/golang-sdk-guide/preparations func main() { // 注册事件 Register event eventHandler := dispatcher.NewEventDispatcher("", ""). OnP2MessageReceiveV1(func(ctx context.Context, event *larkim.P2MessageReceiveV1) error { fmt.Printf("[ OnP2MessageReceiveV1 access ], data: %s\n", larkcore.Prettify(event)) return nil }) // 创建路由处理器 Create route handler http.HandleFunc("/webhook/event", httpserverext.NewEventHandlerFunc(handler, larkevent.WithLogLevel(larkcore.LogLevelDebug))) err := http.ListenAndServe(":7777", nil) if err != nil { panic(err) } } # SDK 使用说明 SDK user guide：https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/server-side-sdk/python--sdk/preparations-before-development from flask import Flask from lark_oapi.adapter.flask import * import lark_oapi as lark app = Flask(__name__) def do_p2_im_message_receive_v1(data: lark.im.v1.P2ImMessageReceiveV1) -> None: print(f'[ do_p2_im_message_receive_v1 access ], data: {lark.JSON.marshal(data, indent=4)}') # 注册事件 Register event event_handler = lark.EventDispatcherHandler.builder("", "") \ .register_p2_im_message_receive_v1(do_p2_im_message_receive_v1) \ .build() # 创建路由处理器 Create route handler @app.route("/webhook/event", methods=["POST"]) def event(): resp = event_handler.do(parse_req()) return parse_resp(resp) if __name__ == "__main__": app.run(port=7777) package com.lark.oapi.sample.event; import com.lark.oapi.core.utils.Jsons; import com.lark.oapi.service.im.ImService; import com.lark.oapi.service.im.v1.model.P2MessageReceiveV1; import com.lark.oapi.sdk.servlet.ext.ServletAdapter; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; // SDK 使用说明 SDK user guide：https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/server-side-sdk/java-sdk-guide/preparations @RestController public class EventController { // 注册事件 Register event private static final EventDispatcher EVENT_HANDLER = EventDispatcher.newBuilder("verificationToken", "encryptKey") .onP2MessageReceiveV1(new ImService.P2MessageReceiveV1Handler() { @Override public void handle(P2MessageReceiveV1 event) throws Exception { System.out.printf("[ onP2MessageReceiveV1 access ], data: %s\n", Jsons.DEFAULT.toJson(event.getEvent())); } }) .build(); // 注入 ServletAdapter 实例 Inject ServletAdapter instance @Autowired private ServletAdapter servletAdapter; // 创建路由处理器 Create route handler @RequestMapping("/webhook/event") public void event(HttpServletRequest request, HttpServletResponse response) throws Throwable { // 回调扩展包提供的事件回调处理器 Callback handler provided by the extension package servletAdapter.handleEvent(request, response, EVENT_DISPATCHER); } } // SDK 使用说明 SDK user guide：https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/server-side-sdk/nodejs-sdk/preparation-before-development import http from 'http'; import * as lark from '@larksuiteoapi/node-sdk'; // 注册事件 Register event const eventDispatcher = new lark.EventDispatcher({ encryptKey: '', verificationToken: '', }).register({ 'im.message.receive_v1': async (data) => { console.log(data); return 'success'; }, }); const server = http.createServer(); // 创建路由处理器 Create route handler server.on('request', lark.adaptDefault('/webhook/event', eventDispatcher)); server.listen(3000);