channel

README

Lark Channel SDK for Go

中文文档

channel-sdk-go is a Go package for building Feishu and Lark conversational bots. It provides one high-level Channel entry point for WebSocket event listening, normalized inbound events, outbound messaging, media handling, interactive card callbacks, policy controls, and streaming replies.

Requires Go 1.18 or later.

Install

go get github.com/larksuite/channel-sdk-go

Minimal Example

package main

import (
	"context"
	"log"
	"os"

	channel "github.com/larksuite/channel-sdk-go"
)

func main() {
	ch, err := channel.New(os.Getenv("APP_ID"), os.Getenv("APP_SECRET"))
	if err != nil {
		log.Fatalf("create channel: %v", err)
	}

	ch.OnMessage(func(ctx context.Context, msg *channel.NormalizedMessage) error {
		_, err := ch.Send(ctx, &channel.SendInput{
			ReceiveID: msg.ChatID,
			Text:      "received: " + msg.Content,
		})
		return err
	})

	if err := ch.Start(context.Background()); err != nil {
		log.Fatalf("start channel: %v", err)
	}
}

Start(ctx) opens the WebSocket connection and blocks until the connection ends. Send and Stream use REST APIs and can be called without Start.

Documentation

Topic	Description
Documentation index	All user guides and examples
Quickstart	Prepare an app, configure events, and run an echo bot
API reference	Constructor options, defaults, methods, models, and errors
Receiving events	Message normalization, callbacks, ordering, and concurrency
Sending messages	SendInput parameters, target detection, message types, and replies
Streaming replies	Markdown and interactive-card stream controllers
Media	Upload from keys, files, bytes, or URLs and download resources
Policy and safety	Admission policy, batching, deduplication, and stale-event handling
Migration guide	Move from oapi-sdk-go/v3/channel
Troubleshooting	Events, permissions, sending, media, and streaming diagnostics
E2E testing	Run real Feishu/Lark end-to-end tests

Examples

• Send a message
• Echo bot
• Streaming reply
• Card action callback
• Custom domains

Package Boundary

Application code should normally import only the root package:

import channel "github.com/larksuite/channel-sdk-go"

The public types package is available when explicit type imports or default configuration values are useful. Packages under internal are implementation details and are not part of the compatibility contract.

This release receives events and callbacks through WebSocket long connections. It does not expose an HTTP webhook adapter. Use RawClient() or the main oapi-sdk-go/v3 module when an integration needs OpenAPI capabilities outside the Channel surface.

Local Development

go test ./...
go test -race ./...
go test ./examples/...

Real E2E tests use the e2e build tag and are not included in normal unit tests:

CHANNEL_E2E_DRY_RUN=1 go test -tags=e2e ./e2e -run TestChannelE2E -v

Contributing

Please read CONTRIBUTING.md before submitting a pull request. All contributors must follow our Code of Conduct.

Security

Report potential vulnerabilities according to SECURITY.md. Please do not disclose security vulnerabilities through public GitHub issues.

License

This project is licensed under the MIT License.

Documentation

Overview

Package channel provides the high-level Channel SDK for Go.

Use this package to create a Channel, listen for Feishu/Lark events, send messages, stream replies, handle card callbacks, and configure common OpenAPI client options. Lower-level OpenAPI clients, WebSocket clients, event dispatching, and generated service models continue to come from github.com/larksuite/oapi-sdk-go/v3.

Index

• Constants
• Variables
• type BatchConfig
• type BatchedDispatch
• type BotAddedEvent
• type BotIdentity
• type BotIdentityCacheConfig
• type CardActionContext
• type CardActionEvent
• type CardActionOperator
• type CardActionPayload
• type Channel
  • func New(appID, appSecret string, opts ...Option) (Channel, error)
• type CommentEvent
• type FeishuChannelError
• type FeishuChannelErrorCode
• type MediaKind
• type Mention
• type NormalizedMessage
• type OperatorInfo
• type Option
  • func WithBotIdentityCacheConfig(cfg types.BotIdentityCacheConfig) Option
  • func WithClientAssertionProvider(provider larkcore.ClientAssertionProvider) Option
  • func WithDomain(domain string) Option
  • func WithEnableTokenCache(enable bool) Option
  • func WithHTTPClient(httpClient larkcore.HttpClient) Option
  • func WithHeaders(headers http.Header) Option
  • func WithLogLevel(level larkcore.LogLevel) Option
  • func WithLogger(logger larkcore.Logger) Option
  • func WithOAuthBaseURL(baseURL string) Option
  • func WithOpenBaseURL(baseURL string) Option
  • func WithOutboundConfig(cfg types.OutboundConfig) Option
  • func WithPolicyConfig(cfg types.PolicyConfig) Option
  • func WithReqTimeout(timeout time.Duration) Option
  • func WithSafetyConfig(cfg types.SafetyConfig) Option
  • func WithSource(source string) Option
  • func WithTokenCache(cache larkcore.Cache) Option
  • func WithWebSocketDomain(domain string) Option
• type OutboundConfig
• type PolicyConfig
• type PolicyDecision
• type ReactionEvent
• type RejectEvent
• type RejectReason
• type Resource
• type SafetyConfig
• type SendInput
• type SendResult
• type StreamController
• type UploadInput
• type UploadResult

Constants

const (
	MediaKindImage = types.MediaKindImage
	MediaKindFile  = types.MediaKindFile
	MediaKindAudio = types.MediaKindAudio
	MediaKindVideo = types.MediaKindVideo
)

const (
	RejectReasonGroupNotAllowed  = types.RejectReasonGroupNotAllowed
	RejectReasonNoMention        = types.RejectReasonNoMention
	RejectReasonMentionAll       = types.RejectReasonMentionAll
	RejectReasonDMDisabled       = types.RejectReasonDMDisabled
	RejectReasonSenderNotAllowed = types.RejectReasonSenderNotAllowed
)

const (
	ErrCodeTargetRevoked    = types.ErrCodeTargetRevoked
	ErrCodePermissionDenied = types.ErrCodePermissionDenied
	ErrCodeFormatError      = types.ErrCodeFormatError
	ErrCodeRateLimited      = types.ErrCodeRateLimited
	ErrCodeSSRFBlocked      = types.ErrCodeSSRFBlocked
	ErrCodeSendTimeout      = types.ErrCodeSendTimeout
	ErrCodeUnknown          = types.ErrCodeUnknown
)

Variables

var ClassifyError = types.ClassifyError

var DefaultBatchConfig = types.DefaultBatchConfig

var IsFormatError = types.IsFormatError

var IsRetryable = types.IsRetryable

Types

type BatchConfig

type BatchConfig = types.BatchConfig

type BatchedDispatch

type BatchedDispatch = types.BatchedDispatch

type BotAddedEvent

type BotAddedEvent = types.BotAddedEvent

type BotIdentity

type BotIdentity = types.BotIdentity

type BotIdentityCacheConfig

type BotIdentityCacheConfig = types.BotIdentityCacheConfig

type CardActionContext

type CardActionContext = types.CardActionContext

type CardActionEvent

type CardActionEvent = types.CardActionEvent

type CardActionOperator

type CardActionOperator = types.CardActionOperator

type CardActionPayload

type CardActionPayload = types.CardActionPayload

type Channel

type Channel interface {
	types.Channel
	RawClient() *lark.Client
}

func New

func New(appID, appSecret string, opts ...Option) (Channel, error)

type CommentEvent

type CommentEvent = types.CommentEvent

type FeishuChannelError

type FeishuChannelError = types.FeishuChannelError

type FeishuChannelErrorCode

type FeishuChannelErrorCode = types.FeishuChannelErrorCode

type MediaKind

type MediaKind = types.MediaKind

type Mention

type Mention = types.Mention

type NormalizedMessage

type NormalizedMessage = types.NormalizedMessage

type OperatorInfo

type OperatorInfo = types.OperatorInfo

type Option

type Option func(*config)

func WithBotIdentityCacheConfig

func WithBotIdentityCacheConfig(cfg types.BotIdentityCacheConfig) Option

func WithClientAssertionProvider

func WithClientAssertionProvider(provider larkcore.ClientAssertionProvider) Option

func WithDomain

func WithDomain(domain string) Option

func WithEnableTokenCache

func WithEnableTokenCache(enable bool) Option

func WithHTTPClient

func WithHTTPClient(httpClient larkcore.HttpClient) Option

func WithHeaders

func WithHeaders(headers http.Header) Option

func WithLogLevel

func WithLogLevel(level larkcore.LogLevel) Option

func WithLogger

func WithLogger(logger larkcore.Logger) Option

func WithOAuthBaseURL

func WithOAuthBaseURL(baseURL string) Option

func WithOpenBaseURL

func WithOpenBaseURL(baseURL string) Option

func WithOutboundConfig

func WithOutboundConfig(cfg types.OutboundConfig) Option

func WithPolicyConfig

func WithPolicyConfig(cfg types.PolicyConfig) Option

func WithReqTimeout

func WithReqTimeout(timeout time.Duration) Option

func WithSafetyConfig

func WithSafetyConfig(cfg types.SafetyConfig) Option

func WithSource

func WithSource(source string) Option

func WithTokenCache

func WithTokenCache(cache larkcore.Cache) Option

func WithWebSocketDomain

func WithWebSocketDomain(domain string) Option

type OutboundConfig

type OutboundConfig = types.OutboundConfig

type PolicyConfig

type PolicyConfig = types.PolicyConfig

type PolicyDecision

type PolicyDecision = types.PolicyDecision

type ReactionEvent

type ReactionEvent = types.ReactionEvent

type RejectEvent

type RejectEvent = types.RejectEvent

type RejectReason

type RejectReason = types.RejectReason

type Resource

type Resource = types.Resource

type SafetyConfig

type SafetyConfig = types.SafetyConfig

type SendInput

type SendInput = types.SendInput

type SendResult

type SendResult = types.SendResult

type StreamController

type StreamController = types.StreamController

type UploadInput

type UploadInput = types.UploadInput

type UploadResult

type UploadResult = types.UploadResult