Slackのfiles.uploadの廃止:代わりの3ステップのアップロード
files.uploadは今はmethod_deprecatedを返します。files.getUploadURLExternalでURLを受け取り、バイトをPOSTし、files.completeUploadExternalで共有します。SDKならfiles_upload_v2です。curlとPythonで試し、エラーなしで失敗する2つのケースも確かめました。
On this page
Slackの古い files.upload メソッドは廃止されました。2026年9月29日に、files:write のスコープを持つ私たちのボットで呼ぶと、{"ok": false, "error": "method_deprecated"} が返りました。代わりの方法は3回の呼び出しです。files.getUploadURLExternal がアップロード先のURLとファイルIDを返し、そのURLにファイルのバイトをPOSTし、files.completeUploadExternal でファイルをチャンネルに共有します。PythonとNodeのSDKは3つを1回の呼び出しにまとめていて、Pythonでは files_upload_v2、Nodeでは filesUploadV2 です。以下に、私たちが実行したcurlの版、Pythonの版、そして ok: true が返るのにファイルが壊れたり消えたりする2つの間違いを載せます。
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 の配列を受け取るので、アップロードした複数のファイルを1つのメッセージで共有できます。ファイル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 が返り、ファイルは下のスクリーンショットの2つ目のアップロードとしてチャンネルに出ました。v2の関数は単数の channel を受け取ります。古い関数は channels でした。同じ3ステップは動画のファイルでも動き、Slackはそれをプレーヤー用に変換します。アップロードしたあとにどの形式が再生できるかは、Slackの動画形式のテストにあります。
okが返るのに間違っている2つのアップロード
わざと2つの間違いを試しました。どちらもエラーは返りませんでした。
1つ目は、length=10 で頼んでおいて41バイトをすべて送る間違いです。ステップ2は OK - 10、ステップ3は ok: true と答え、Slackのファイルは10バイトで切れていました。スクリーンショットの3つ目のアップロードがそのファイルで、見出しの行が signu で終わっています。
ですから length は、エンコードする前の文字列の長さではなく、送るバイトから計算します。ASCII以外の文字を含むUTF-8のテキストでは、この2つが違います。アップロードした画像をファイルとしてではなくBlock Kitのメッセージの中に出すには、画像ブロックの slack_file にファイルIDを指定します。画像ブロックのテストでは、PNG、JPG、GIFは動き、WebPは動きませんでした。こうしてアップロードしたファイルは、Block Kitのメッセージの中にカードとして置くこともできます。ファイルブロックのテストでは、"source": "remote" とファイルIDで1つ投稿しました。
2つ目は、ステップ2を飛ばしたまま files.completeUploadExternal を呼ぶ間違いです。ok: true が返りましたが、ファイルはチャンネルに出ず、そのIDで files.info を呼ぶと file_not_found が返りました。アップロードが「成功」するのに何も出ないなら、ステップ2が実行されたか、その本文が OK - と自分のバイト数になっているかを確かめます。
ほかのツールからのアップロード
- • GitHub Actions:
slackapi/slack-github-actionにはfiles.uploadV2のメソッドがあります。ワークフローはGitHub ActionsからSlackにメッセージを送る方法にあります。 - • Incoming Webhookではファイルをアップロードできません。送れるのはテキストとブロックだけで、Webhookでのファイルのテストでは、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ステップの流れを使う版に更新します。
関連記事
Slack APIのconversations.listでチャンネル一覧:プライベートが消える理由
conversations.listはパブリックチャンネルをすべて返しますが、プライベートチャンネルはボットが入っているものしか返しません。2026年10月2日にボットトークンとユーザートークンで実行し、それぞれが返したものをそのまま載せます。
Slackのボットトークン:xoxb-トークンの場所と、xoxbとxoxpの違いを検証
Slackのボットトークンは、アプリのOAuth & PermissionsページにあるBot User OAuth Tokenで、xoxb-で始まります。アプリをインストールすると表示されます。取得の手順、SLACK_BOT_TOKENでの読み込み、xoxpのユーザートークン、xappのアプリレベルトークン、xoxeのローテーション、xoxcのセッショントークンとの違いをまとめました。
Slackの文字色:文字に色は付けられないが、色が出るものは3つ
Slackには、メッセージにもcanvasにも文字色の設定がなく、APIも色のスタイルを受け付けません。2026年9月29日にすべての方法を試しました。カラーコードには色見本が付き、インラインコードは赤になり、アプリのメッセージには色付きの線を付けられます。