#Lark integration

The Lark integration provides two independent connection types, plus a notification channel:

• Agent bot: bind a Sharkly Agent as a Lark bot and chat with it in direct messages, groups, and topics.
• Task assistant: one system assistant per Space. Bind it from the Lark integration page, then it can turn conversation context into Tasks in a group, and look up and update that Space's Tasks.
• Lark notifications: an optional delivery channel for Inbox events, delivered as Lark direct messages once your personal Lark account is linked.

The two connections are independent and can be used at the same time, but each must be configured separately. A task assistant is not an ordinary Agent: it does not appear in Agent lists, assignment pickers, or in-app chat.

Lark (the international edition of Feishu) and Feishu are two separate clouds with different hosts and non-interchangeable accounts. The Lark entry connects the Lark cloud; authorization, bots, notification channels, and task assistants are isolated per cloud and never route to the other side. If you authorize with an account from the Feishu cloud, the connection is not lost — the bot is listed on the Feishu entry instead.

#What do you need before connecting?

One Agent can be bound to only one Lark bot entry at a time. Agents already bound do not appear in the selectable list.

#Where do you start?

• After entering an Organization, open Integrations and go to the Lark page;
• Or open an Agent's detail page and configure it in the Integrations tab — this binds that Agent directly, with no need to pick it again.

#Lark task assistant: one entry per Space

The task assistant is a built-in assistant provided for each Space. It is not created from the "create Agent" form.

#What can it do?

• When @-mentioned in a Lark group, it turns the current discussion into a Task; the chat context it uses includes code blocks in the messages;
• Look up and update that Space's Tasks in Lark;
• Files sent by Agents return to the original Lark conversation.

It only works inside Lark. It cannot be chatted with in the app, does not appear in Agent lists or assignment pickers, and still shows as the executor on Tasks, comments, and activity it handled.

#How to bind it

1. Open Integrations and go to the Lark page.
2. In the Task assistant section, find a Space you have joined.
3. Choose Bind Lark.
4. Pick the Runtime that runs this Space's task assistant.
5. Scan the QR code in the same dialog to finish binding the Lark bot.

After binding, the task assistant uses the same settings structure as an Agent duplicate: each Space row's ··· menu offers Settings, Unbind Lark, and Remove assistant. Settings opens the same settings panel an Agent uses — computer and Runtime, default model, instructions, Skills, and more. Description and Instructions inherit the admin console's Task assistant template by default and sync automatically when the template changes; once edited on the assistant they are marked Overridden and keep their own value, and Reset to inherit returns them to the template. A shipped template (the built-in Lark task-creation instructions) is provided out of the box, and organization admins maintain it on the admin console's Task assistant template page; saving it updates every assistant still following the template.

To connect one of your own Agents to Lark, use the Agent bot below instead of the task assistant.

#Lark Agent bot: control a Sharkly Agent from Lark

The Agent bot connects one Sharkly Agent to Lark, so you can message the Agent directly in Lark and have it act in Sharkly without opening the app.

#What can it do?

• Ask, discuss, and give instructions to a Sharkly Agent in Lark;
• Create Sharkly Tasks and bind the current Lark topic to the Task;
• View and sync Task progress, including status, comments, and replies;
• Work with Tasks and other resources the Agent can access;
• Send text, rich text, images, and video attachments; files the Agent sends return to the original Lark conversation;
• Control each trigger separately: direct messages, group mentions, reaction triggers, and any-message triggers for selected groups.

What the Agent can actually reach depends on its permissions, the connection state, and the capabilities currently enabled.

#Connect the bot

1. Open Integrations and go to the Lark page (or start from the Agent's detail page).
2. Click Connect Agent and pick the Agent.
3. Wait for the QR code to be generated.
4. Scan it with Lark, or click Open link.
5. Finish creating and authorizing the bot in Lark.
6. Return to Sharkly and wait for the status to become connected.

Connection states:

QR codes and authorization links are one-time and expire. Click Retry afterwards to generate a fresh session.

#Using the Agent in Lark

#Direct messages, groups, and topics

By default the bot responds to direct messages and @ mentions in groups. Different topics keep their own context and do not mix just because they share a group.

Each trigger has its own switch in the Agent's Lark integration settings:

• Direct messages;
• Group mentions;
• Emoji reaction trigger;
• Any-message trigger: must target selected groups; it cannot apply to all groups.

#Stop the Agent with a reaction

While the Agent is working, add the stop reaction (a cross mark by default, changeable in the Agent's Lark integration settings) to the message that triggered the run — anyone in the conversation can do this. Lark removes the "working" marker from the message and confirms the stop; the Sharkly run is marked as stopped, the same as clicking Stop in Sharkly, and stopping in Sharkly syncs back to Lark.

#Where replies go

• In ordinary groups, a mention is answered in the group; a mention inside a topic is answered in that topic. Adding the reaction to a group message starts a new topic for the reply; reacting inside a topic answers in that topic.
• In topic-only groups, both mentions and reactions are answered under the corresponding topic. With any-message trigger enabled, the Agent replies in a newly created topic; ordinary messages in that topic do not keep triggering afterwards, and mentions still work. You can enable Keep triggering on new messages in the Lark topic.

#How replies are formatted

Sharkly picks the message type from the reply itself; the Agent needs no setting:

• Plain words are sent as a text message.
• Markdown such as bold, links, lists and quotes is sent as a rich-text message, so the formatting shows.
• Tables and code blocks are sent as a message card, with tables laid out in columns. A reply with more than 5 tables is sent as rich text, with the tables shown as code blocks.

Long replies are split into several messages.

#Context and files

When triggered, the Agent can use the messages accessible in the current conversation to understand the request — history, images, quoted content, message cards, and merged-forward records, plus member names — as allowed by the permissions Lark granted and the trigger settings. Images inside cards and forwarded records reach the Agent as attachments.

#Start a fresh session with /new

Use /new in an existing Lark chat, group, or topic to start a new Agent session. You can put the first prompt of the new session right after the command:

/new Summarize the release risks

/new only starts a new Agent session; it does not create a Sharkly Task.

#Create Tasks and sync progress

The bot does not turn every Lark message into a Task. When work needs tracking — status, assignee, comments, or acceptance criteria — ask the Agent to create a Task, and optionally bind the current topic. Once a topic is bound, messages in the topic and comments on the Task sync with each other; the corresponding switch in the Agent's trigger settings is Mirror the Lark topic's messages into the task's comments. Which comments are written back to Lark follows the live behavior.

An existing Task can be bound too: @ the bot in the topic with the Task's link. This does not depend on the switch above. The bot replies in the topic that the Task is linked, later messages sync to it, and earlier history is back-filled once. A message with only the @ and the link just binds and does not start an Agent reply; with anything else in it, the Agent replies as usual after binding. A Task in a private Space can only be bound by a member whose Lark account is linked and who can see the Task; otherwise the bot replies that it cannot bind it.

Bound topics follow these rules:

• Only topics bound to a Task sync. An ordinary group or direct message does not become Task comments just because the same bot is present;
• After a binding takes effect, messages in the topic sync without requiring every message to @ the bot. History from before the binding is back-filled once, in a limited way;
• Stopping the sync keeps the binding and existing comments. Resuming starts a new sync phase; messages from the paused window are not back-filled;
• One topic can be bound to several Tasks, and one Task to topics in several groups. Topic messages sync to every bound Task, and a comment one bound Task posts into the topic is synced to the other bound Tasks too. A message carrying several task links binds each of them, up to 5 Tasks per message; sending a link to an already-bound Task again makes the bot reply that the topic is already bound to that Task, without binding twice;
• Comments synced in from Lark do not fire another outbound Lark notification, avoiding a loop between Sharkly and Lark;
• Members linked to a Sharkly account are recorded by their member identity; historical or external senders that cannot be confirmed are kept as external participants.

The Task's details show the bound topic (for example "bound to a topic in a group"), where you can stop or resume syncing. Status changes can also be posted to the bound topic as a separate notification — do not confuse them with comment syncing.

#Lark connector: let an Agent access Lark resources

The connector works in the opposite direction of the Agent bot: the Agent bot lets you control a Sharkly Agent from Lark; the connector lets an Agent access Lark resources — documents, spreadsheets, and more — while it runs.

If an Agent needs Lark capabilities during its work, open Connectors on its detail page and pick Lark. The backend runs the authorization for you: confirm twice in your browser, and nothing is installed or signed in on any machine. New credentials bind automatically to the Agent that started the connection, and the first Task that needs Lark resources can use them. To reuse an existing credential, bind it instead of authorizing again — one credential can serve several Agents; to use a different Lark account, authorize a new one and keep the identities separate.

Connector credentials only give the Agent access to Lark resources. They do not create a Lark bot and do not enable Task previews or Lark notifications.

#Lark notifications

Lark notifications are an optional delivery channel for Inbox events. Before you can receive Lark direct messages:

1. The organization's Lark assistant must be connected (configured by the organization Owner or Admin with the organization's Lark app on open.larksuite.com);
2. Your personal Lark account must be linked.

One Lark app is used in exactly one place: it cannot serve an Agent bot and the organization assistant at the same time — across organizations included. Binding an app that is already in use elsewhere is rejected with a clear message telling you to rebind or create a new app; an existing app still shared by both shows a yellow banner at the top of the Lark integration page, naming the app, the bindings that share it, and how to resolve the conflict. Rebind one side to a new app and the banner disappears on its own (shared connections are not disabled — but each Lark message is delivered to only one of them, so the bot may miss messages until then).

Link your account from Settings → Notifications → Lark, Settings → Third-party accounts, or My Lark account on the Lark integration page. Notifications are grouped into categories — assignments, status changes, comments and replies, mentions, and Agent activity. Turning a group off only stops the corresponding Lark messages; the Inbox still records those events. Turning a group off in the Inbox stops both. Only events produced after enabling are delivered; the backlog is not replayed.

If the assistant is temporarily unavailable, your switches are kept and take effect again after reconnecting. Disconnecting the organization's Lark app stops Lark notifications immediately.

The same organization Lark app also renders Task link previews: paste a Sharkly Task link into Lark and a preview card appears, opening the Task and showing its creator, displaying each reader only what they are allowed to see. Previews in public Spaces render without a personal Lark account; private Spaces require the reader's personal Lark account to be linked. For previews to work, the Lark app needs a released production version, long-connection callbacks, the url.preview.get subscription, and registered URL rules — one wildcard path such as app.sharkly.ai/** is enough. Members outside the app's availability scope get nothing: Lark never asks Sharkly for them.

#Manage and disconnect

The Lark page lists the Organization's bound bots. You can:

• See which Agent each Lark entry is bound to;
• Connect additional Agents that are not bound yet;
• Refresh binding states;
• Disconnect bindings you no longer need.

To control whether direct messages, group mentions, reactions, or any-message triggers wake the Agent, adjust the corresponding Agent's integration settings.

After disconnecting, the Lark entry stops forwarding new messages to the Agent; existing Sharkly sessions and history are not deleted. To reconnect, complete the QR authorization again.

#FAQ

#Task assistant or Agent bot — which one do I need?

• Task assistant: one system assistant per Space that turns discussions into that Space's Tasks;
• Agent bot: connects an Agent you created to Lark, so you can message Sharkly from Lark and have it create Tasks, sync progress, or work with Sharkly resources;
• Lark connector: from the Sharkly side, lets an Agent access Lark documents and spreadsheets while it runs.

The task assistant does not appear in Agent lists. To connect your own Agent, use the Agent bot.

#Why is there no Agent to select?

Either no Agent exists yet, or every Agent you can use is already bound to a Lark bot entry. Create a new Agent, or disconnect a binding you no longer use. One Agent can hold only one Lark bot entry at a time.

#Why did the QR code stop working?

Each connection uses a one-time authorization session. If the code expires, authorization was canceled in Lark, or the session is lost, click Retry to generate a new one.

#Still "waiting for authorization" after scanning?

Make sure you finished the final creation and authorization steps in Lark, not just opened the page. Sharkly updates the connection state automatically a moment later.

#Do Lark messages automatically become Sharkly Tasks?

No. Ordinary messages go to the Agent's external session. Work that needs tracking should be created as a Task in Sharkly or via the Agent bot; only topics bound to a Task — at Task creation, or by @-ing the bot with the Task's link — sync later messages to the Task's comments.