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

# End-to-end: Connect an expert to Feishu

> The full path from onboarding to reading and writing Feishu docs, and the two authorizations people conflate

This connects an expert to Feishu (Lark) so your team can use it in the chat window they already live in, and so it can read and write your Feishu documents and Bitables.

The thing that usually blocks people isn't configuration — it's that **there are two separate authorizations**. Onboarding lets the bot send and receive messages; `/auth` is what lets it touch your documents. Many people finish onboarding, assume they're done, hit a permission error when reading a doc, and then spend an hour re-checking the onboarding config — which was fine all along. This guide draws that line clearly.

## What you'll get

* A working bot in Feishu, usable in both direct messages and groups
* After authorization, the ability to read and write Feishu docs, Bitables, and wikis **that you have access to**
* The ability to create a scheduled task from a Feishu message, with results delivered back to the same conversation

## The key distinction: two authorizations

|               | App authorization (onboarding)         | User authorization (`/auth`)                              |
| ------------- | -------------------------------------- | --------------------------------------------------------- |
| Answers       | Can this bot send and receive messages | Can this bot access **my** resources on my behalf         |
| Configured by | A Feishu admin                         | Each individual user                                      |
| Scope         | The whole organization                 | Only the person who ran `/auth`                           |
| If missing    | The bot doesn't respond at all         | Chat works, document access fails with a permission error |
| Lifetime      | Long-lived                             | Expires; re-run `/auth`                                   |

<Warning>
  User authorization is **per person**. Everything working for you says nothing about your colleagues — each of them must run `/auth` themselves. This is the single most common "but it works for me" confusion.
</Warning>

## Part 1: Onboarding

### Option A: QR code (recommended)

<Steps>
  <Step title="Open channel setup">
    In the expert's Studio, go to channel setup and pick Feishu.
  </Step>

  <Step title="Scan the code">
    Scan with a **Feishu admin account**. Regular member accounts can't complete this — that's the first sticking point.
  </Step>

  <Step title="Confirm authorization">
    Confirming creates the Feishu app and configures permissions and callbacks automatically.
  </Step>

  <Step title="Find the bot in Feishu">
    Search for the bot by name and send "hello" to test.
  </Step>
</Steps>

### Option B: Manual configuration

Use this when you need tight permission scoping, or want to reuse an existing Feishu app:

<Steps>
  <Step title="Create a custom app">
    On the [Feishu Open Platform](https://open.feishu.cn).
  </Step>

  <Step title="Enable the bot capability">
    Under the "Bot" capability.
  </Step>

  <Step title="Configure event subscription">
    Copy the callback URL from Profy's channel panel. **A wrong callback URL is the number one cause of "the bot doesn't reply"** — hit verify on the Feishu side after saving.
  </Step>

  <Step title="Add permissions">
    Message send/receive at minimum; add contacts, docs, and Bitable scopes if you need them.
  </Step>

  <Step title="Fill in credentials">
    Put the App ID and App Secret into Profy's channel panel.
  </Step>

  <Step title="Publish and wait for review">
    Custom apps must publish a version and pass review. **The bot won't respond until it does** — that's the second sticking point, and it looks exactly like a misconfiguration.
  </Step>
</Steps>

### Verify onboarding

Send "hello" to the bot in Feishu. A reply means onboarding worked. If nothing comes back, check in this order: is the app published and approved → is the callback URL correct → in a group, did you @ the bot.

## Part 2: User authorization

### Run /auth

<Steps>
  <Step title="Send the command">
    Send `/auth` in your Feishu conversation with the bot.
  </Step>

  <Step title="Open the link">
    The bot replies with an authorization link.
  </Step>

  <Step title="Confirm the scope">
    Approve the requested scopes on the Feishu OAuth page.
  </Step>

  <Step title="Back to the conversation">
    Authorization is live; you can now have it read documents.
  </Step>
</Steps>

### Verify authorization

Find a Feishu doc you have access to and send the link:

```text theme={null}
Read this document and summarize it in three sentences:
https://xxx.feishu.cn/docx/xxxxxxxx
```

Getting the content back means authorization worked. A permission error means it never took effect or has expired — run `/auth` again.

<Note>
  After authorization the expert's reach **equals your own** — it cannot see documents you can't see. Authorizing it does not grant access beyond your own permissions.
</Note>

## Part 3: What it can do

Three capability groups become available. Note these tools exist **only in Feishu conversations** — they don't appear when you talk to the same expert on the web.

### Documents

| Capability | Notes                                                        |
| ---------- | ------------------------------------------------------------ |
| Read       | Returns the document as plain text                           |
| Create     | New document, optionally in a specific folder                |
| Append     | Adds to the end                                              |
| Overwrite  | **Clears first, then writes** — the original content is gone |

<Warning>
  Overwrite is clear-then-write, not a smart merge. Telling it to "update section three" of a document someone maintains can leave you with a document containing only section three. To change part of a document, explicitly say "append at the end," or have it read the doc, agree the new full text with you, and only then write.
</Warning>

### Bitables

Querying and modifying records is supported, along with structural operations. The typical use is writing conversation output straight into a table:

```text theme={null}
Write these 8 customer feedback items into this Bitable, one row each:
https://xxx.feishu.cn/base/xxxxxxxx

Field mapping: feedback text → "Description", urgency → "Priority", source → "Channel"
Read the header row first and confirm the field names match before writing.
```

Include the "read the header first" instruction. When field names don't match, the default behavior may be to skip that column, leaving you with a batch of records missing fields.

### Creating scheduled tasks from Feishu

An easily missed capability: you can create **Profy** scheduled tasks (not Feishu calendar events) right from chat:

```text theme={null}
Send me a summary of yesterday's customer feedback every morning at 9
```

The task records Feishu as its source, so results are pushed back into that Feishu conversation. The task itself is visible and manageable on Profy's web console. Recurrence is still limited to `no-repeat` / `daily` / `weekly` / `monthly` — see [Daily briefing](/en/documentation/guides/daily-briefing).

## Behavior in groups

* The bot only responds when **@-mentioned**; it doesn't chime in on every message
* Each member's `/auth` is independent — A being authorized says nothing about B
* Replies arrive as multiple bubbles, with status notices while tools run
* Long replies are split automatically

## Boundaries and failure modes

| Symptom                                      | Cause                                                                  | Fix                                                         |
| -------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------- |
| Bot never responds                           | App unpublished/unapproved, wrong callback, not @-mentioned in a group | Work through the onboarding verification order              |
| Chat works but docs return permission errors | No user authorization, or it expired                                   | Send `/auth` again                                          |
| Works for me, not for a colleague            | User authorization is per person                                       | Have them run `/auth`                                       |
| Can't read a specific document               | You personally don't have access to it                                 | Get access in Feishu first                                  |
| Document content was wiped                   | Overwrite was used instead of append                                   | Restore from Feishu version history; say "append" next time |
| Bitable rows missing fields                  | Field names didn't match and were skipped                              | Read the header first, confirm names, then write            |
| Feishu tools missing on the web              | These tools only activate in the Feishu channel                        | Do it from the Feishu conversation                          |
| Authorization link errors out                | The link is time-limited                                               | Send `/auth` for a fresh one                                |

## Related pages

<CardGroup cols={2}>
  <Card title="Feishu channel" icon="comment" href="/en/documentation/channels/feishu">
    Full channel configuration reference
  </Card>

  <Card title="Feishu tools" icon="screwdriver-wrench" href="/en/documentation/plugins/feishu-tools">
    Every action and parameter of the three tools
  </Card>

  <Card title="Knowledge connectors" icon="book" href="/en/documentation/capabilities/knowledge-connectors">
    Another path to Feishu content
  </Card>

  <Card title="Channels overview" icon="layer-group" href="/en/documentation/channels/overview">
    Other IM platforms
  </Card>
</CardGroup>