I. Function Overview

Bots are a type of automated program that can push information to users and engage in simple interactions. You can add bots to group chats, share messages with group members in real time, and collaborate efficiently. For example, you can use Reminder bots to send reminders to team members.

Note: You can add up to 15 bots to a single group.

II. Procedure

1. Add bots to a group

Enter the group chat and click the Settings icon. Go to the Bots tab and click Add Bot. Select the bot you'd like to add to the group chat.

Some chat bots must be configured after being added to the group chat. For others, you simply need to @the bot to input commands. For specific instructions, go to Help Center > Using Feishu > Workplace to find instructions for each type of bot.

Note: Custom bots are a special kind of group bots. With associated configuration and development, custom bots can receive information from external systems and send it to chat groups via webhook. For more information about using custom bots, see Open Platform documentation Custom bot developer guide.

On the mobile, go to the group where you want to add a bot, click ... to enter the Settings. Select BOTs > Add, navigate to the bot you want to add and click Add.

Note: Custom Bot is not available on mobile.

2. View and edit bots

To view the profile information of a bot in your group, select Settings > Bot and click the bot to view its name, description, developer and other attributes. You can also remove the bot from the current group.

Note: For custom bots, you can also edit its name, description and security settings. Only custom bots added by internal members are editable. You cannot edit the custom bots added by external members outside your organization.

3.Remove a bot

Go to Settings > BOTs and click on an existing bot. Then, click Remove Bot on the right.

4.Use custom bots in a group

For full information on using custom bots, see Open Platform documentation Custom bot developer guide.

Custom bots

You can create custom bots according to your own needs. Custom bots use webhook to receive messages from external systems and then push the messages to your group chats. Custom bots are used to automatically send notifications and will not respond to your messages. Custom bots can only be used in group chats.

To make a custom bot instantly push messages from an external system to the group chat, you need to use a webhook to connect the group chat and your external system. Enter your target group and click Settings > BOTs > Add Bot. Select Custom Bot.

4.1 Steps

Step 1: Add custom bot to the group. Enter a suitable name and description for your bot and click Next.

Note: Custom Bot is not available on mobile.

Step 2: Set up webhook. You'll then get the webhook address for this group in the following format:

https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx

Copy this address and configure it in the relevant external system to send messages to your group. Be sure to keep the URL secure, or it can be used to push spam ads to your group.

Note: If the webhook you use is the old version: https://open.feishu.cn/open-apis/bot/hook/xxxxxxxxxxxxxxxxxxnov2 in the URL), please refer to the Appendix for instructions.

Step 3: Send message via webhook

Sned HTTP POST request to this webhook URL to post a message in group chat using the custom bot. Below is a request sample:

https://open.feishu.cn/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx

Please replace it with the webhook URL.

4.2 Security settings

If the webhook address isn't kept properly, there may be a risk of being spammed by malicious developers once the webhook address is leaked. We strongly recommend that it be securely set.

Security settings currently provide 3 ways, you can choose one or more ways to configure according to your needs.

•Method 1: Custom keywords

You can set up to 10 keywords. After configuration, only messages containing at least one keyword will be sent.

For example, after the custom keywords are set to "application alarm" and "item update", messages sent by the custom bot containing at least one of these words will be sent to the group chat.

After sending the request, if the custom keyword verification fails, the following information will be returned:

// 关键词校验失败
{        
    "code": 19024,        
    "msg": "Key Words Not Found"
}

•Method 2: IP allowlist

You can set up to 10 IP addresses or address fields. After configuration, only requests from the set IP address range can be processed. Field input is supported such as 123.12.1.* or 123.1.1.1/24

After sending the request, if the IP verification fails, the following information will be returned:

// IP校验失败
{        
    "code": 19022,        
    "msg": "Ip Not Allowed"
}

•Method 3: Signature verification

After configuration, the sent request requires signature verification to ensure the authenticity of the source.

Signature algorithm: Use timestamp + "\n" + key as the signature string, use the HmacSHA256 algorithm to calculate the signature, and then perform Base64 encoding.

•Timestamp isn't more than 1 hour (3600) from the current time.

•The key is automatically generated and can be copied directly from the interface.

Sample code in Go:

func GenSign(secret string, timestamp int64) (string, error) {
   //timestamp + key 做sha256, 再进行base64 encode
   stringToSign := fmt.Sprintf("%v", timestamp) + "\n" + secret
   var data []byte
   h := hmac.New(sha256.New, []byte(stringToSign))
   _, err := h.Write(data)
   if err != nil {
      return "", err
   }
   signature := base64.StdEncoding.EncodeToString(h.Sum(nil))
   return signature, nil
}

After obtaining the signature, add timestamp and sign (namely the obtained signature) fields when sending the request. An example of a request to send a text message is as follows:

Please see below for more formats of message types.

After sending the request, if the signature verification fails, please troubleshoot the following reasons:

1.The timestamp has expired more than 1 hour from the time it was sent;

2.The signature doesn't match and the verification fails.

The following information will be returned:

// 签名校验失败
{
        "code": 19021,
        "msg": "sign match fail or timestamp is not within one hour from current time"
}

4.3 Send more customized messages

Once the custom bot is added, you can send POST requests to its webhook address to post messages in your group chat. Supported message types are plain text, rich text, images, group chat sharing, etc.

The parameter msg_type represents the message type, which can be input: "text" (plain text), "post" (rich text), "image" (images), "share_chat" (group chat sharing), and interactive (message card).

Parameter (msg_type)	Message type	Reference doc
text	Plain text	-
post	Rich text	Rich text - Open Platform
image	Image	Images - Open Platform
share_chat	Share group card	Group cards- Open Platform
interactive	Message card	Message cards - Open Platform

4.3.1 Plain text messages

Request body example:

{
    "msg_type": "text",
    "content": {
        "text": "新更新提醒"
    }
}

4.3.2 Rich text messages

Request body example:

{
    "msg_type": "post",
    "content": {
        "post": {
            "zh_cn": {
                "title": "项目更新通知",
                "content": [
                    [
                        {
                            "tag": "text",
                            "text": "项目有更新: "
                        },
                        {
                            "tag": "a",
                            "text": "请查看",
                            "href": "http://www.example.com/"
                        }
                    ]
                ]
            }
        }
    }
}

For more information about the parameters you can use when sending a rich text message (including @mentioning a member in the message), please check Open Platform Help Docs.

4.3.3 Sharing group chat information

Request body example:

{
    "msg_type": "share_chat",
    "content":{
        "share_chat_id": "oc_f5b1a7eb27ae2c7b6adc2a74fafxxxxx"
    }
}

For more information about the parameters you can use when sharing group chats, please check Open Platform Help Docs.

4.3.4 Images

Request body example:

{
    "msg_type":"image",
    "content":{
        "image_key": "img_ecffc3b9-8f14-400f-a014-05eca1a4xxxx"
    }
}

For more information about the parameters you can use when sharing group chats, please check Open Platform Help Docs.

4.3.5 Message cards

Sending message cards allows you to interact with users rather than just pushing an ordinary one-way message. A message card is built with different modules and can contain various elements such as buttons, date pickers and images.

Note:

•When developing the interaction module (please check Interaction Module - Open Platform Help Docs) of message cards, message cards via custom bot - as opposed to message cards via Open Platform APIs - only support redirections, and don't support callback interactions.

•To @mention a user in your message card, note that you can only use the user's open_id, using email or user_id is not supported currently.

Request body example:

{
    "msg_type": "interactive",
    "card": {
        "config": {
                "wide_screen_mode": true,
                "enable_forward": true
        },
        "elements": [{
                "tag": "div",
                "text": {
                        "content": "**西湖**，位于浙江省杭州市西湖区龙井路1号，杭州市区西部，景区总面积49平方千米，汇水面积为21.22平方千米，湖面面积为6.38平方千米。",
                        "tag": "lark_md"
                }
        }, {
                "actions": [{
                        "tag": "button",
                        "text": {
                                "content": "更多景点介绍 :玫瑰:",
                                "tag": "lark_md"
                        },
                        "url": "https://www.example.com",
                        "type": "default",
                        "value": {}
                }],
                "tag": "action"
        }],
        "header": {
                "title": {
                        "content": "今日旅游推荐",
                        "tag": "plain_text"
                }
        }
    }
}

Note: You can also use the Message Card Builder to quickly generate the code for message cards. Insert the generated code into the "card" field in your request body.

👏Congratulations! Now you know how to use bots in groups! Go ahead and try!

III. FAQs

After adding a chat bot into a group, how do I use it?

The assistance that a chat bot can provide you depends on how the developer designed it. If you don’t know how to use a chat bot, you can get help in two ways:

•You can @mention the bot in a chat. The bot might respond to you with information about how to use it.

•If it doesn’t work, you can click the bot’s profile photo to open up the bot card. There, you can find the developer’s contact information and contact the developer for assistance. You'll need Mobile version 2.8 or higher, or Desktop version 2.9 or higher to realize this function. If you can't contact the developer, you can contact your admin for help.

Appendix: Use the previous version of webhook (custom bot)

If your webhook address is in the following pattern:

https://open.feishu.cn/open-apis/bot/hook/xxxxxxxxxxxxxxxxxx

It means this weebhook can only be used to send plain text messages. You can specify the title and text of your message in the request.

Initiate HTTP POST requests to this webhook to send plain text messages to the group. The request message format must be as follows (JSON format):

{
"title": "Hello Feishu",  # 选填
"text": "Good Feishu"  # 必填
}

cURL:

curl -X POST -H "Content-Type: application/json" -d '{"title": "Hello Feishu", "text": "Good Feishu"}'
https://open.feishu.cn/open-apis/bot/hook/xxxxxxxxxxxxxxxx

Message style: