feishu-img-send-mx

send images directly to feishu users via open platform api. images render inline, not as file attachments. use this when you need to push screenshots, qr codes, or other images into a feishu chat without going through the openclaw plugin layer.

intent

this skill uploads an image to feishu's servers and sends it as an embedded message to a user, group, or chat. the image renders natively in feishu clients instead of appearing as a downloadable file. deploy this when you're generating screenshots, qr codes, or other visual assets on the fly and need to get them in front of a feishu user without friction. the skill bypasses openclaw's file attachment constraints by hitting the feishu api directly.

inputs

feishu app credentials (required):

• APP_ID: feishu app id. set via env var FEISHU_APP_ID or pass inline.
• APP_SECRET: feishu app secret. set via env var FEISHU_APP_SECRET or pass inline. treat as sensitive; never log it.
• source: register an app at https://open.feishu.cn/app, grab credentials from the app settings page.

image file (required):

• IMAGE_PATH: absolute or relative path to the image file on disk.
• supported formats: jpg, png, gif, webp, bmp, heic.
• max size: 30 mb per file.
• validation: file must exist and be readable before upload attempt.

recipient identifier (required):

• RECEIVE_ID: the feishu user, group, or chat id.
• RECEIVE_ID_TYPE: one of open_id, user_id, chat_id, union_id. must match the type of RECEIVE_ID.

network requirements:

• outbound https to open.feishu.cn must be open (firewall, vpc, proxy rules).
• dns resolution for open.feishu.cn must succeed.
• no proxy authentication required unless your network enforces it.

procedure

1. fetch tenant access token

   • input: APP_ID, APP_SECRET.
   • method: post to https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal with json body {"app_id":"<APP_ID>","app_secret":"<APP_SECRET>"}.
   • output: json response containing tenant_access_token (string) and expire (seconds, typically 3339 = ~55 min). store tenant_access_token in memory for steps 2 and 3.
   • error handling: if response code is non-zero or token field is missing, halt and return error to caller.

2. upload image to feishu

   • input: IMAGE_PATH, tenant_access_token from step 1.
   • method: post multipart form to https://open.feishu.cn/open-apis/im/v1/images. include headers: Authorization: Bearer <tenant_access_token>, Content-Type: multipart/form-data. form fields: image_type=message, image=<binary file content>.
   • validation before upload: confirm file at IMAGE_PATH exists, is readable, and is <= 30 mb. confirm mime type matches one of the supported formats. if validation fails, return descriptive error without attempting upload.
   • output: json response with data.image_key (string, e.g., img_v3_xxx). store image_key for step 3.
   • error handling: if response code is non-zero, log full response and return error. common issues: invalid token (re-fetch), file too large (check size), unsupported format (validate before upload), network timeout (retry up to 2 times with 1 second backoff).

3. send image message

   • input: tenant_access_token from step 1, image_key from step 2, RECEIVE_ID, RECEIVE_ID_TYPE.
   • method: post to https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=<RECEIVE_ID_TYPE>. headers: Authorization: Bearer <tenant_access_token>, Content-Type: application/json. json body: {"receive_id":"<RECEIVE_ID>","msg_type":"image","content":"{\"image_key\":\"<image_key>\"}"}.
   • output: json response with data.message_id (string, e.g., om_xxx). message_id confirms delivery to feishu backend.
   • error handling: if response code is non-zero, log error. common issues: invalid receive_id (user/chat does not exist), receive_id_type mismatch (e.g., passing user_id but type is open_id), image_key expired (re-upload if > 1 hour old), network timeout (retry up to 2 times).

decision points

if credentials are missing:

• if APP_ID or APP_SECRET env vars are not set and no inline credentials provided, return error stating "feishu app credentials required: set FEISHU_APP_ID and FEISHU_APP_SECRET or pass inline". do not attempt api call.

if image file does not exist:

• return error immediately: " not found or not readable". do not proceed to upload.

if image file exceeds 30 mb:

• return error: "image exceeds 30 mb limit. file size: bytes". do not upload.

if image format is unsupported:

• parse file extension and mime type. if not in [jpg, png, gif, webp, bmp, heic], return error: "unsupported image format. supported: jpg, png, gif, webp, bmp, heic". do not upload.

if access token fetch fails:

• log the full response. if code is non-zero or token field missing, return error and do not attempt steps 2 or 3. recommend re-checking credentials against the feishu app console.

if image upload returns success but image_key is missing or malformed:

• log response and return error: "image upload succeeded but image_key missing from response". this is a feishu backend anomaly. do not proceed to step 3.

if image message send returns success but receive_id_type does not match receive_id:

• before calling step 3, validate that receive_id matches the type. if you pass open_id as receive_id but receive_id_type is user_id, feishu will reject with code non-zero. return error early: "receive_id_type does not match the provided receive_id".

if token expires during execution (< 1 minute remaining):

• re-fetch token before step 2 or 3 if you detect expiry approaching. most implementations will complete within seconds, so expiry during execution is rare. but if batch-processing multiple images, refresh token if expire value has dropped below 60 seconds.

if network timeout occurs:

• on timeout during step 1, 2, or 3, retry the request up to 2 times with 1 second linear backoff. if all retries fail, return error: "network timeout after 3 attempts. check connectivity to open.feishu.cn".

output contract

success case:

• return a json object: {"status":"success","message_id":"om_xxx","image_key":"img_v3_xxx","recipient":"<RECEIVE_ID>"}.
• the message_id proves the message reached feishu backend. the image will render inline in the target chat within 1-2 seconds.

failure case:

• return a json object: {"status":"error","code":<numeric_error_code>,"message":"<human_readable_error>","step":<step_number>}.
• example: {"status":"error","code":400,"message":"image exceeds 30 mb limit","step":2}.
• always include the step where failure occurred to aid debugging.

file location:

• this skill does not write files to disk. all data is in-memory. the image itself lives on feishu's servers after successful upload.

outcome signal

the skill worked if:

• the function returns a success response with a valid message_id.
• the target user opens feishu and sees the image rendered inline in the chat within 1-2 seconds. the image appears as an embedded visual, not as a file download link.
• on feishu desktop or mobile client, the image is clickable and opens in a preview overlay.
• feishu web clients may not render image messages; users must open desktop or mobile to view. this is a feishu platform limitation, not a skill bug.

you know it failed if:

• the function returns an error object with a non-zero code and a step number.
• no message appears in the feishu chat after 5 seconds.
• the user sees a placeholder or "image unavailable" message in the chat, indicating the image_key expired or was invalid.