go-lark SDK

For rich messages, use MsgBuffer (or lark.NewMsgBuffer) which allows for method chaining to build message bodies.

Supported Message Types

• MsgText: Plain text
• MsgPost: Rich text
• MsgInteractive: Interactive cards
• MsgShareCard: Group share cards
• MsgShareUser: User share cards
• MsgImage: Images
• MsgFile: Files
• MsgAudio: Audio
• MsgMedia: Media
• MsgSticker: Stickers

Binding Functions

Use these to specify the recipient or context:

• BindChatID: Bind to OpenID, UserID, Email, ChatID, or UnionID.
• BindOpenID: Bind to a user's Open ID.
• BindUserID: Bind to a user's User ID.
• BindUnionID: Bind to a user's Union ID.
• BindEmail: Bind to a user's email.
• BindReply: Required when replying to a specific message ID.

Content Functions

Pair these with the appropriate message type:

• Text for MsgText
• Post for MsgPost
• Card for MsgInteractive
• Template for MsgInteractive (requires CardKit)
• ShareChat for MsgShareCard
• ShareUser for MsgShareUser
• Image, File, Audio, Media, Sticker (requires prior upload to Lark server)

For simple messages, use direct methods like PostText, PostImage, or ReplyMessage. For complex messages, use MsgBuffer to chain construction before calling PostMessage.

Supported Message Types

• MsgText: Text
• MsgPost: Rich Text
• MsgInteractive: Interactive Cards (supports Card or Template)
• MsgShareUser: User Card
• MsgShareCard: Group Card
• MsgImage, MsgFile, MsgAudio, MsgMedia, MsgSticker: Media types (requires prior upload to Lark/Feishu servers)

MsgBuffer Bind Functions (Targeting)

Use these to specify who receives the message:

• BindChatID, BindOpenID, BindUserID, BindUnionID, BindEmail, BindReply (for replies).

MsgBuffer Content Functions

These are type-specific:

• Text (for MsgText)
• Post (for MsgPost)
• Card / Template (for MsgInteractive)
• ShareChat (for MsgShareCard)
• ShareUser (for MsgShareUser)
• Image, File, Audio, Media, Sticker (for media types)

You can extend go-lark to support new Lark Open Platform APIs by leveraging its existing infrastructure for authentication and HTTP handling. Use the bot.PostAPIRequest method to implement new functionality.

To implement a custom API:

1. Define the API URL pattern.
2. Define response structures that embed lark.BaseResponse.
3. Use bot.PostAPIRequest to execute the request, passing the context, a name for the operation, the URL, a boolean indicating if it's a POST request, the request body, and a pointer to your response object.

package lark

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

const copyFileAPIPattern = "/open-apis/drive/explorer/v2/file/copy/files/%s"

type CopyFileResponse struct {
	lark.BaseResponse
	Data CopyFileData `json:"data"`
}

type CopyFileData struct {
	FolderToken string `json:"folderToken"`
	Revision    int64  `json:"revision"`
	Token       string `json:"token"`
	Type        string `json:"type"`
	URL         string `json:"url"`
}

func CopyFile(ctx context.Context, bot *lark.Bot, fileToken, dstFolderToken, dstName string) (*CopyFileResponse, error) {
	var respData CopyFileResponse
	err := bot.PostAPIRequest(
		ctx,
		"CopyFile",
		fmt.Sprintf(copyFileAPIPattern, fileToken),
		true,
		map[string]interface{}{
			"type":             "doc",
			"dstFolderToken":   dstFolderToken,
			"dstName":          dstName,
			"permissionNeeded": true,
			"CommentNeeded":    false,
		},
		&respData,
	)
	return &respData, err
}

To receive events (like messages or URL challenges) in a Gin web server, use the lark-gin middleware.

URL Challenge

Required for verifying your webhook URL with Lark.

Event V2

Lark's current standard for new bots. Use LarkEventHandler() to register the handler and GetEvent(c) to extract the event data.

Card Callback

To handle interactions from interactive cards (e.g., button clicks), use LarkCardHandler() and GetCardCallback(c).

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

// 1. Handle URL Challenge
middleware.BindURLPrefix("/handle")
r.Use(middleware.LarkChallengeHandler())

// 2. Handle Event V2
r.Use(middleware.LarkEventHandler())
r.POST("/", func(c *gin.Context) {
    if evt, ok := middleware.GetEvent(c); ok {
        if evt.Header.EventType == lark.EventTypeMessageReceived {
            if msg, err := evt.GetMessageReceived(); err == nil {
                fmt.Println(msg.Message.Content)
            }
        }
    }
})

// 3. Handle Card Callbacks
r.Use(middleware.LarkCardHandler())
r.POST("/callback", func(c *gin.Context) {
    if card, ok := middleware.GetCardCallback(c); ok {
        // Handle card action
    }
})

The SDK supports two types of bots:

1. ChatBot: Created via the Feishu or Lark Developer platforms. Requires an App ID and App Secret.
2. NotificationBot: Created via a group chat Webhook. Requires a WebHook URL.

ChatBot Example

bot := lark.NewChatBot("<App ID>", "<App Secret>")
bot.PostText(context.Background(), "hello, world", lark.WithEmail("someone@example.com"))

NotificationBot Example

bot := lark.NewNotificationBot("<WEB HOOK URL>")
bot.PostNotification(context.Background(), lark.NewMsgBuffer(lark.MsgText).Text("hello, world").Build())

import (
    "context"
    "github.com/go-lark/lark/v2"
)

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

    // NotificationBot
    nBot := lark.NewNotificationBot("<WEB HOOK URL>")
    nBot.PostNotification(context.Background(), lark.NewMsgBuffer(lark.MsgText).Text("hello, world").Build())
}