以前、Slack APIを使ったのですが、久しぶりに使おうとしたら完全に使い方を忘れていたので、また忘れた時用のSlack API使い方メモです。
ちなみにAPIでやりたかったことは下記のようなことです。
- 投稿(アプリとして)
- 投稿(ユーザーとして)
- ファイルアップロード
- ワークスペースのユーザー一覧取得
基本的な仕組み
基本的には、まずアプリを作成して、そのアプリをユーザーがワークスペースにインストールし、ユーザーがそのインストールされたアプリを介してAPIを使います。
Slackのデベロッパー向け機能には、Slackを操作するAPIだけでなく
- ユニークなURLを発行して、トークン無しでURLコールだけで投稿する機能
- 指定したURLにWebhookでイベント通知を受け取る機能
など、色々な機能があります。そして、何をするにもまずアプリを作成し、そのアプリをハブにして各種機能を開発していくスタイルになります。
手順(準備)
アプリの作成
Slack APIページに移動
[Building Slack apps]-[Create a Slack app]ボタンでアプリを作成
アプリはワークスペースにひも付きます。
アプリのインストール
上記でアプリが作成されるので、次に作成したアプリをユーザーがインストールして、APIを使えるようにします。
[Basic Information]-[Add features and functionality]-[Permissions] に移動
(「OAuth & Permissions」でも同じページに行けます)
ちょっと分かりにくいのですが、移動先のページ(OAuth & Permissions)で「どのAPIを使うかの設定」と「アプリのインストール」を行います。
[Scopes]-[Select Permission Scopes]で使いたいAPIを選択
[Save Changes]ボタンで使いたいAPIを登録
例として下記のAPIを登録してみました。
- 投稿(アプリとして)
- chat:write:bot
- 投稿(ユーザーとして)
- chat:write:user
- ファイルアップロード
- files:write:user
- ユーザー一覧取得
- users:read
[OAuth Token & Redirect URLs]-[Install App to Workspace]でユーザー(自分)にアプリをインストール
すると自分にアプリが登録され、アクセストークンが発行されるので、以後このトークンを使ってAPIを呼び出します。
手順(APIを使う)
トークンはBearerトークンで、「Authorization」ヘッダーに「Bearer <トークン値>」を設定して使います。
他の設定はAPIによってまちまちなので、APIのリファレンスに合わせて設定します。
例)アプリとして投稿
import axios from 'axios'; (async () => { const token = `xoxp-XXXX`; const url = 'https://slack.com/api/chat.postMessage'; const result = await axios.request({ headers: { 'authorization': `Bearer ${token}` }, url, method: "POST", data: { channel: 'XXXX', text: 'Hello, World!', } }); console.log(result.data); })();
すると、こんな感じで投稿されます。
手順(API・アプリの追加・変更・削除方法)
自分が作成したアプリ一覧はSlack APIページの右上の「Your Apps」から行けます。
アプリ名をクリックすると、アプリの設定ページに移動します。
APIの追加・変更・削除
- アプリ設定ページの[OAuth & Permissions]-[Scopes]で行います。
- 変更した後は、[OAuth & Permissions]-[OAuth Tokens & Redirect URLs]-[Reinstall App]でトークンを再発行します。
- 今まで発行したトークンを無効にするのは[OAuth & Permissions]-[Revoke All OAuth Tokens]-[Revoke Tokens]で行います。
アプリの削除
インストールしたアプリをアンインストールするには、ワークスペースの「App +」から行います。
アプリそのものを削除するには、アプリ設定ページの[Delete App]-[Delete App]で行います。
手順(API情報収集)
API使用にあたり、どんなAPIがあって、どう使うかをリファレンスで調べる必要があります。 リファレンスの参照方法は下記のとおりです。
どんなAPIがあるかを調べる
Slack APIページの[Reference]-[Methods]にAPI一覧があるので、そこから使いたいAPIを探します。
APIの具体的な使い方を調べる
上記のAPI一覧からAPI名をクリックすると、URL・method・引数等の、API毎の使い方が載っています。
API使用例
例)ユーザーとして投稿
import axios from 'axios'; (async () => { const token = `xoxp-XXXX`; const url = 'https://slack.com/api/chat.postMessage'; const result = await axios.request({ headers: { 'authorization': `Bearer ${token}` }, url, method: "POST", data: { channel: 'XXXX', text: 'Hello, World!', as_user: true, // ユーザーとして投稿フラグ } }); console.log(result.data); })();
例)ファイルアップロード
import axios from 'axios'; import * as FormData from 'form-data'; import * as fs from 'fs'; (async () => { const token = `xoxp-XXXX`; const url = 'https://slack.com/api/files.upload'; const form = new FormData(); form.append('file', fs.createReadStream('./data/slack_logo.png')); form.append('filename', 'slack_logo.png'); form.append('channels', 'XXXX'); const result = await axios.request({ headers: { 'authorization': `Bearer ${token}`, ...form.getHeaders(), }, url, method: "POST", data: form }); console.log(result.data); });
補足説明
ファイルアップロードAPIのパラメータを自分で設定しようとするとハマりやすいです。
ファイルの中身を渡すだけではダメで、ファイルの種類を適切に設定しないとうまく行きません。
ファイルの種類を判定して設定するのはかなり手間なので、ライブラリがあるならそれに任せてしまった方がいいです。
ファイルアップロードは、いわゆるhtmlのファイルアップロード方法「multipart/form-data」が使えます。
サンプルでは、Node.jsで「multipart/form-data」を行うライブラリ「form-data」を使っていて、ライブラリがよしなにファイルの種類(content-type)を設定してくれています。
例)ワークスペースのユーザー一覧を取得
import axios from 'axios'; import * as qs from 'qs'; (async () => { const token = 'xoxp-XXXX'; const url = 'https://slack.com/api/users.list'; let cursor = ''; do{ const result:any = await axios.request({ headers: { 'authorization': `Bearer ${token}`, 'Content-Type': 'application/x-www-form-urlencoded', }, url, method: "POST", data: qs.stringify({ cursor, }) }); console.log(result.data); cursor = result.data.response_metadata.next_cursor; }while(cursor); })();
投稿関連APIメモ
APIを使って、主に投稿関連の操作をすることになるかと思いますが、用語が色々あって分かりにくいので簡単に解説しておきます。
投稿箇所
投稿ができる箇所は大きく下記の3箇所になります。
- ダイレクトメッセージ
- いわゆる対個人への直接メッセージ
- APIリファレンスでは「im」と記載されていたりします
- パブリックチャンネル
- 誰でも中を見ることができるチャンネル
- APIリファレンスでは「channel」と記載されていたりします
- プライベートチャンネル
- メンバー以外は見れないチャンネル
- APIリファレンスでは「group」と記載されていたりします
投稿方法
chat.postMessage
で投稿します。「chat」とありますが「投稿」のことで、ダイレクトメッセージ・パブリックチャンネル・プライベートチャンネル全て、
このAPIで投稿します。
投稿先の指定は「channel」にIDをセットして行います。「channel」とありますが、パブリックチャンネルのことではありません。
ダイレクトメッセージの場合は、送信相手のユーザーIDを「channel」に指定します。Slack的には、ダイレクトメッセージを「im channel」と呼んでいて、 ダイレクトメッセージはチャンネルの一種ということのようです。
ユーザーIDは、ユーザーのプロフィールを開いた時にURLの最後に表示されるIDです。投稿先をユーザー名で指定できないので、事前にユーザーIDを取得 しておく必要があります。
ユーザー名からIDを取り出すAPIは無いので、URLからIDをメモしておくか、conversations.list
でユーザー一覧を取得して自分で探すしかありません。
パブリックチャンネル・プライベートチャンネルのIDに関しても同様です。
投稿メッセージの識別方法
メッセージのユニークIDはなく、投稿先IDと、メッセージのタイムスタンプ「ts」の組み合わせでユニークメッセージとなります。 つまり、同一投稿先では「ts」は重複せずユニークになります。
返信
メッセージへ返信することができます。1つのメッセージに対して、複数の返信を受けることができますが、返信への返信はできません。
返信するには、投稿先を「channel」に、返信先のメッセージの「ts」を「thread_ts」に指定して投稿します。
おまけ(ボットを使う)
ボットとは?
アプリとしてAPIを実行するだけでなく、ボットを作成して、ボットとしてAPIを実行することも可能です。
ボットの作成は、アプリの設定ページの[Bot Users]から行えます。
ボットを追加すると、ボット用のトークンが発行されるので、アプリ・ユーザーとしてAPIの操作と、ボットとしてAPIの操作を使い分けることが可能になります。
トークンがボット専用になるだけで、APIの使い方はアプリの時と同じです。 APIを使うだけなら、ボットもアプリも大した違いはありません。
ボットとアプリの一番大きな違いは、ボットを登録するとWebHookでイベント通知をリアルタイムに受けられるようになるところです。 そのあたりの説明はAPIとは別の話になるので記事を分けました。
感想
正直、Slackの構成やUIが、いつまで経っても馴染めません…。
想像していたところに想像していたものが無く、なんか記憶に残らないのです…。
みんなよく使いこなせてるなぁ…。