Feishu / Lark | Sophon

Sophon connects to Feishu (and its international edition, Lark) using the Feishu Open Platform Bot API. Inbound messages arrive over an event webhook, while Sophon sends replies through the REST messaging API, authenticating with a tenant access token derived from your app credentials. You'll create a custom app, grant it messaging permissions, and paste two credentials into Sophon.

Prerequisites

A Feishu or Lark account with permission to create custom apps
Access to the Feishu Open Platform developer console
A publicly reachable URL for your Sophon instance so Feishu can deliver events to the webhook endpoint

Step-by-Step Setup

1. Create a Custom App

Sign in to the Feishu Open Platform
Open Developer Console and click Create Custom App
Give the app a name (e.g., "Sophon Assistant") and an icon
Open the app's Credentials & Basic Info page and copy the App ID and App Secret

2. Enable the Bot and Permissions

Under Add Features, enable the Bot capability
In Permissions & Scopes, grant the scopes needed to read and send instant messages (for example, sending messages as the app and receiving message events)
Publish a version of the app so the permissions take effect

3. Configure the Event Subscription

Open Event Subscription for your app
Set the Request URL to your Sophon webhook endpoint:
```
https://<your-sophon-host>/webhooks/feishu
```
Feishu sends a one-time verification request to that URL. Sophon answers the challenge automatically, so the URL is verified as soon as your instance is reachable.
Subscribe to the message-received event so Sophon is notified when users message the bot. The adapter handles the im.message.receive_v1 event.

4. Configure in Sophon Dashboard

Go to Channels and click Add Channel
Select Feishu / Lark
Paste the App ID
Paste the App Secret
Click Test Connection — Sophon requests a tenant access token to confirm the credentials work
Click Activate

5. Test It

Open a chat with your app in Feishu or Lark and send a text message. Sophon should respond in the same chat.

Feishu delivers inbound events over a webhook, so your Sophon instance must be reachable from the public internet at /webhooks/feishu. The webhook path is exempt from per-IP rate limiting. See Sophon Node for deployment and reverse-proxy guidance.

Configuration Reference

Field	Type	Required	Description
`appId`	text	Yes	App ID from the Feishu Open Platform (Credentials & Basic Info)
`appSecret`	secret	Yes	App Secret from the Feishu Open Platform; used to obtain a tenant access token

channels.json Example

{
  "id": "feishu-bot",
  "type": "feishu",
  "name": "Sophon Feishu Bot",
  "enabled": true,
  "config": {
    "appId": "cli_xxxxxxxxxxxxxxxx",
    "appSecret": "<encrypted>"
  },
  "routing": {
    "agentId": "default",
    "dmBehavior": "main-session",
    "groupBehavior": "mention-only"
  },
  "status": "connected"
}

Media Support

The Feishu adapter is text-first. Inbound handling is limited to text messages, and outbound messages are sent as Feishu text messages. Images sent from Sophon are delivered as their caption text rather than as an uploaded file.

Type	Inbound	Outbound
Text	Yes	Yes
Images	No	Caption text only
Audio	No	No
Video	No	No
Documents	No	No

Troubleshooting

Request URL verification fails — Feishu must be able to reach https://<your-sophon-host>/webhooks/feishu. Confirm the instance is publicly reachable, uses a valid TLS certificate, and that no proxy rewrites or blocks the path before retrying verification in the console.
Test Connection fails — The App ID or App Secret is wrong. Re-copy both values from Credentials & Basic Info and make sure the published app version is active. Sophon validates by requesting a tenant access token, so invalid credentials surface here immediately.
Bot receives no messages — Ensure the Bot capability is enabled, the message-received event is subscribed, and the app has been published with the required messaging scopes. Only im.message.receive_v1 text events are processed.
"Feishu requires a chat ID (starting with 'oc_')" — Outbound recipients must be Feishu chat IDs that begin with oc_. This is set automatically for replies; it only appears when targeting a chat manually.
Sends fail silently — Check the Sophon logs for a "Feishu send failed" warning with the platform status and error, which usually points to an expired token, missing scope, or an invalid receive_id.

Feishu / LarkNEW