Bot Types
Custom Group Bot
A custom group bot operates exclusively within the chat it was added to. Created via Group Settings > Group Bots, it requires no tenant admin approval. Interaction occurs through a webhook URL. Limitations include:
- Usable only in the group where added; cannot engage in one-on-one chats.
- Supports only unidirectional push to the group; cannot invoke broader Feishu APIs or access user/tenant data.
App-Managed Bot
Created in the developer console, an app-managed bot must be published and approved by the tenant's application administrator. Authorized users can chat priavtely with the bot or add it to groups. It can call extensive Feishu APIs to access user and tenant resources post-permission approval.
Sending Messages via App-Managed Bot
Plain Text (text)
{
"receive_id": "ou_abcdef1234567890xyz",
"msg_type": "text",
"content": "{\"text\":\"sample message\"}"
}
Line breaks require \n:
{
"receive_id": "oc_12345",
"msg_type": "text",
"content": "{\"text\":\"first line \\n second line\"}"
}
Mention a user using at, specifying user_id as open_id, union_id, or user_id:
{
"receive_id": "oc_12345",
"msg_type": "text",
"content": "{\"text\":\"<at user_id=\\\"ou_98765\\\"></at> mentioned text\"}"
}
Rich Post (post)
Supports mixed elements: text, mentions, images, videos, hyperlinks. A post consists of sections [ ]; each section contains elements defined by tag and fields.
{
"receive_id": "oc_abcde12345",
"msg_type": "post",
"content": "{\"zh_cn\":{\"title\":\"Header\",\"content\":[[{\"tag\":\"text\",\"text\":\"Segment 1: \"},{\"tag\":\"a\",\"href\":\"http://www.feishu.cn\",\"text\":\"Link\"},{\"tag\":\"at\",\"user_id\":\"ou_111\",\"user_name\":\"Alice\"}],[{\"tag\":\"img\",\"image_key\":\"img_key_001\"}],[{\"tag\":\"text\",\"text\":\"Segment 2: \"},{\"tag\":\"text\",\"text\":\"More text\"}],[{\"tag\":\"img\",\"image_key\":\"img_key_002\"}]]}}"
}
Image (image)
{
"receive_id": "oc_xyz",
"msg_type": "image",
"content": "{\"image_key\":\"img_key_001\"}"
}
Image key from upload-image API.
File (file)
{
"receive_id": "oc_abc",
"msg_type": "file",
"content": "{\"file_key\":\"file_key_a1b2c3\"}"
}
File key from upload-file API.
Audio (audio)
{
"receive_id": "oc_123",
"msg_type": "audio",
"content": "{\"file_key\":\"audio_key_456\"}"
}
Audio file key from upload-file API.
Video (media)
{
"receive_id": "oc_789",
"msg_type": "media",
"content": "{\"file_key\":\"video_key_999\",\"image_key\":\"thumb_img_key\"}"
}
Video and thumbnail keys from respective upload APIs.
Interactive Card (interactive)
Card JSON example:
{
"receive_id": "oc_card123",
"msg_type": "interactive",
"content": "{\"config\":{\"wide_screen_mode\":true},\"header\":{\"template\":\"turquoise\",\"title\":{\"tag\":\"plain_text\",\"content\":\"📚 Share Books\"} },\"elements\":[{\"tag\":\"img\",\"img_key\":\"img_key_001\",\"alt\":{\"tag\":\"plain_text\",\"content\":\"\"}},{\"tag\":\"div\",\"text\":{\"tag\":\"lark_md\",\"content\":\"Join our reading event! Share notes. [Guide](https://open.feishu.cn/)\"}},{\"tag\":\"action\",\"actions\":[{\"tag\":\"button\",\"text\":{\"tag\":\"plain_text\",\"content\":\"Recommend\"},\"type\":\"primary\",\"url\":\"https://open.feishu.cn/\"},{\"tag\":\"button\",\"text\":{\"tag\":\"plain_text\",\"content\":\"View Rules\"},\"type\":\"default\",\"url\":\"https://open.feishu.cn/\"}]}]}"
}
Using template:
{
"receive_id": "ou_template",
"msg_type": "interactive",
"content": "{\"type\":\"template\",\"data\":{\"template_id\":\"tpl_555\",\"template_variable\":{\"article_title\":\"My Article\"}}}"
}
Shared Chat (share_chat)
{
"receive_id": "oc_123",
"msg_type": "share_chat",
"content": "{\"chat_id\":\"oc_group456\"}"
}
Shared User Profile (share_user)
{
"receive_id": "oc_789",
"msg_type": "share_user",
"content": "{\"user_id\":\"ou_user321\"}"
}
Bulk Messaging
Send to multiple users or department members. Requires bot capability enabled and relevant permissions. Asynchronous processing applies; daily limit is 500,000 messages per app. Only individual recipients allowed.
Message Escalation
In-App Escalation
Escalate a bot-originated message with in the app. Bot must reside in the target group. Recipient's unread escalations ≤ 200.
SMS Escalation
In-app plus SMS escalation. Consumes enterprise SMS quota.
Phone Call Escalation
In-app plus voice call escalation. Also consumes call quota.
Spring Boot Implementation
package com.example.feishu.helper;
import com.lark.oapi.Client;
import com.lark.oapi.service.im.v1.model.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.util.*;
public class FeishuMessenger {
private static final Logger logger = LoggerFactory.getLogger(FeishuMessenger.class);
public static List<UserContactInfo> fetchUsersByMobiles(List<String> numbers, String idType, Client feishuClient) {
List<UserContactInfo> results = new ArrayList<>();
int batchSize = 50;
for (int i = 0; i < numbers.size(); i += batchSize) {
List<String> chunk = numbers.subList(i, Math.min(i + batchSize, numbers.size()));
BatchGetIdUserReq req = BatchGetIdUserReq.newBuilder()
.userIdType(idType)
.batchGetIdUserReqBody(BatchGetIdUserReqBody.newBuilder().mobiles(chunk.toArray(new String[0])).build())
.build();
try {
BatchGetIdUserResp resp = feishuClient.contact().user().batchGetId(req);
if (!resp.success()) {
logger.error("Fetch failed: {} - {}", resp.getCode(), resp.getMsg());
} else if (resp.getData() != null) {
results.addAll(Arrays.asList(resp.getData().getUserList()));
}
} catch (Exception ex) {
throw new RuntimeException(ex);
}
}
return results;
}
public static void pushMessage(String targetId, String payload, String kind, String idKind, Client feishuClient) {
CreateMessageReq req = CreateMessageReq.newBuilder()
.receiveIdType(idKind)
.createMessageReqBody(CreateMessageReqBody.newBuilder()
.receiveId(targetId)
.msgType(kind)
.content(payload)
.build())
.build();
try {
CreateMessageResp resp = feishuClient.im().message().create(req);
if (!resp.success()) {
logger.error("Send error: {} - {}", resp.getCode(), resp.getMsg());
}
} catch (Exception ex) {
throw new RuntimeException(ex);
}
}
public static void escalateInApp(String msgId, List<String> users, Client feishuClient) {
UrgentAppMessageReq req = UrgentAppMessageReq.newBuilder()
.messageId(msgId)
.userIdType("user_id")
.urgentReceivers(UrgentReceivers.newBuilder().userIdList(users.toArray(new String[0])).build())
.build();
try {
UrgentAppMessageResp resp = feishuClient.im().message().urgentApp(req);
if (!resp.success()) {
logger.error("In-app escalation failed: {} - {}", resp.getCode(), resp.getMsg());
}
} catch (Exception ex) {
throw new RuntimeException(ex);
}
}
public static void escalateViaSms(String msgId, List<String> users, Client feishuClient) {
UrgentSmsMessageReq req = UrgentSmsMessageReq.newBuilder()
.messageId(msgId)
.userIdType("user_id")
.urgentReceivers(UrgentReceivers.newBuilder().userIdList(users.toArray(new String[0])).build())
.build();
try {
UrgentSmsMessageResp resp = feishuClient.im().message().urgentSms(req);
if (!resp.success()) {
logger.error("SMS escalation failed: {} - {}", resp.getCode(), resp.getMsg());
}
} catch (Exception ex) {
throw new RuntimeException(ex);
}
}
public static void escalateViaCall(String msgId, List<String> users, Client feishuClient) {
UrgentPhoneMessageReq req = UrgentPhoneMessageReq.newBuilder()
.messageId(msgId)
.userIdType("user_id")
.urgentReceivers(UrgentReceivers.newBuilder().userIdList(users.toArray(new String[0])).build())
.build();
try {
UrgentPhoneMessageResp resp = feishuClient.im().message().urgentPhone(req);
if (!resp.success()) {
logger.error("Call escalation failed: {} - {}", resp.getCode(), resp.getMsg());
}
} catch (Exception ex) {
throw new RuntimeException(ex);
}
}
}