botbook/src/06-gbdialog/keyword-download.md

# 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

```basic
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

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

### Download with Custom Name

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

### Generate Download Link

```basic
' 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

```basic
' 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

```basic
' 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

```basic
' 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

```basic
' 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."
```

### Share Meeting Notes

```basic
' 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

```basic
' 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"
```

### Generate and Share Report

```basic
' 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

```basic
' 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:

```basic
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 |

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

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

---

## Error Handling

```basic
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

```basic
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:

```basic
' 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 |

```basic
' 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`:

```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

---

## Related Keywords

- [UPLOAD](keyword-upload.md) — Upload files to storage
- [READ](keyword-read.md) — Read file contents
- [WRITE](keyword-write.md) — Write content to files
- [LIST](keyword-list.md) — List files in storage
- [GENERATE PDF](keyword-generate-pdf.md) — 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.
- Split from botserver. 2025-12-03 19:56:35 -03:00			`# DOWNLOAD`
docs: comprehensive keyword documentation update Completed stub files: - keyword-soap.md - SOAP web service integration - keyword-merge-pdf.md - PDF merging (MERGE PDF with spaces) - keyword-kb-statistics.md - KB statistics overview - keyword-kb-collection-stats.md - Per-collection stats - keyword-kb-documents-count.md - Document counting - keyword-kb-documents-added-since.md - Recent document tracking - keyword-kb-list-collections.md - Collection listing - keyword-kb-storage-size.md - Storage monitoring Updated documentation: - keyword-generate-pdf.md - Updated to GENERATE PDF (spaces) - keyword-delete.md - Rewritten for unified DELETE - keyword-delete-http.md - Redirects to unified DELETE - keyword-delete-file.md - Redirects to unified DELETE - All keyword docs updated to use spaces not underscores PROMPT.md updates: - Added keyword naming rules (NO underscores) - Added keyword mapping table - Added quick reference for all keywords - Added error handling examples TASKS.md created: - Comprehensive discrepancy report - Model name update tracking (17 files) - Config parameter documentation - Architecture notes Key clarifications: - GENERATE FROM TEMPLATE = FILL keyword - GENERATE WITH PROMPT = LLM keyword - ON ERROR RESUME NEXT now implemented - DELETE is unified (HTTP/DB/File auto-detect) 2025-12-05 09:55:38 -03:00
			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`

			```basic
			`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`

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

			`### Download with Custom Name`

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

			`### Generate Download Link`

			```basic
			`' 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`

			```basic
			`' 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`

			```basic
			`' 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`

			```basic
			`' 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`

			```basic
			`' 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."`
			```

			`### Share Meeting Notes`

			```basic
			`' 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`

			```basic
			`' 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"`
			```

			`### Generate and Share Report`

			```basic
			`' 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`

			```basic
			`' 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:`

			```basic
			`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 \|`

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

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

			`---`

			`## Error Handling`

			```basic
			`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`

			```basic
			`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:

			```basic
			`' 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 \|`

			```basic
			`' 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`:

			```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`

			`---`

			`## Related Keywords`

			`- [UPLOAD](keyword-upload.md) — Upload files to storage`
			`- [READ](keyword-read.md) — Read file contents`
			`- [WRITE](keyword-write.md) — Write content to files`
			`- [LIST](keyword-list.md) — List files in storage`
			`- [GENERATE PDF](keyword-generate-pdf.md) — 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.