Feishu OpenPlatform Server SDK for Java

LarkChannel is a high-level abstraction in the Java SDK designed for conversational bots and AI Agents. It encapsulates WebSocket/Webhook event ingestion, message normalization, security policies, message sending, streaming output, resource management, and interactive components (cards/reactions) into a single unified interface.

When to use LarkChannel:

• Building AI Agents, customer service assistants, or knowledge base bots.
• Long-term monitoring of 1-on-1 chats, group chats, card actions, reactions, or document comments.
• When you need to convert raw Lark events into a unified NormalizedMessage format.
• When you require built-in security policies like deduplication, expiration filtering, or @mention requirements.
• When you need streaming responses (e.g., an Agent generating text incrementally).

When to use Client instead:

• If you only need to occasionally call a specific Open Platform API without maintaining a continuous conversational session.

// Use LarkChannel for conversational logic, Client for one-off API calls.
LarkChannel channel = LarkChannelFactory.createLarkChannel(...);

You can use the addons parameter in RegisterAppOptions to incrementally request specific permissions, event subscriptions, or callbacks. These are pre-filled on the user's confirmation page.

Key Concepts

• Additive Only: addons are merged on top of the platform's base template. You cannot remove base permissions via addons.
• Base Template Switch:
  • addons.preset(true) (default): Uses the platform's default template.
  • addons.preset(false): Switches to a minimal base template (bot capability only). This allows you to declare the full configuration via addons.
• Supported Types: Only tenant/user scopes, tenant/user events, and callbacks are supported. Sensitive configurations (like event request URLs or encryption keys) must be updated via the update application config OpenAPI instead.

Usage Scenarios

1. Create a new app with specific permissions

RegisterApp.register(RegisterAppOptions.newBuilder()
        .addons(AppAddons.newBuilder()
                .tenantScopes("im:message:send_as_bot")
                .userScopes("calendar:calendar:read")
                .tenantEvents("im.message.receive_v1")
                .callbacks("card.action.trigger")
                .build())
        .createOnly(true)
        .onQRCode(info -> System.out.println(info.getUrl()))
        .build());

2. Update an existing app

Pass the existing appId to allow the user to confirm incremental changes.

RegisterApp.register(RegisterAppOptions.newBuilder()
        .appId("cli_xxx")
        .addons(AppAddons.newBuilder()
                .tenantScopes("drive:drive.metadata:readonly")
                .build())
        .onQRCode(info -> System.out.println(info.getUrl()))
        .build());

3. Use a minimal base template

Set preset(false) to ensure the confirmation page only shows the configuration you explicitly declare.

RegisterApp.register(RegisterAppOptions.newBuilder()
        .addons(AppAddons.newBuilder()
                .preset(false)
                .tenantScopes("im:message:send_as_bot")
                .build())
        .onQRCode(info -> System.out.println(info.getUrl()))
        .build());

For AI Agents, bots, customer service assistants, or knowledge base Q&A, use the LarkChannel high-level session channel. It abstracts WebSocket/Webhook event ingestion, message normalization, security policies, reply sending, streaming output, resource management, card actions, and emoji reactions into a unified Java interface.

When to use:

• Use Client for occasional API calls.
• Use LarkChannel for long-term message listening, context understanding, and automated responses.

Core Workflow:

1. Create a channel using LarkChannelFactory.createLarkChannel(...).
2. Call connect() to start listening. It returns a CompletableFuture<BotIdentity> to access the bot's identity.
3. Listen for events using .on("message", handler), .on("cardAction", handler), or .on("reject", handler).
4. Respond using send(...) or stream results using stream(...).
5. Configure security via policy(...) (e.g., group chat whitelists, single-chat mode, or requiring @mentions).
6. Enable includeRawEvent(true) only if you specifically need original event fields.

// Conceptual usage pattern
LarkChannel channel = LarkChannelFactory.createLarkChannel(...);
channel.connect().thenAccept(identity -> {
    channel.on("message", (context, event) -> {
        channel.send(...);
    });
});

The SDK includes a PolicyConfig to control how the bot interacts with messages. By default, the SDK is optimized for Agent scenarios (e.g., requiring a mention in group chats).

Key Policy Settings:

• setGroupAllowlist(String chatId): Only allow messages from these groups.
• setDmMode(String mode): Control Direct Message behavior (e.g., using an allowlist).
• setDmAllowlist(String userId): Only allow DMs from these users.
• setRequireMention(boolean): If true, the bot ignores group messages that don't @ it.
• setRespondToMentionAll(boolean): If true, the bot responds to @all even if not specifically @'d.

Handling Rejected Events: When a message is blocked by policy, a reject event is triggered. You can listen for this using channel.on("reject", ...) to inspect the RejectEvent, which contains the reason (e.g., no_mention, group_not_allowed, mention_all_blocked).

LarkChannelOptions.PolicyConfig policy = new LarkChannelOptions.PolicyConfig();
policy.setGroupAllowlist("oc_allowed_group");
policy.setDmMode("allowlist");
policy.setDmAllowlist("ou_allowed_user");
policy.setRequireMention(true);
policy.setRespondToMentionAll(false);

LarkChannel channel = LarkChannelFactory.createLarkChannel(
        LarkChannelOptions.newBuilder(appId, appSecret)
                .policy(policy)
                .build()
);

// Listen for rejections
channel.on("reject", new ChannelEventHandler<RejectEvent>() {
    @Override
    public void handle(RejectEvent event) {
        System.out.println(event.getReason().getValue());
    }
});

Use LarkChannel for conversational bot and Agent scenarios. It provides a unified entry point for event intake (WebSocket/Webhook), message normalization, safety policies, and messaging (replies, streaming, media).

To get started, create a channel using LarkChannelFactory, define an event handler for message events using NormalizedMessage, and call connect() to resolve the bot's identity.

LarkChannel channel = LarkChannelFactory.createLarkChannel(
        LarkChannelOptions.newBuilder(System.getenv("APP_ID"), System.getenv("APP_SECRET"))
                .transport("websocket")
                .build()
);

channel.on("message", new ChannelEventHandler<NormalizedMessage>() {
    @Override
    public void handle(NormalizedMessage message) {
        channel.send(
                message.getChatId(),
                SendInput.markdown("Received: " + message.getContent()),
                SendOptions.newBuilder().replyTo(message.getMessageId()).build()
        );
    }
});

BotIdentity identity = channel.connect().get();