Feishu Openapi Skill

Core Workflow

1. Use the fixed link command by default:

   • command -v feishu-openapi-cli
   • If missing, create it: uxc link feishu-openapi-cli https://open.feishu.cn/open-apis --schema-url https://raw.githubusercontent.com/holon-run/uxc/main/skills/feishu-openapi-skill/references/feishu-im.openapi.json
   • feishu-openapi-cli -h

2. Inspect operation schema first:

   • feishu-openapi-cli get:/bot/v3/info -h
   • feishu-openapi-cli get:/im/v1/chats -h
   • feishu-openapi-cli post:/im/v1/images -h
   • feishu-openapi-cli post:/im/v1/files -h
   • feishu-openapi-cli post:/im/v1/messages -h
   • feishu-openapi-cli get:/im/v1/messages -h

3. Prefer read/setup validation before writes:

   • feishu-openapi-cli get:/bot/v3/info
   • feishu-openapi-cli get:/im/v1/chats page_size=20
   • feishu-openapi-cli get:/im/v1/chats/{chat_id} chat_id=oc_xxx
   • feishu-openapi-cli get:/contact/v3/users/{user_id} user_id=ou_xxx user_id_type=open_id

4. Execute with key/value or positional JSON:

   • key/value: feishu-openapi-cli get:/im/v1/messages container_id_type=chat container_id=oc_xxx page_size=20
   • multipart upload: feishu-openapi-cli post:/im/v1/images image_type=message image=/tmp/example.png
   • positional JSON: feishu-openapi-cli post:/im/v1/messages receive_id_type=chat_id '{"receive_id":"oc_xxx","msg_type":"text","content":"{\"text\":\"Hello from UXC\"}"}'

5. For inbound message intake, use uxc subscribe directly:

   • uxc subscribe start https://open.feishu.cn/open-apis --transport feishu-long-connection --auth feishu-tenant --sink file:$HOME/.uxc/subscriptions/feishu.ndjson
   • send a bot-visible message, then inspect the sink for header.event_type = "im.message.receive_v1"

Operation Groups

Bot Identity

• get:/bot/v3/info

Chat Reads

• get:/im/v1/chats
• get:/im/v1/chats/{chat_id}
• get:/im/v1/chats/{chat_id}/members

Message Reads / Writes

• get:/im/v1/messages
• get:/im/v1/messages/{message_id}
• post:/im/v1/messages
• post:/im/v1/messages/{message_id}/reply

Uploads

• post:/im/v1/images
• post:/im/v1/files

User Lookup

• get:/contact/v3/users/{user_id}
• post:/contact/v3/users/batch_get_id

Guardrails

• Keep automation on the JSON output envelope; do not use --text.
• Parse stable fields first: ok, kind, protocol, data, error.
• Prefer uxc auth bootstrap over manual token management. Manual tenant_access_token setup is still supported as a fallback.
• get:/bot/v3/info requires a tenant token for an app with bot capability enabled, but does not require additional API scopes.
• feishu-long-connection requires the app credential fields app_id and app_secret; a plain bearer-only credential is not enough for event intake.
• post:/im/v1/images and post:/im/v1/files use multipart/form-data. File fields must be local path strings; help output marks them as multipart file fields.
• post:/im/v1/messages requires the receive_id_type query parameter and the body content field is a JSON-encoded string, not a nested JSON object.
• Upload first, then send by returned key:
  • image sends use msg_type=image with content='{\"image_key\":\"img_xxx\"}'
  • file sends use msg_type=file with content='{\"file_key\":\"file_xxx\"}'
• post:/im/v1/messages/{message_id}/reply is for explicit replies to an existing message. Treat it as a high-risk write.
• History reads only return chats and messages visible to the bot/app configuration. Auth success does not imply access to every chat.
• Long-connection message intake is validated for Feishu bot chats; webhook-style callbacks and non-IM products are still out of scope.
• feishu-openapi-cli <operation> ... is equivalent to uxc https://open.feishu.cn/open-apis --schema-url <feishu_openapi_schema> <operation> ....

References

• Usage patterns: references/usage-patterns.md
• Curated OpenAPI schema: references/feishu-im.openapi.json
• Feishu Open Platform docs: https://open.feishu.cn/document/
• Lark Open Platform docs: https://open.larksuite.com/document/