Slack Document Uploader

A Python implementation for uploading documents to Slack channels using Slack's modern REST API.

Overview

This project demonstrates how to use Slack's REST APIs to upload and share documents to Slack channels. It implements the modern three-step upload process that replaced the deprecated files.upload method.

Slack API Research

Modern File Upload Process

As of May 16, 2024, Slack deprecated the files.upload API method in favor of a more asynchronous and scalable approach. The new process involves three steps:

Step 1: Get Upload URL

API Method: files.getUploadURLExternal

Request an upload URL and file ID from Slack:

curl --location 'https://slack.com/api/files.getUploadURLExternal' \
  --header 'Authorization: Bearer {token}' \
  --form 'filename="document.pdf"' \
  --form 'length="12345"'

Response:

{
  "ok": true,
  "upload_url": "https://files.slack.com/upload/v1/...",
  "file_id": "F012AB3CDE4"
}

Step 2: Upload File Content

Upload the actual file content to the URL received in Step 1:

curl --location 'https://files.slack.com/upload/v1/...' \
  --header 'Content-Type: application/octet-stream' \
  --data-binary '@document.pdf'

Step 3: Complete Upload

API Method: files.completeUploadExternal

Finalize the upload and optionally share to a channel:

curl --location 'https://slack.com/api/files.completeUploadExternal' \
  --header 'Authorization: Bearer {token}' \
  --form 'files="[{\"title\":\"My Document\", \"id\":\"F012AB3CDE4\"}]"' \
  --form 'channel_id="C0123456789"' \
  --form 'initial_comment="Here is the document"'

Required Scopes

Your Slack app must have the following OAuth scopes:

• files:write - Required to upload files
• files:read - Optional, for reading file information

API Documentation References

• Working with Files
• files.getUploadURLExternal
• files.completeUploadExternal
• Deprecation Notice

Setup Instructions

Prerequisites

• Python 3.7 or higher
• A Slack workspace where you have permission to create apps
• A Slack app with the files:write scope

1. Create a Slack App

1. Go to https://api.slack.com/apps
2. Click "Create New App" → "From scratch"
3. Enter an app name (e.g., "Document Uploader") and select your workspace
4. Click "Create App"

2. Configure OAuth Scopes

1. In your app settings, go to "OAuth & Permissions"
2. Scroll to "Scopes" → "Bot Token Scopes"
3. Add the following scopes:
   • files:write
   • chat:write (optional, if you want to post messages)
4. Scroll to the top and click "Install to Workspace"
5. Authorize the app
6. Copy the "Bot User OAuth Token" (starts with xoxb-)

3. Get Channel ID

1. Open Slack in your browser
2. Navigate to the channel where you want to upload files
3. The channel ID is in the URL: https://app.slack.com/client/T.../C...
   • The part starting with C is your channel ID (e.g., C0123456789)

Alternatively, right-click the channel → "View channel details" → scroll to bottom to see the Channel ID.

4. Install Dependencies

# Clone or download this repository
cd "Slack Assignment"

# Install required packages
pip install -r requirements.txt

5. Configure Environment Variables

1. Copy the example environment file:

   cp .env.example .env

2. Edit .env and add your credentials:

   SLACK_BOT_TOKEN=xoxb-your-actual-token-here
   SLACK_CHANNEL_ID=C0123456789

Usage

Basic Usage

Upload a file to the configured channel:

python slack_file_uploader.py path/to/your/document.pdf

With Custom Title

Upload a file with a custom title:

python slack_file_uploader.py resume.pdf "My Resume"

With Title and Comment

Upload a file with a title and initial comment:

python slack_file_uploader.py resume.pdf "My Resume" "Here is my updated resume for review"

Example Output

📤 Uploading file: resume.pdf (245678 bytes)
  Step 1/3: Getting upload URL...
  ✓ Received upload URL and file ID: F012AB3CDE4
  Step 2/3: Uploading file content...
  ✓ File content uploaded successfully
  Step 3/3: Completing upload...
  ✓ Upload completed successfully
✅ File shared to channel: C0123456789

📋 Upload Details:
  File ID: F012AB3CDE4
  Name: resume.pdf
  Title: My Resume
  Size: 245678 bytes
  Type: PDF
  Permalink: https://yourworkspace.slack.com/files/...

Code Structure

slack_file_uploader.py

The main script contains the SlackFileUploader class with the following methods:

• get_upload_url(filename, file_size) - Step 1: Request upload URL from Slack
• upload_file_content(upload_url, file_path) - Step 2: Upload file to the URL
• complete_upload(file_id, title, channel_id, initial_comment) - Step 3: Finalize and share
• upload_file(file_path, title, channel_id, initial_comment) - Convenience method combining all steps

Using as a Library

You can also import and use the SlackFileUploader class in your own code:

from slack_file_uploader import SlackFileUploader

# Initialize uploader
uploader = SlackFileUploader(token="xoxb-your-token")

# Upload file
result = uploader.upload_file(
    file_path="document.pdf",
    title="Important Document",
    channel_id="C0123456789",
    initial_comment="Please review this document"
)

print(f"File uploaded: {result['files'][0]['permalink']}")

Security Best Practices

1. Never commit tokens - The .gitignore file excludes .env to prevent accidental commits
2. Use environment variables - Store sensitive credentials in .env file
3. Limit token scopes - Only request the scopes your app needs
4. Rotate tokens regularly - Regenerate tokens periodically
5. Use Bot tokens - Bot tokens (xoxb-) are safer than user tokens

Troubleshooting

Error: "SLACK_BOT_TOKEN not found"

• Make sure you created a .env file with your token
• Verify the token starts with xoxb-

Error: "missing_scope"

• Your app needs the files:write scope
• Go to your app settings → OAuth & Permissions → Add the scope
• Reinstall the app to your workspace

Error: "channel_not_found"

• Verify the channel ID is correct
• Make sure the bot is added to the channel (invite it with /invite @YourBot)

Error: "invalid_auth"

• Your token may be expired or invalid
• Regenerate the token in your app settings

File uploads but doesn't appear in channel

• Make sure you're providing the channel_id parameter
• Verify the bot has been invited to the channel

API Limitations

• Maximum file size: 1GB for free workspaces, larger for paid plans
• Rate limits apply (Tier 3: 20+ requests per minute)
• Files are scanned for malware before being made available

References

• Slack API Documentation
• Working with Files Guide
• Python Requests Library

License

This project is provided as-is for educational and demonstration purposes.