Rodrigo Rodriguez (Pragmatismo) c26fb1e3a2 Update: General project updates

2025-12-06 11:09:12 -03:00

8 KiB

Raw Blame History

DOWNLOAD

The DOWNLOAD keyword retrieves files from the bot's storage and sends them to users or saves them to external locations, enabling bots to share documents, export data, and deliver files through chat channels.

Syntax

DOWNLOAD "filename"
DOWNLOAD "filename" TO user
DOWNLOAD "filename" AS "display_name"
url = DOWNLOAD "filename" AS LINK

Parameters

Parameter	Type	Description
`filename`	String	Path to the file in the bot's storage
`TO user`	Flag	Send file to specific user (default: current user)
`AS "name"`	String	Custom display name for the file
`AS LINK`	Flag	Return a download URL instead of sending file

Description

DOWNLOAD retrieves a file from the bot's configured storage (drive bucket) and delivers it to the user through their chat channel. It supports:

Sending files directly in chat (WhatsApp, Telegram, web, etc.)
Custom display names for downloaded files
Generating shareable download links
Sending files to specific users
Automatic MIME type detection

The file path is relative to the bot's storage root. Use forward slashes for subdirectories.

Examples

Basic File Download

' Send a file to the current user
DOWNLOAD "documents/user-guide.pdf"
TALK "Here's the user guide you requested!"

Download with Custom Name

' Send file with a friendly display name
DOWNLOAD "reports/rpt-2025-01.pdf" AS "January 2025 Report.pdf"

Generate Download Link

' Get a shareable URL instead of sending directly
link = DOWNLOAD "exports/data.xlsx" AS LINK
TALK "Download your data here: " + link

' Link expires after 24 hours by default

Send to Specific User

' Send file to a different user
DOWNLOAD "contracts/agreement.pdf" TO manager_email
TALK "I've sent the contract to your manager for review."

Download After Processing

' Generate a report and send it
report_content = "# Sales Report\n\n" + sales_data
WRITE report_content TO "temp/report.md"

' Convert to PDF (if configured)
GENERATE PDF "temp/report.md" TO "temp/report.pdf"

DOWNLOAD "temp/report.pdf" AS "Sales Report.pdf"
TALK "Here's your sales report!"

Common Use Cases

Send Invoice

' Lookup and send customer invoice
invoice_path = "invoices/" + customer_id + "/" + invoice_id + ".pdf"

DOWNLOAD invoice_path AS "Invoice-" + invoice_id + ".pdf"
TALK "Here's your invoice. Let me know if you have any questions!"

Export Data

' Export user's data to file and send
user_data = FIND "orders" WHERE customer_id = user.id
WRITE user_data TO "exports/user-" + user.id + "-orders.csv" AS TABLE

DOWNLOAD "exports/user-" + user.id + "-orders.csv" AS "My Orders.csv"
TALK "Here's a complete export of your order history."

' Send meeting notes from earlier session
meeting_date = FORMAT(NOW(), "YYYY-MM-DD")
notes_file = "meetings/" + meeting_date + "-notes.md"

IF FILE_EXISTS(notes_file) THEN
    DOWNLOAD notes_file AS "Meeting Notes - " + meeting_date + ".md"
    TALK "Here are the notes from today's meeting!"
ELSE
    TALK "I don't have any meeting notes for today."
END IF

Provide Template

' Send a template file for user to fill out
TALK "I'll send you the application form. Please fill it out and send it back."
DOWNLOAD "templates/application-form.docx" AS "Application Form.docx"

' Create report on demand
TALK "Generating your monthly report..."

' Build report content
report = "# Monthly Summary\n\n"
report = report + "**Period:** " + month_name + " " + year + "\n\n"
report = report + "## Key Metrics\n\n"
report = report + "- Revenue: $" + FORMAT(revenue, "#,##0.00") + "\n"
report = report + "- Orders: " + order_count + "\n"
report = report + "- New Customers: " + new_customers + "\n"

' Save and send
filename = "reports/monthly-" + FORMAT(NOW(), "YYYYMM") + ".md"
WRITE report TO filename
DOWNLOAD filename AS "Monthly Report - " + month_name + ".md"

Send Multiple Files

' Send several related files
files = ["contract.pdf", "terms.pdf", "schedule.pdf"]

TALK "I'm sending you the complete documentation package:"

FOR EACH file IN files
    DOWNLOAD "documents/" + file
    WAIT 1  ' Brief pause between files
NEXT

TALK "All documents sent! Please review and let me know if you have questions."

Return Values

Direct Download (default)

Returns a confirmation object:

Property	Description
`result.sent`	Boolean indicating success
`result.filename`	Name of file sent
`result.size`	File size in bytes

Download as Link

Returns a URL string:

link = DOWNLOAD "file.pdf" AS LINK
' Returns: "https://storage.example.com/download/abc123?expires=..."

Channel-Specific Behavior

Channel	Behavior
WhatsApp	Sends as document attachment
Telegram	Sends as document or media based on type
Web Chat	Triggers browser download
Email	Attaches to email message
SMS	Sends download link (files not supported)

File Type Handling

File Type	Display
PDF	Document with preview
Images	Inline image display
Audio	Audio player
Video	Video player
Other	Generic document icon

' Images display inline in most channels
DOWNLOAD "photos/product.jpg"

' PDFs show with document preview
DOWNLOAD "docs/manual.pdf"

Error Handling

ON ERROR RESUME NEXT

DOWNLOAD "reports/missing-file.pdf"

IF ERROR THEN
    PRINT "Download failed: " + ERROR_MESSAGE
    TALK "Sorry, I couldn't find that file. It may have been moved or deleted."
END IF

Check File Exists First

files = LIST "invoices/" + customer_id + "/"

found = false
FOR EACH file IN files
    IF file.name = invoice_id + ".pdf" THEN
        found = true
        EXIT FOR
    END IF
NEXT

IF found THEN
    DOWNLOAD "invoices/" + customer_id + "/" + invoice_id + ".pdf"
ELSE
    TALK "Invoice not found. Please check the invoice number."
END IF

Link Options

When using AS LINK, you can configure link behavior:

' Default link (expires in 24 hours)
link = DOWNLOAD "file.pdf" AS LINK

' Custom expiration (in config.csv)
' download-link-expiry,3600  (1 hour)

Size Limits

Limit	Default	Notes
WhatsApp	100 MB	Documents, 16 MB for media
Telegram	50 MB	Standard, 2 GB for premium
Web Chat	No limit	Browser handles download
Email	25 MB	Typical email limit

' For large files, use link instead
file_info = LIST "exports/large-file.zip"

IF file_info[0].size > 50000000 THEN
    link = DOWNLOAD "exports/large-file.zip" AS LINK
    TALK "This file is large. Download it here: " + link
ELSE
    DOWNLOAD "exports/large-file.zip"
END IF

Configuration

Configure download settings in config.csv:

name,value
drive-provider,seaweedfs
drive-url,http://localhost:8333
drive-bucket,my-bot
download-link-expiry,86400
download-link-base-url,https://files.mybot.com
download-max-size,104857600

Implementation Notes

Implemented in Rust under src/file/mod.rs
Uses streaming for large file transfers
Automatic MIME type detection
Supports range requests for resumable downloads
Files are served through secure signed URLs
Access logging for audit trails

UPLOAD — Upload files to storage
READ — Read file contents
WRITE — Write content to files
LIST — List files in storage
GENERATE PDF — Create PDF documents

Summary

DOWNLOAD is essential for delivering files to users through chat. Use it to send invoices, share reports, provide templates, and export data. Combined with AS LINK for large files and custom display names, it provides flexible file delivery for any bot workflow.

8 KiB Raw Blame History