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.
- 1.Using chat bots in a group
Enter the group chat and click Settings BOTs
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
The following will mainly introduce how to set up and use custom bots.
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
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.larksuite.com/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: in the URL), please refer to the Appendix for instructions.
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 whitelist
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).Plain text messages
Request body example:
{
"msg_type": "text",
"content": {
"text": "New Updates"
}
} 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.
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.
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.
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 for mentioning users,
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!
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) (the updated version of bot is recommended)
If your webhook address is in the following pattern:
https://open.larksuite.com/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 Lark", # optional
"text": "Good Lark" # required
} cURL：
curl -X POST -H "Content-Type: application/json" -d '{"title": "Hello Lark", "text": "Good Lark"}' https://open.larksuite.com/open-apis/bot/hook/xxxxxxxxxxxxxxxx
Message style: