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.

As a special type of bot, custom bot will be the focus of this help doc.

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.

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

II. Procedure

1. Using chat bots in a group

Enter the group chat and click the Settings icon. Go to the Bots tab and click Add Bot. Click the Chat Bot tab and 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 - Bot to find instructions for each type of bot.

The following will mainly introduce how to set up and use custom bots.

1.1 Use custom bots in a group

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.

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

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 in this pattern:

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

(no v2 in the URL), please refer to the Appendix for instructions about how to use the previous version of wehbhook.

1.1.1 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:

// keywords verification failed
{
        "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 verification failed
{
        "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.

func GenSign(secret string, timestamp int64) (string, error) {
   //timestamp + key as sha256, then 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:

// send text msg after signature verification
{
        "timestamp": "1599360473",
        "sign": "xxxxxxxxxxxxxxxxxxxxx",
        "msg_type": "text",
        "content": {
                "text": "request example"
        }
}

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:

// signature verification failed
{
        "code": 19021,
        "msg": "sign match fail or timestamp is not within one hour from current time"
}

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).

1.1.2 Plain text messages

Request body example:

{
    "msg_type": "text",
    "content": {
        "text": "New Updates"
    }
}

1.1.3 Rich text messages

Request body example:

{
    "msg_type": "post",
    "content": {
        "post": {
            "zh_cn": {
                "title": "Project Updates",
                "content": [
                    [
                        {
                            "tag": "text",
                            "text": "You have a new update: "
                        },
                        {
                            "tag": "a",
                            "text": "Go check",
                            "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.

1.1.4 Sharing group chat information

Request body example:

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

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

1.1.5 Images

Request body example:

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

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

1.1.6 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.

Request body example:

{
    "msg_type": "interactive",
    "card": {
        "config": {
                "wide_screen_mode": true,
                "enable_forward": true
        },
        "elements": [{
                "tag": "div",
                "text": {
                        "content": "West Lake is a freshwater lake in Hangzhou, China. It is divided into five sections by three causeways. There are numerous temples, pagodas, gardens, and artificial islands within the lake.",
                        "tag": "lark_md"
                }
        }, {
                "actions": [{
                        "tag": "button",
                        "text": {
                                "content": "More Recommendations",
                                "tag": "lark_md"
                        },
                        "url": "https://www.example.com",
                        "type": "default",
                        "value": {}
                }],
                "tag": "action"
        }],
        "header": {
                "title": {
                        "content": "Travel Destination of the Day",
                        "tag": "plain_text"
                }
        }
    }
}

For more information about design specifications and formats of message cards, please check Open Platform Help Docs - Message Cards.

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.

2. Removing a bot

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

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

III. FAQs

Q: 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.

IV. Appendix: Use the previous version of webhook (custom bot) (the updated version of bot is recommended)

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",  # optional
"text": "Good Feishu"  # required
}

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: