Bot | Use bots in groups

I. Intro

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

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 Lark > Bot to find instructions for each type of bot.

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, hover your mouse to the bot, and click the Remove icon on the right.

III. How to configure custom bots in a group

This part illustrates how to configure custom bots in a group as well as related security settings.

Intended readers: Developers who need to configure a custom bot.

For full information on using custom bots, see Lark Developer documentation Custom bot developer guide.

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.

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.larksuite.com/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx

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.larksuite.com/open-apis/bot/hook/xxxxxxxxxxxxxxxxx (without v2 in the URL), please refer to the Appendix for instructions.

Step 3: Send message via webhook

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

curl -X POST -H "Content-Type: application/json" \
        -d '{"msg_type":"text","content":{"text":"request example"}}' \
  https://open.larksuite.com/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx

Please replacehttps://open.larksuite.com/open-apis/bot/v2/hook/xxxxxxxxxxxxxxxxx in the codes above with the webhook URL.

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:

// keyword verification fails
{
        "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 Not Allowed
{
        "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, and 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
}

Sample code in Java:

package sign;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import org.apache.commons.codec.binary.Base64;
public class SignDemo {
  public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeyException {
    
    String secret = "demo";
    int timestamp = 100;
    System.out.printf("sign: %s", GenSign(secret, timestamp));
}
  private static String GenSign(String secret, int timestamp) throws NoSuchAlgorithmException, InvalidKeyException {
    //Take timestamp+"\n"+key as a signature string
    String stringToSign = timestamp + "\n" + secret;
    
    //Calculate the signature using the HmacSHA256 algorithm
    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(stringToSign.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
    byte[] signData = mac.doFinal(new byte[]{});
    return new String(Base64.encodeBase64(signData));
  }
}

Sample code in Python:

import hashlib
import base64
import hmac
def gen_sign(timestamp, secret):
  # Stitch timestamp and secret
  string_to_sign = '{}\n{}'.format(timestamp, secret)
  hmac_code = hmac.new(string_to_sign.encode("utf-8"), digestmod=hashlib.sha256).digest()
  
  # Base64 processing the results
  sign = base64.b64encode(hmac_code).decode('utf-8')
  
  return sign

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 message after signature verification is turned on
{
        "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"
}

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 parametermsg_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 - Lark Developer
image	Image	Images - Lark Developer
share_chat	Share group card	Group cards- Lark Developer
interactive	Message card	Message cards - Lark Developer

a. Plain text messages

Request body example:

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

b. Rich text messages

Request body example:

{
    "msg_type": "post",
    "content": {
        "post": {
            "en_us": {
                "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 Lark Developer Help Docs.

c. 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 Lark Developer Help Docs.

d. 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 Lark Developer Help Docs.

e. 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 - Lark Developer Help Docs) of message cards, message cards via custom bot - as opposed to message cards via Lark Developer 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": "**West Lake** is a freshwater lake in Hangzhou, China. It is diveded 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"
                }
        }
    }
}

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!

IV. 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.larksuite.com/open-apis/bot/hook/xxxxxxxxxxxxxxxxx

It means this webhook 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/xxxxxxxxxxxxxxx

Message style:

Related Articles