> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synti.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Lark / Feishu

> Connect a Lark or Feishu custom app to Synti for direct and group chats with interactive cards and rich text.

Lark (international) and Feishu (China) are two regions of the same platform. To connect Synti you create a custom app on the Open Platform, grant it a few messaging permissions, and paste its credentials into Synti. Unlike the other integrations, Lark/Feishu can also respond in group chats when the bot is @mentioned.

<Info>
  Pick your region up front — a bot belongs to **Lark** or **Feishu**, not both.

  * Lark (international): `open.larksuite.com`
  * Feishu (China): `open.feishu.cn`
</Info>

## Create the app

The Open Platform offers a quick path that pre-configures everything, and a manual path if you'd rather set it up yourself.

<Tabs>
  <Tab title="Quick create (recommended)">
    On the app-creation page, look for the **"Built for agents. Ready to connect"** banner. It pre-configures the required permissions and event settings so you can skip the manual toggles below and go straight to pasting credentials into Synti.
  </Tab>

  <Tab title="Manual setup">
    <Steps>
      <Step title="Create a custom app">
        In the Developer Console, create a custom app and give it a name and icon.
      </Step>

      <Step title="Copy the credentials">
        Copy the **App ID** (starts with `cli_`) and the **App Secret** (a 32-character string).
      </Step>

      <Step title="Enable scopes">
        Under **Permissions & Scopes**, enable the required scopes (see below).
      </Step>

      <Step title="Configure events">
        Set up the event subscription (see below).
      </Step>

      <Step title="Publish">
        Publish the app version, or keep the tenant in dev mode, so it can receive messages.
      </Step>
    </Steps>
  </Tab>
</Tabs>

### Required scopes

Enable all three, or events and sends will silently fail:

| Scope                     | Purpose                          |
| ------------------------- | -------------------------------- |
| `im:message`              | Receive message events.          |
| `im:message.group_at_msg` | Handle @mentions in group chats. |
| `im:message:send_as_bot`  | Send messages as the bot.        |

### Events

* **Delivery mode:** Long connection (WebSocket) — not webhooks.
* **Event subscription:** `im.message.receive_v1`.
* **Encryption key:** leave blank. Long-connection mode doesn't encrypt payloads.
* **Publishing:** the app version must be published, or the tenant in dev mode, before messages arrive.

## Connect it in Synti

<Steps>
  <Step title="Open the Lark / Feishu tile">
    Go to **Settings → Messaging** and open the Lark / Feishu tile.
  </Step>

  <Step title="Select your region">
    Choose Lark or Feishu to match where you created the app.
  </Step>

  <Step title="Paste credentials">
    Enter the App ID and App Secret.
  </Step>

  <Step title="Test and save">
    Click **Test** — Synti exchanges the credentials for a tenant access token — then **Save**. The credentials go into the workspace keychain and the WebSocket connection starts.
  </Step>
</Steps>

## Pair your first chat

<Steps>
  <Step title="DM the bot">
    Open a direct message with the bot in Lark or Feishu.
  </Step>

  <Step title="Request a code">
    Send `/pair` in the chat.
  </Step>

  <Step title="Copy the code from Synti">
    In Synti, open the session menu → **Pair with Messaging → Lark**, and copy the six-digit code.
  </Step>

  <Step title="Redeem it">
    Send the pairing command with that code back in Lark, then send any message to begin.
  </Step>
</Steps>

## Group chats

In groups, the bot only receives messages where it's **@mentioned** — a consequence of the `im:message.group_at_msg` scope. Without the mention, the server never delivers the event. This scope can't be widened without enterprise approvals.

## Rich text and cards

Lark/Feishu renders more formatting natively than the other platforms, though a few Markdown constructs fall back to plain text.

| Rendered natively                     | Falls back to plain text    |
| ------------------------------------- | --------------------------- |
| Bold, italic, strikethrough           | Headers                     |
| Clickable links                       | Bullet and numbered lists   |
| Fenced code blocks with language tags | Tables (space-padded)       |
| Paragraph breaks                      | Inline code (shown as bold) |

When the agent needs mid-flow approval, it posts an **interactive card** with native action buttons. A few limits apply:

* Up to 10 buttons per card.
* Button labels are truncated at 30 characters.
* The card clears itself after you act on it.
* Draft apps display cards but their button callbacks won't fire — publish the app to make buttons work.

## Attachments

* **Inbound** (DMs and group @mentions): images and files download server-side into the session's working directory.
* **Outbound:** the agent can send images and documents; any caption follows as a separate text message.
* **Limits:** 20 MB per attachment. Audio, video, and stickers aren't supported and are logged as dropped.

## Other limits

* **One region per bot.** A bot lives in Lark or Feishu, never both.
* **Edit window.** Editing a message older than 24 hours silently fails — a Lark API limit.

## Troubleshooting

| Problem                 | Fix                                                                                                                         |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Bot ignores messages    | Confirm `im:message` is enabled and `im.message.receive_v1` is subscribed, and that delivery mode is **Long connection**.   |
| Test connection fails   | The App Secret may have been regenerated, or the tenant switched — old credentials get revoked. Re-copy the current secret. |
| Group messages ignored  | Enable `im:message.group_at_msg` **and** make sure the message @mentions the bot.                                           |
| Card buttons do nothing | Publish the app, or put the tenant in dev mode. Draft apps can't fire card callbacks.                                       |
| File too large          | The adapter caps attachments at 20 MB. Compress or split the file.                                                          |

<Note>
  Messaging logs are written to `~/.synti/logs/messaging-gateway.log`. Filter for the `lark-adapter` component to isolate Lark/Feishu activity.
</Note>