1. File Input in Actions
File inputs allow users to upload files that your action can then process or send to external APIs.1.1 When to Use File Inputs
- Upload files to external tools: Send user-uploaded documents to APIs, cloud storage, or external services like email or tickets systems.
- Process user files: Analyze, convert, or transform files uploaded by users
1.2 Adding File Input Fields
Single File Input
Add an input field of type “FILE” to accept one file:
Multiple File Input
For multiple files, enable Allow multiple files:
1.3 Accessing File Data in Code
Every uploaded file is delivered as aFileData
object with this exact format:
Important: File inputs do NOT include atext
property. Thetext
shortcut only exists for file outputs.
Single File Access
Multiple Files Access
Data Structure: When “Allow multiple files” is enabled, data.input.fieldName
is an array. Otherwise, it’s a single object.
1.4 Common Input Patterns
1.5 Input Validation & Error Handling
2. File Output in Actions
File outputs allow your action to generate and return files that users can download or use in subsequent actions.2.1 When to Use File Outputs
- Generate reports: Create PDFs, spreadsheets, or documents from data
- Retrieve files from APIs: Download files from external services
- Transform files: Convert between formats or process uploaded files
- Export data: Create CSV exports, backup files, or data dumps
2.2 File Output Format
Return files under afiles
key in your response:
File Output Properties
Field | Required | Notes |
---|---|---|
fileName | ✓ | Include proper file extension |
mimeType | ✓ | Accurate MIME type for proper handling |
base64 | ✓* | Base64 encoded binary content |
text | ✓* | UTF-8 text content (alternative to base64) |
lastModified | – | ISO date string (defaults to current time) |
base64
OR text
, never both.
2.3 Common Output Patterns
3. File Output in Triggers
Triggers can also return files when detecting events that include file attachments or when generating files based on trigger data.Key Difference: Unlike actions that return objects directly, triggers must return an array of events. Each event needsid
,timestamp
, anddata
properties, with files inside thedata
object.
3.1 When to Use File Outputs in Triggers
- Email attachments: Forward attachments from incoming emails
- File change events: Return modified or new files from monitored systems
- Generated notifications: Create summary files or reports when events occur
- API webhook files: Process and forward files from webhook payloads
3.2 Trigger File Output Format
Triggers must return an array of objects withid
, timestamp
, and data
properties. Files go inside the data
object:
Important: Unlike actions, triggers must return an array of events, andfiles
must be inside thedata
object, not at the top level.
3.3 Common Trigger Patterns
4. Platform Constraints & Limits
Constraint | Limit |
---|---|
Total file size per action | 100 MB |
Maximum files per action | 20 files |
Individual documents | ≤ 256 MB* |
Individual images | ≤ 20 MB |
Individual spreadsheets | ≤ 30 MB |
Individual audio files | ≤ 200 MB* |
Individual video files | ≤ 20 MB |
Other file types | ≤ 10 MB |
Action execution timeout | 2 minutes |
Validation: Exceeding limits throws an error before your code executes.
4.1 Sandbox Library Restrictions
Custom action and trigger code runs in a secure sandboxed environment.
You cannot install or import external libraries (npm, pip, etc.)—only a limited set of built-in JavaScript/Node.js APIs are available.
For advanced file processing (e.g., PDF parsing, image manipulation), use external APIs or services and call them from your code.
5. Best Practices
File Input Best Practices
- Validate file types early: Check MIME types before processing
- Handle missing files gracefully: Use
|| []
for optional file arrays - Log file metadata: Help debug issues without exposing content
- Provide clear error messages: Tell users exactly what went wrong
File Output Best Practices
- Use meaningful filenames: Include dates, IDs, or descriptive names
- Set accurate MIME types: Enables proper file handling and previews
- Use text shortcut for UTF-8: More efficient than base64 for text files
- Include processing status: Help users understand what happened
Performance Best Practices
- Process files in parallel when possible: Use
Promise.all()
for independent operations - Avoid loading all files into memory: Process one at a time for large batches
- Log progress: Use
ld.log()
to track processing status - Handle errors gracefully: Continue processing other files if one fails
6. Troubleshooting
Issue | Likely Cause | Solution |
---|---|---|
”File not found” | User didn’t attach file | Make file input required or add validation |
Size limit error | Files exceed 100 MB total | Ask for smaller files or fewer files |
”Invalid file type” | Wrong MIME type | Validate file.mimeType in your code |
Empty file content | Base64 encoding issue | Verify file.base64 is valid |
Timeout errors | Large files or slow processing | Optimize processing or reduce file sizes |
Memory errors | Too many large files | Process files sequentially, not in parallel |