feishu file transfer guide

intent

send local files to feishu users through openclaw by obtaining a tenant access token from the feishu api, uploading the file to get a file_key identifier, then sending a file message to the target user. use this when openclaw's message tool only sends file paths instead of actual file content, or when you need reliable file delivery with proper metadata to feishu contacts.

inputs

feishu app credentials (required):

• APP_ID: feishu app id (format: cli_xxxxxxxxxx). store in env var FEISHU_APP_ID
• APP_SECRET: feishu app secret. store in env var FEISHU_APP_SECRET. never commit to version control

file to upload (required):

• FILE_PATH: absolute or relative path to local file (e.g. /path/to/document.docx)
• DISPLAY_NAME: optional custom filename for feishu ui (defaults to basename of FILE_PATH). use ascii/utf-8 characters only; avoid special chars that break multipart encoding
• file size: must be greater than 0 bytes. feishu rejects empty files
• file type: any format supported (docx, pdf, xlsx, images, etc.)

recipient identifier (required):

• RECEIVE_ID: feishu user open_id (format: ou_xxxxxxxxxx). this is the target user's unique id, not their name
• RECEIVE_ID_TYPE: always use "open_id" for user direct messages. other types (user_id, chat_id) require different api endpoints

external connection:

• feishu open platform api at https://open.feishu.cn/open-apis/. requires outbound https access. no firewall restrictions on standard ports

network and ssl (edge cases):

• ssl/tls certificate validation: some environments disable cert verification (see python ssl_context in procedure). production systems should enable full validation
• rate limits: feishu throttles auth endpoint to ~10 req/sec per app; file upload has no documented limit but avoid burst uploads
• token expiry: tenant_access_token has 2hr lifetime (7200 seconds). do not cache tokens longer than 1.5hrs
• network timeout: set reasonable timeouts (e.g. 30s) for slow networks or large files

procedure

step 1: obtain tenant_access_token

input: APP_ID, APP_SECRET

action: call feishu auth endpoint to exchange credentials for a bearer token valid for 2 hours.

http details:

• method: POST
• url: https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal
• headers: Content-Type: application/json
• body: json object with app_id and app_secret fields

python implementation:

import urllib.request
import json
import ssl

ssl_context = ssl.create_default_context()
ssl_context.check_hostname = False
ssl_context.verify_mode = ssl.CERT_NONE

def get_tenant_token(app_id, app_secret):
    url = 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal'
    payload = {'app_id': app_id, 'app_secret': app_secret}
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode('utf-8'),
        method='POST'
    )
    req.add_header('Content-Type', 'application/json')
    
    with urllib.request.urlopen(req, context=ssl_context) as response:
        result = json.loads(response.read().decode('utf-8'))
        if result.get('code') != 0:
            raise Exception(f"auth failed: {result.get('msg')}")
        return result['tenant_access_token']

token = get_tenant_token(APP_ID, APP_SECRET)

powershell implementation:

$body = @{
    app_id = "cli_xxxxxxxxxx"
    app_secret = "xxxxxxxxxx"
} | ConvertTo-Json

$response = Invoke-RestMethod `
    -Uri 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal' `
    -Method POST `
    -ContentType 'application/json; charset=utf-8' `
    -Body $body

$TOKEN = $response.tenant_access_token

output: tenant_access_token string (format: t-xxxxxxxxxx). typical response code 0 with msg "ok". any non-zero code indicates auth failure (check APP_ID and APP_SECRET validity)

---

step 2: upload file and obtain file_key

input: tenant_access_token, FILE_PATH, DISPLAY_NAME

action: upload file via multipart/form-data to feishu file api. returns a unique file_key identifier needed for step 3.

critical requirements:

• use multipart/form-data content type with explicit boundary marker
• include two form fields: "file" (binary) and "file_type" (text value "stream")
• filename in content-disposition header must be utf-8 encoded and match DISPLAY_NAME. chinese characters are supported
• do not send empty files (size 0 bytes)

http details:

• method: POST
• url: https://open.feishu.cn/open-apis/im/v1/files
• headers: Authorization: Bearer {token}, Content-Type: multipart/form-data; boundary={boundary}

python implementation (recommended):

def upload_file_to_feishu(token, file_path, display_name=None):
    if display_name is None:
        display_name = os.path.basename(file_path)
    
    url = 'https://open.feishu.cn/open-apis/im/v1/files'
    
    # read binary file data
    with open(file_path, 'rb') as f:
        file_data = f.read()
    
    if len(file_data) == 0:
        raise ValueError(f"file {file_path} is empty")
    
    # build multipart body manually
    boundary = '----WebKitFormBoundary7MA4YWxkTrZu0gW'
    body = b''
    
    # add file field
    body += f'------{boundary}\r\n'.encode('utf-8')
    body += f'Content-Disposition: form-data; name="file"; filename="{display_name}"\r\n'.encode('utf-8')
    body += b'Content-Type: application/octet-stream\r\n\r\n'
    body += file_data
    body += b'\r\n'
    
    # add file_type field
    body += f'------{boundary}\r\n'.encode('utf-8')
    body += b'Content-Disposition: form-data; name="file_type"\r\n\r\n'
    body += b'stream\r\n'
    
    # end boundary
    body += f'------{boundary}--\r\n'.encode('utf-8')
    
    # send request
    req = urllib.request.Request(url, data=body, method='POST')
    req.add_header('Authorization', f'Bearer {token}')
    req.add_header('Content-Type', f'multipart/form-data; boundary=----{boundary}')
    
    with urllib.request.urlopen(req, context=ssl_context) as response:
        result = json.loads(response.read().decode('utf-8'))
        if result.get('code') != 0:
            raise Exception(f"upload failed: {result.get('msg')}")
        return result['data']['file_key']

file_key = upload_file_to_feishu(token, '/path/to/file.docx', '语文.docx')

powershell implementation:

# Note: PowerShell multipart handling is verbose. Python is strongly preferred.
$filePath = "C:\path\to\file.docx"
$fileBytes = [System.IO.File]::ReadAllBytes($filePath)

# construct multipart body (simplified example)
$boundary = "----WebKitFormBoundary7MA4YWxkTrZu0gW"
$body = ...  # omitted for brevity; see python version for full implementation

Invoke-RestMethod `
    -Uri 'https://open.feishu.cn/open-apis/im/v1/files' `
    -Method POST `
    -Headers @{
        'Authorization' = "Bearer $TOKEN"
        'Content-Type' = "multipart/form-data; boundary=----$boundary"
    } `
    -Body $body

output: file_key string (format: file_v3_00vp_xxxxxxxxxx). typical response code 0. non-zero code with msg "invalid_parameter" suggests empty file or malformed multipart body

---

step 3: send file message to recipient

input: tenant_access_token, file_key, RECEIVE_ID

action: send file message containing the file_key to the target feishu user. message arrives in their direct message inbox with the original filename and download option.

http details:

• method: POST
• url: https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id
• headers: Authorization: Bearer {token}, Content-Type: application/json; charset=utf-8
• body: json with receive_id, msg_type="file", content={file_key}

python implementation:

def send_file_message(token, file_key, receive_id):
    url = 'https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id'
    payload = {
        'receive_id': receive_id,
        'msg_type': 'file',
        'content': json.dumps({'file_key': file_key})
    }
    
    req = urllib.request.Request(
        url,
        data=json.dumps(payload).encode('utf-8'),
        method='POST'
    )
    req.add_header('Authorization', f'Bearer {token}')
    req.add_header('Content-Type', 'application/json; charset=utf-8')
    
    with urllib.request.urlopen(req, context=ssl_context) as response:
        result = json.loads(response.read().decode('utf-8'))
        if result.get('code') != 0:
            raise Exception(f"send failed: {result.get('msg')}")
        return result['data']['message_id']

message_id = send_file_message(token, file_key, RECEIVE_ID)

powershell implementation:

$body = @{
    receive_id = "ou_xxxxxxxxxx"
    msg_type = "file"
    content = '{"file_key":"file_v3_00vp_xxxxxxxxxx"}'
} | ConvertTo-Json

$response = Invoke-RestMethod `
    -Uri 'https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id' `
    -Method POST `
    -Headers @{
        'Authorization' = "Bearer $TOKEN"
        'Content-Type' = 'application/json; charset=utf-8'
    } `
    -Body $body

$MESSAGE_ID = $response.data.message_id

output: message_id string (format: om_xxxxxxxxxx) confirming successful delivery. typical response code 0. non-zero code with msg "invalid_receive_id" indicates RECEIVE_ID does not exist or is malformed

---

decision points

if auth fails (non-zero code from step 1):

• check that APP_ID matches the format cli_xxxxxxxxxx from feishu developer console
• verify APP_SECRET has not expired or been rotated in feishu admin panel
• confirm environment variables FEISHU_APP_ID and FEISHU_APP_SECRET are set correctly
• else, create new app credentials in feishu open platform

if file upload fails (non-zero code from step 2):

• if error message mentions "invalid_parameter" or "400": verify file exists, is readable, has size > 0 bytes
• if error mentions "multipart" or "boundary": ensure boundary string in content-type header matches body boundary markers exactly
• if filename contains non-utf-8 characters: re-encode DISPLAY_NAME to utf-8 before passing to request
• else, check feishu api status page for outages

if file send fails (non-zero code from step 3):

• if error mentions "invalid_receive_id": confirm RECEIVE_ID is a valid feishu user open_id (format ou_xxxxxxxxxx), not a user_id or email
• if error mentions "invalid_file_key": verify file_key was obtained in step 2 and has not expired (use within 24 hours of upload)
• if error mentions "permission denied": confirm app has im:message scope granted in feishu console
• else, file may have been deleted after upload; re-run steps 2-3

if token expires during multi-file operations:

• check elapsed time since step 1. if > 1.5 hours have passed, re-run step 1 to refresh token (expiry is 7200 seconds / 2 hours)
• do not reuse tokens older than 1.5 hours

if receiving send errors on large files:

• feishu has undocumented but real file size limits. if upload succeeds but send fails, file may exceed practical limit
• workaround: split file into smaller chunks and send separately, or use feishu cloud storage link instead

output contract

success state:

• step 1 returns a valid tenant_access_token (bearer token, 2hr lifetime)
• step 2 returns a file_key in format file_v3_00vp_xxxxxxxxxx
• step 3 returns a message_id in format om_xxxxxxxxxx confirming message creation

data format:

• all api responses are json objects with code (integer, 0 for success), msg (string), and data (object with response payload)
• file_key persists in feishu file service for 24 hours after upload
• message_id is immutable once returned; can be used for later retrieval or deletion

file location:

• uploaded file resides in feishu cloud storage, not on local disk
• recipient accesses file via feishu ui (desktop app, web, mobile) in their direct message thread
• file can be re-downloaded by recipient indefinitely after message arrival

no local artifacts (files are remote):

• script does not create output files locally
• recommend logging message_id for audit/tracking purposes

outcome signal

user-facing confirmation:

• recipient sees new message in feishu direct message inbox from the app/bot account
• message displays filename (DISPLAY_NAME) with file icon
• recipient can click to preview (if supported format) or download file with original filename
• file appears instantly (within 1-2 seconds of step 3 completion)

programmatic confirmation:

• step 3 returns http 200 with json code field = 0 and a non-empty message_id
• check logs for "message_id: om_xxxxxxxxxx" or equivalent success log line
• no exception or error raised in any step indicates full success

failure signals (skip step 3 if any occur):

• step 1: http error, non-zero code, missing tenant_access_token field in response
• step 2: http error, non-zero code, missing file_key field in data, or file not found on disk
• step 3: http error, non-zero code, missing message_id field in data

recipient verification:

• ask recipient to check feishu direct message thread with bot/app account
• confirm filename matches DISPLAY_NAME and file can be downloaded
• if file shows as uuid-style name instead of DISPLAY_NAME, filename encoding failed in step 2 (re-run with ascii-only DISPLAY_NAME)

---

complete reference implementation

python standalone script:

#!/usr/bin/env python3
"""
feishu file transfer standalone script.
usage: python feishu_transfer.py <file_path> <receive_id> [display_name]
example: python feishu_transfer.py /home/user/report.xlsx ou_abc123 "Q4 Report"
"""

import urllib.request
import json
import ssl
import os
import sys

class FeishuFileTransfer:
    def __init__(self, app_id, app_secret):
        self.app_id = app_id
        self.app_secret = app_secret
        self.ssl_context = ssl.create_default_context()
        self.ssl_context.check_hostname = False
        self.ssl_context.verify_mode = ssl.CERT_NONE
    
    def get_tenant_token(self):
        """step 1: obtain tenant_access_token"""
        url = 'https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal'
        payload = {'app_id': self.app_id, 'app_secret': self.app_secret}
        req = urllib.request.Request(
            url,
            data=json.dumps(payload).encode('utf-8'),
            method='POST'
        )
        req.add_header('Content-Type', 'application/json')
        
        try:
            with urllib.request.urlopen(req, context=self.ssl_context) as response:
                result = json.loads(response.read().decode('utf-8'))
                if result.get('code') != 0:
                    raise Exception(f"auth failed: code={result.get('code')}, msg={result.get('msg')}")
                print(f"[step 1] token obtained (expires in {result.get('expire')}s)")
                return result['tenant_access_token']
        except urllib.error.URLError as e:
            raise Exception(f"network error during auth: {e}")
    
    def upload_file(self, token, file_path, display_name=None):
        """step 2: upload file and obtain file_key"""
        if display_name is None:
            display_name = os.path.basename(file_path)
        
        if not os.path.exists(file_path):
            raise FileNotFoundError(f"file not found: {file_path}")
        
        file_size = os.path.getsize(file_path)
        if file_size == 0:
            raise ValueError(f"file is empty: {file_path}")
        
        url = 'https://open.feishu.cn/open-apis/im/v1/files'
        
        with open(file_path, 'rb') as f:
            file_data = f.read()
        
        boundary = '----WebKitFormBoundary7MA4YWxkTrZu0gW'
        body = b''
        
        body += f'------{boundary}\r\n'.encode('utf-8')
        body += f'Content-Disposition: form-data; name="file"; filename="{display_name}"\r\n'.encode('utf-8')
        body += b'Content-Type: application/octet-stream\r\n\r\n'
        body += file_data
        body += b'\r\n'
        
        body += f'------{boundary}\r\n'.encode('utf-8')
        body += b'Content-Disposition: form-data; name="file_type"\r\n\r\n'
        body += b'stream\r\n'
        
        body += f'------{boundary}--\r\n'.encode('utf-8')
        
        req = urllib.request.Request(url, data=body, method='POST')
        req.add_header('Authorization', f'Bearer {token}')
        req.add_header('Content-Type', f'multipart/form-data; boundary=----{boundary}')
        
        try:
            with urllib.request.urlopen(req, context=self.ssl_context) as response:
                result = json.loads(response.read().decode('utf-8'))
                if result.get('code') != 0:
                    raise Exception(f"upload failed: code={result.get('code')}, msg={result.get('msg')}")
                file_key = result['data']['file_key']
                print(f"[step 2] file uploaded (size={file_size}B, key={file_key})")
                return file_key
        except urllib.error.URLError as e:
            raise Exception(f"network error during upload: {e}")
    
    def send_file_message(self, token, file_key, receive_id):
        """step 3: send file message"""
        url = 'https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id'
        payload = {
            'receive_id': receive_id,
            'msg_type': 'file',
            'content': json.dumps({'file_key': file_key})
        }
        
        req = urllib.request.Request(
            url,
            data=json.dumps(payload).encode('utf-8'),
            method='POST'
        )
        req.add_header('Authorization', f'Bearer {token}')
        req.add_header('Content-Type', 'application/json; charset=utf-8')
        
        try:
            with urllib.request.urlopen(req, context=self.ssl_context) as response:
                result = json.loads(response.read().decode('utf-8'))
                if result.get('code') != 0:
                    raise Exception(f"send failed: code={result.get('code')}, msg={result.get('msg')}")
                message_id = result['data']['message_id']
                print(f"[step 3] message sent to {receive_id} (message_id={message_id})")
                return message_id
        except urllib.error.URLError as e:
            raise Exception(f"network error during send: {e}")
    
    def transfer(self, file_path, receive_id, display_name=None):
        """execute full transfer pipeline"""
        print(f"starting feishu file transfer: {file_path} -> {receive_id}")
        token = self.get_tenant_token()
        file_key = self.upload_file(token, file_path, display_name)
        message_id = self.send_file_message(token, file_key, receive_id)
        print(f"transfer complete: {message_id}")
        return message_id

if __name__ == '__main__':
    APP_ID = os.getenv('FEISHU_APP_ID')
    APP_SECRET = os.getenv('FEISHU_APP_SECRET')
    
    if not APP_ID or not APP_SECRET:
        print("error: FEISHU_APP_ID and FEISHU_APP_SECRET env vars required")
        sys.exit(1)
    
    if len(sys.argv) < 3:
        print(f"usage: {sys.argv[0]} <file_path> <receive_id> [display_name]")
        sys.exit(1)
    
    file_path = sys.argv[1]
    receive_id = sys.argv[2]
    display_name = sys.argv[3] if len(sys.argv) > 3 else None
    
    try:
        transfer = FeishuFileTransfer(APP_ID, APP_SECRET)
        transfer.transfer(file_path, receive_id, display_name)
    except Exception as e:
        print(f"error: {e}")
        sys.exit(1)

run with:

export FEISHU_APP_ID=cli_xxxxxxxxxx
export FEISHU_APP_SECRET=xxxxxxxxxx
python feishu_transfer.py /path/to/file.docx ou_user123 "My Document"

---

troubleshooting table

symptom	root cause	fix
filename shows as uuid or garbage	multipart encoding error or non-utf-8 chars in display_name	ensure display_name is valid utf-8; use python version if possible
"invalid_parameter" on upload	file is 0 bytes or multipart boundary mismatch	verify file has content; check boundary string matches exactly in headers
"invalid_receive_id" on send	receive_id is not open_id format or user does not exist	confirm receive_id is ou_xxxxxxxxxx format and user is active in tenant
"permission denied"	app lacks im:message scope	grant im:message and im:file scopes in feishu console under app permissions
file downloaded but appears corrupted	upload interrupted or file type incompatible	re-run upload with same file; try different file format if issue persists
token auth fails	credentials expired or incorrect	verify APP_ID and APP_SECRET in feishu developer console; regenerate if needed
slow upload for large files	network latency or rate limiting	increase timeout; split very large files (>100MB) into smaller uploads

---

references

• feishu open platform: https://open.feishu.cn/
• file api docs: https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/file/create
• message api docs: https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/message/create
• auth api docs: https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/auth-v3/tenant_access_token/internal

---

credits: original guide by SwingMonkey.