UXC

One CLI for tools across protocols.

Feishu / Lark IM Skill

Use this skill to run Feishu or Lark IM operations through uxc + OpenAPI.

Reuse the uxc skill for shared execution, auth, and error-handling guidance.

Prerequisites

Scope

This skill covers an IM-focused request/response surface:

This skill does not cover:

Subscribe Status

Feishu and Lark expose event-delivery models beyond plain request/response APIs, including long-connection event delivery in the platform ecosystem.

Current uxc subscribe status:

Important runtime notes:

Endpoint Choice

This schema works against either Feishu or Lark Open Platform base URLs:

The fixed link example below uses Feishu. For Lark, use the same schema URL against the Lark base host.

Authentication

Feishu and Lark service-side APIs use Authorization: Bearer <tenant_access_token> for these operations.

Preferred setup is to store app_id + app_secret as credential fields and let uxc auth bootstrap fetch and refresh the short-lived tenant token automatically.

Feishu bootstrap-managed setup:

uxc auth credential set feishu-tenant \
  --auth-type bearer \
  --field app_id=env:FEISHU_APP_ID \
  --field app_secret=env:FEISHU_APP_SECRET

uxc auth bootstrap set feishu-tenant \
  --token-endpoint https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
  --header 'Content-Type=application/json; charset=utf-8' \
  --request-json '{"app_id":"{{field:app_id}}","app_secret":"{{field:app_secret}}"}' \
  --access-token-pointer /tenant_access_token \
  --expires-in-pointer /expire \
  --success-code-pointer /code \
  --success-code-value 0

uxc auth binding add \
  --id feishu-tenant \
  --host open.feishu.cn \
  --path-prefix /open-apis \
  --scheme https \
  --credential feishu-tenant \
  --priority 100

For Lark, use the same bootstrap shape against the Lark host and bind the credential to open.larksuite.com.

To use long-connection subscribe, the credential still needs app_id and app_secret fields because the transport opens its own temporary event URL outside the normal bearer-token request path.

Manual fallback if you already have a tenant token:

curl -sS https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{"app_id":"cli_xxx","app_secret":"xxxx"}'

Lark uses the same path shape on the Lark host:

curl -sS https://open.larksuite.com/open-apis/auth/v3/tenant_access_token/internal \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{"app_id":"cli_xxx","app_secret":"xxxx"}'

Configure one bearer credential and bind it to the Feishu API host:

uxc auth credential set feishu-tenant \
  --auth-type bearer \
  --secret-env FEISHU_TENANT_ACCESS_TOKEN

uxc auth binding add \
  --id feishu-tenant \
  --host open.feishu.cn \
  --path-prefix /open-apis \
  --scheme https \
  --credential feishu-tenant \
  --priority 100

For Lark, create the same binding against open.larksuite.com:

uxc auth binding add \
  --id lark-tenant \
  --host open.larksuite.com \
  --path-prefix /open-apis \
  --scheme https \
  --credential feishu-tenant \
  --priority 100

Inspect or pre-warm bootstrap state when auth looks wrong:

uxc auth bootstrap info feishu-tenant
uxc auth bootstrap refresh feishu-tenant

Validate the active binding when auth looks wrong:

uxc auth binding match https://open.feishu.cn/open-apis

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:/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:/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

Chat Reads

Message Reads / Writes

Uploads

User Lookup

Guardrails

References