go-lark

go-lark is an easy-to-use SDK for Feishu and Lark Open Platform, which implements messaging APIs, with full-fledged supports on building Chat Bot and Notification Bot.

It is widely used and tested by ~650 ByteDance in-house developers with over 3k Go packages.

Features

Notification bot & chat bot supported
Send messages (Group, Private, Rich Text, and Card)
Quick to build message with MsgBuffer
Easy to create incoming message hook
Encryption and token verification supported
Middleware support for Gin & Hertz web framework
Highly extensible
Documentation & tests

Installation

go get github.com/go-lark/lark

Quick Start

Prerequisite

There are two types of bot that is supported by go-lark. We need to create a bot manually.

Chat Bot:

Feishu: create from Feishu Open Platform.
Lark: create from Lark Developer.
App ID and App Secret are required to init a ChatBot.

Notification Bot:

Create from group chat.
Web Hook URL is required.

Sending Message

Chat Bot:

import "github.com/go-lark/lark"

func main() {
    bot := lark.NewChatBot("<App ID>", "<App Secret>")
    bot.StartHeartbeat()
    bot.PostText("hello, world", lark.WithEmail("someone@example.com"))
}

Notification Bot:

import "github.com/go-lark/lark"

func main() {
    bot := lark.NewNotificationBot("<WEB HOOK URL>")
    bot.PostNotificationV2(lark.NewMsgBuffer(lark.MsgText).Text("hello, world").Build())
}

Feishu/Lark API offers more features, please refers to Usage for further documentation.

Limits

go-lark is tested on Feishu endpoints, which literally compats Lark endpoints, because Feishu and Lark basically shares the same API specification. We do not guarantee all of the APIs work well with Lark, until we have tested it on Lark.
go-lark only supports Custom App. Marketplace App is not supported yet.
go-lark implements messaging, group chat, and bot API, other APIs such as Lark Doc, Calendar and so on are not supported.

Switch to Lark Endpoints

The default API endpoints are for Feishu, in order to switch to Lark, we should use SetDomain:

bot := lark.NewChatBot("<App ID>", "<App Secret>")
bot.SetDomain(lark.DomainLark)

Usage

Auth

Auto-renewable authentication:

// initialize a chat bot with appID and appSecret
bot := lark.NewChatBot(appID, appSecret)
// Renew access token periodically
bot.StartHeartbeat()
// Stop renewal
bot.StopHeartbeat()

Single-pass authentication:

bot := lark.NewChatBot(appID, appSecret)
resp, err := bot.GetTenantAccessTokenInternal(true)
// and we can now access the token value with `bot.TenantAccessToken()`

Example: examples/auth

Messaging

For Chat Bot, we can send simple messages with the following method:

PostText
PostTextMention
PostTextMentionAll
PostImage
PostShareChatCard
ReplyMessage
AddReaction
DeleteReaction

Basic message examples: examples/basic-message

To build rich messages, we may use Message Buffer (or simply MsgBuffer), which builds message conveniently with chaining methods.

Examples

Apart from the general auth and messaging chapter, there are comprehensive examples for almost all APIs. Here is a collection of ready-to-run examples for each part of go-lark:

Message Buffer

We can build message body with MsgBuffer and send with PostMessage, which supports the following message types:

MsgText: Text
MsgPost: Rich Text
MsgInteractive: Interactive Card
MsgShareCard: Group Share Card
MsgShareUser: User Share Card
MsgImage: Image
MsgFile: File
MsgAudio: Audio
MsgMedia: Media
MsgSticker: Sticker

MsgBuffer provides binding functions and content functions.

Binding functions:

| Function | Usage | Comment | | ----------- | ------------------- | --------------------------------------------------------------------------- | | BindChatID | Bind a chat ID | Either OpenID, UserID, Email, ChatID or UnionID should be present | | BindOpenID | Bind a user open ID | | | BindUserID | Bind a user ID | | | BindUnionID | Bind a union ID | | | BindEmail | Bind a user email | | | BindReply | Bind a reply ID | Required when reply a message |

Content functions pair with message content types. If it mismatched, it would not have sent successfully. Content functions:

| Function | Message Type | Usage | Comment | | --------- | ---------------- | ----------------------- | ---------------------------------------------------------------- | | Text | MsgText | Append plain text | May build with TextBuilder | | Post | MsgPost | Append rich text | May build with PostBuilder | | Card | MsgInteractive | Append interactive card | May build with CardBuilder | | Template | MsgInteractive | Append card template | Required to build with CardKit | | ShareChat | MsgShareCard | Append group share card | | | ShareUser | MsgShareUser | Append user share card | | | Image | MsgImage | Append image | Required to upload to Lark server in advance | | File | MsgFile | Append file | Required to upload to Lark server in advance | | Audio | MsgAudio | Append audio | Required to upload to Lark server in advance | | Media | MsgMedia | Append media | Required to upload to Lark server in advance | | Sticker | MsgSticker | Append sticker | Required to upload to Lark server in advance |

Error Handling

Each go-lark API function returns response and err. err is the error from HTTP client, when it was not nil, HTTP might have gone wrong.

While response is HTTP response from Lark API server, in which Code and OK represent whether it succeeds. The meaning of Code is defined here.

Event

Lark provides a number of events and they are in two different schema (1.0/2.0). go-lark now only implements a few of them, which are needed for interacting between bot and Lark server:

URL Challenge
Receiving Messages

We recommend HTTP middlewares to handle these events.

Middlewares

We have already implemented HTTP middlewares to support event handling:

Example: examples/gin-middleware examples/hertz-middleware

URL Challenge

r := gin.Default()
middleware := larkgin.NewLarkMiddleware()
middleware.BindURLPrefix("/handle") // supposed URL is http://your.domain.com/handle
r.Use(middleware.LarkChallengeHandler())

Event V2

Lark has provided event v2 and it applied automatically to newly created bots.

r := gin.Default()
middleware := larkgin.NewLarkMiddleware()
r.Use(middleware.LarkEventHandler())

Get the event (e.g. Message):

r.POST("/", func(c *gin.Context) {
    if evt, ok := middleware.GetEvent(c); ok { // => GetEvent instead of GetMessage
        if evt.Header.EventType == lark.EventTypeMessageReceived {
            if msg, err := evt.GetMessageReceived(); err == nil {
                fmt.Println(msg.Message.Content)
            }
        }
    }
})

Lark

Install / Use

README