블로그로 돌아가기
Guide

Slack files.upload 종료: 대신 쓰는 3단계 업로드

files.upload는 이제 method_deprecated를 돌려줍니다. files.getUploadURLExternal로 URL을 받고, 바이트를 POST한 뒤, files.completeUploadExternal로 공유하세요. SDK에서는 files_upload_v2입니다. curl과 Python으로 시험했고, 오류 없이 실패하는 두 경우도 확인했습니다.

Slack Green Team
November 20, 2026
November 20, 2026
4 분 읽기
Share:
slack api
개발자
slack 파일

Slack의 예전 files.upload 메서드는 종료됐습니다. 2026년 9월 29일 files:write 범위가 있는 저희 봇으로 호출하자 {"ok": false, "error": "method_deprecated"}가 돌아왔습니다. 대신 쓰는 방법은 호출 세 번입니다. files.getUploadURLExternal이 업로드 URL과 파일 ID를 돌려주고, 그 URL로 파일 바이트를 POST한 뒤, files.completeUploadExternal로 파일을 채널에 공유합니다. Python과 Node SDK는 세 단계를 호출 하나로 묶었고, Python에서는 files_upload_v2, Node에서는 filesUploadV2입니다. 아래에 저희가 실행한 curl 버전, Python 버전, 그리고 ok: true가 돌아오는데도 파일이 망가지거나 사라지는 실수 두 가지를 실었습니다.

files.upload가 지금 돌려주는 것

chat:write만 있는 토큰으로는 예전 메서드도 새 메서드도 먼저 범위에서 실패합니다.

{"ok": false, "error": "missing_scope", "needed": "files:write", "provided": "chat:write"}

files:write를 추가하고 다시 설치하자 files.upload는 이렇게 돌려줬습니다.

{"ok": false, "error": "method_deprecated"}

Python SDK의 예전 files_upload()도 같은 벽에 부딪힙니다. slack_sdk 3.44.1은 files_upload_v2()를 쓰라는 경고를 띄운 뒤 method_deprecated와 함께 SlackApiError를 냈습니다. 오래된 플러그인이나 스크립트가 이 오류를 낸다면 아직 files.upload를 부르고 있는 것이고, 업데이트하는 것 말고는 방법이 없습니다. 범위를 추가해도 소용없습니다.

curl로 하는 3단계 업로드

저희가 실행한 스크립트입니다. 41바이트 CSV를 채널에 올립니다.

TOKEN=$SLACK_BOT_TOKEN; CH=C0C4RQXFPAT; F=report.csv
LEN=$(wc -c < "$F" | tr -d ' ')

# 1. ask for an upload URL
S1=$(curl -s -X POST https://slack.com/api/files.getUploadURLExternal \
  -H "Authorization: Bearer $TOKEN" -d filename=report.csv -d length=$LEN)
URL=$(echo "$S1" | python3 -c 'import json,sys;print(json.load(sys.stdin)["upload_url"])')
FID=$(echo "$S1" | python3 -c 'import json,sys;print(json.load(sys.stdin)["file_id"])')

# 2. send the bytes
curl -s -X POST "$URL" -F filename=@$F

# 3. finish and share to the channel
curl -s -X POST https://slack.com/api/files.completeUploadExternal \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d "{\"files\":[{\"id\":\"$FID\",\"title\":\"report.csv\"}],\"channel_id\":\"$CH\",\"initial_comment\":\"uploaded with the 3-step flow\"}"

단계마다 출력된 내용입니다(업로드 URL은 줄였습니다).

step 1
{"ok": true, "upload_url": "https://files.slack.com/upload/v1/CwABAAAAXAoAASZgcNSg6rYjCg...", "file_id": "F0C5B99LWLU"}
step 2
HTTP 200, body: OK - 41
step 3
{"ok": true, "files": [{"id": "F0C5B99LWLU", "title": "report.csv"}]}

1단계에는 파일 크기를 바이트로 적은 length가 꼭 있어야 합니다. 빼면 invalid_arguments가 돌아오고, 메시지는 [ERROR] missing required field: length였습니다. 2단계는 일반 텍스트로 답하며, OK - 뒤에 Slack이 받은 바이트 수가 붙습니다. 1,073,741,824바이트를 넘으면 대신 400 invalid length라고 답합니다. 이 경계는 Slack 파일 크기 제한 테스트에서 찾았습니다. 3단계는 (channels가 아니라) channel_id와 files 배열을 받으므로, 올린 파일 여러 개를 메시지 하나로 공유할 수 있습니다. 파일 ID는 1단계에서 생기지만, 3단계 전까지는 아무에게도 보이지 않습니다.

files_upload_v2로 Python에서 같은 업로드

import os
from slack_sdk import WebClient
client = WebClient(token=os.environ["SLACK_BOT_TOKEN"])
r = client.files_upload_v2(
    channel="C0C4RQXFPAT",
    file="report.csv",
    title="report.csv (v2)",
    initial_comment="files_upload_v2",
)
print(r["files"][0]["id"])

실행하자 ok: True와 파일 ID F0C4S7G940P가 돌아왔고, 파일은 아래 스크린샷의 두 번째 업로드로 채널에 나왔습니다. v2 함수는 단수형 channel을 받고, 예전 함수는 channels를 받았습니다. 같은 세 단계는 동영상 파일에도 통하고, Slack은 그것을 플레이어용으로 변환합니다. 올린 뒤 어떤 형식이 재생되는지는 Slack 동영상 형식 테스트에 있습니다.

Slack에서 다시는 '자리 비움'으로 표시되지 마세요

클라우드 기반. 다운로드 불필요. 노트북이 꺼져 있어도 24시간 작동.

ok가 돌아와도 잘못된 업로드 두 가지

일부러 실수 두 가지를 해 봤습니다. 둘 다 오류가 나지 않았습니다.

첫 번째는 length=10으로 요청해 놓고 41바이트를 모두 보내는 것입니다. 2단계는 OK - 10, 3단계는 ok: true라고 답했고, Slack의 파일은 10바이트에서 잘려 있었습니다. 스크린샷의 세 번째 업로드가 그 파일이고, 머리글 줄이 signu에서 끝납니다.

Slack 채널에 올라온 업로드 세 개. 3단계 흐름, files_upload_v2, 길이를 잘못 넣어 잘린 채 date, signu만 보이는 파일

그러니 length는 인코딩 전 문자열 길이가 아니라 보내는 바이트로 계산하세요. ASCII가 아닌 글자가 든 UTF-8 텍스트에서는 둘이 다릅니다. 올린 이미지를 파일이 아니라 Block Kit 메시지 안에 보여 주려면 이미지 블록의 slack_file에 파일 ID를 넣으세요. 이미지 블록 테스트에서 PNG, JPG, GIF는 됐고 WebP는 안 됐습니다. 이렇게 올린 파일은 Block Kit 메시지 안에 카드로 둘 수도 있습니다. 파일 블록 테스트에서 "source": "remote"와 파일 ID로 하나를 올렸습니다.

두 번째는 2단계를 건너뛰고 files.completeUploadExternal을 부르는 것입니다. ok: true가 돌아왔지만 파일은 채널에 나오지 않았고, 그 ID로 files.info를 부르자 file_not_found가 돌아왔습니다. 업로드가 "성공"하는데 아무것도 안 보인다면, 2단계가 실행됐는지, 그 본문이 OK - 뒤에 내 바이트 수를 보여 주는지 확인하세요.

다른 도구에서 올리기

  • • GitHub Actions: slackapi/slack-github-action에는 files.uploadV2 메서드가 있습니다. 워크플로는 GitHub Actions에서 Slack 메시지 보내는 법에 있습니다.
  • • 수신 웹후크로는 파일을 올릴 수 없습니다. 텍스트와 블록만 보낼 수 있고, 웹후크 파일 테스트에서 base64 필드는 무시됐고 slack_file 이미지 블록은 invalid_blocks로 실패했습니다. 파일을 붙이려면 files:write가 있는 봇 토큰이 필요하며, 받는 법은 Slack 봇 토큰에 있습니다.
  • • 비공개 채널에서는 먼저 봇을 멤버로 넣어야 합니다. 그러지 않으면 다른 게시처럼 3단계가 실패합니다. channel_not_found를 보세요.

자주 묻는 질문

files_upload_v2에는 files.upload와 다른 범위가 필요한가요? 아니요. 테스트에서 둘 다 files:write를 요구했습니다.

스레드에 올릴 수 있나요? 네. files.completeUploadExternal에 thread_ts를 넘기자, 부모 메시지의 conversations.replies가 그 파일을 답글로 보여 줬습니다. files_upload_v2도 같은 thread_ts 인수를 받습니다.

예전 연동이 왜 업로드를 멈췄나요? 로그에 method_deprecated가 보이면 아직 files.upload를 부르고 있는 것입니다. 3단계 흐름을 쓰는 버전으로 라이브러리나 플러그인을 업데이트하세요.

Always Active

마우스 흔들기는 그만.

수백 명의 원격 근무자들이 Slack 상태를 걱정하지 않습니다. 한 번 설정하면 영원히 초록불.

관련 기사

Guide

Slack API conversations.list로 채널 목록 받기: 비공개 채널이 빠지는 이유

conversations.list는 공개 채널을 모두 돌려주지만 비공개 채널은 봇이 들어 있는 것만 돌려줍니다. 2026년 10월 2일 봇 토큰과 사용자 토큰으로 실행해 각각 돌려준 내용을 그대로 실었습니다.

Slack Green Team
Guide

Slack 봇 토큰: xoxb- 토큰 찾는 곳과 xoxb, xoxp 차이 테스트

Slack 봇 토큰은 앱의 OAuth & Permissions 페이지에 있는 Bot User OAuth Token으로, xoxb-로 시작하고 앱을 설치하면 나타납니다. 받는 순서, SLACK_BOT_TOKEN으로 읽는 법, xoxp 사용자 토큰, xapp 앱 수준 토큰, xoxe 순환, xoxc 세션 토큰과의 차이를 정리했습니다.

Slack Green Team
Guide

Slack 글자 색: 글자에 색은 못 넣지만 색이 보이는 3가지

Slack에는 메시지에도 캔버스에도 글자 색 옵션이 없고, API도 색 스타일을 받지 않습니다. 2026년 9월 29일 모든 방법을 시험했습니다. 색상 코드에는 색 견본이 붙고, 인라인 코드는 빨간색이며, 앱 메시지에는 색 막대를 붙일 수 있습니다.

Slack Green Team