Feishu Image Sender 飞书发图指南

intent

send text messages, images, and files to feishu users and chat groups using the bot api. use this skill when a user needs to push content into feishu im via automated workflows, whether that's a single image to a group chat, a captioned file to a user, or bulk notifications. activate on triggers like 飞书发图, 发送图片, 飞书消息, im:resource, image_key, 飞书附件, 飞书机器人发消息.

inputs

feishu bot credentials and permissions

• tenant_access_token: bot app token (not webhook custom bot). expires every ~2 hours. openClaw auto-refreshes on each call.
• bot_app_id and bot_app_secret: required to obtain tenant_access_token if manual refresh needed.
• environment variable: FEISHU_TENANT_ACCESS_TOKEN (preferred) or passed inline.

required oauth scopes (all currently granted on openClaw installation)

• im:resource: upload images and files to im, receive file_key and image_key in response.
• im:message: send messages containing media attachments.
• im:message:send_as_bot: identify the sender as the bot, not a user.

target identifiers (exactly one required per message)

• user_id: feishu user id (e.g., ou_abc123). sends dm to that user.
• chat_id: feishu group chat id (e.g., oc_abc123). sends to the group.
• email: user email address. feishu will resolve to user_id internally.

content payload (at least one required)

• message: plain text string. required for text-only sends; optional for image/file sends (acts as caption).
• filePath: absolute local file path to image or file. e.g., /tmp/report.jpg. mutually exclusive with media (use one or the other).
• media: alternative to filePath, same behavior. e.g., /var/uploads/chart.png.
• file_type: mime type if sending file (e.g., image/jpeg, application/pdf). defaults to inferred from extension.

external connection

• feishu openapi endpoint: https://open.feishu.cn/open-apis/. used for image upload and message send. requires network access and valid tenant_access_token.

procedure

1. validate inputs. check that target (user_id or chat_id or email) is present and non-empty. check that message or filePath is present. if either missing, raise error with required fields listed. if both filePath and media supplied, raise error (mutually exclusive).

2. obtain token. retrieve tenant_access_token from environment variable FEISHU_TENANT_ACCESS_TOKEN or accept it as parameter. if token missing, attempt auto-refresh using bot_app_id and bot_app_secret (if provided). if no token and no refresh credentials, fail with message "no feishu credentials found".

3. text-only send (if no image/file). if message supplied and filePath/media absent, call message(action=send, channel=feishu, target=<user_id_or_chat_id>, message="<text>"). openClaw tool handles the rest. log success or propagate error from feishu api.

4. prepare image/file upload (if filePath or media provided). resolve the file path to an absolute path on disk. verify file exists and is readable. determine mime type from file extension or accept as parameter. if file does not exist, raise error with path shown.

5. upload to feishu. post file to https://open.feishu.cn/open-apis/im/v1/images (for images) or /im/v1/files (for generic files). include headers: Authorization: Bearer <tenant_access_token>, Content-Type: multipart/form-data. include form fields: image_type=message (critical, not avatar), and file binary in field image. send request and capture response.

6. parse upload response. extract image_key from response json. if response contains error code, check error code against decision table. if image_key is null or empty string, treat as silent failure (token likely expired). log full response for debugging.

7. send message with media. call message(action=send, channel=feishu, target=<chat_id>, filePath="<path>", message="<optional_caption>") or use image_key directly in raw api call if tool does not expose it. if caption provided, include as message field in the feishu message payload. log success with target and image_key.

8. confirm delivery. feishu api returns message_id on success (http 200). confirm that message_id is non-empty string. if http error or missing message_id, treat as failure and log error details. do not retry silently (let caller decide).

decision points

if text only (no image or file)

• send via message tool with action=send, channel=feishu. no upload step needed.

if image or file to be sent

• upload first via /im/v1/images or /im/v1/files. capture image_key or file_key. then send message with that key. never paste raw file path into message text.

if token expired or missing

• if tenant_access_token is absent and no bot_app_id/secret provided, fail immediately with "credentials required" error.
• if token is present but api returns error code 99991400 (token expired), attempt one auto-refresh (if credentials available). if refresh succeeds, retry the upload. if refresh fails or no credentials, fail with "token expired, manual refresh required".

if error code 99991663 (invalid image_key)

• indicates image_key returned from upload was malformed or token used for upload differs from token used for send. check that same tenant_access_token is used for both steps. if using auto-refresh, confirm refresh happened between steps. log error and fail.

if webhook custom bot detected instead of bot app

• feishu webhook bots cannot upload images via api (no access_token). user must switch to Bot App (自建应用) or encode image as base64 in message (not recommended). log warning with setup instructions.

if file not found at provided path

• raise error immediately. do not attempt to create or infer alternate path.

if network timeout on upload (>30s)

• log warning and fail. do not retry silently. caller may retry with backoff.

if empty result set (user_id does not exist in feishu)

• feishu api will return error. log and propagate to caller. do not assume silent success.

output contract

success case

• http status 200 from feishu /im/v1/messages endpoint.
• response json contains non-empty message_id field (e.g., "message_id": "om_abc123def456").
• if image was sent, response also includes image_key or file_key in previous upload response.
• output is written to openClaw message log with timestamp, target, message preview, and image_key (if applicable).

failure case

• http error (4xx, 5xx) from feishu api. response json contains code and msg fields (e.g., "code": 99991400, "msg": "token expired").
• output is written to openClaw error log with full http status, error code, error message, and request details (target, file path if applicable).

file location

• no local files created. all state is in feishu servers and openClaw logs. if caller needs evidence, message_id is the proof of delivery.

outcome signal

• user sees the message or image appear in feishu within 1-2 seconds of skill execution.
• openClaw logs show "feishu send success" with message_id.
• if failure, openClaw logs show error code and message (e.g., "token expired", "file not found", "chat_id invalid").
• user can click the message in feishu to verify content (text, image caption, etc.) matches what was sent.