Slack WebAPIのドキュメントの見方と使い方

目次

本記事では、Slack APIをとりあえず使ってみることを目的とします。

1. Slack appを作成する。
2. ドキュメントを見る。
3. GASからWeb APIを使う。

Slack appを作成する

Slack APIを利用するためには、ワークスペースごとにSlack appを作成する必要があります。
https://api.slack.com/apps/
にアクセスし、「Create New App」のボタンを押します。
アプリ名とワークスペースを選択し、Createしてください。

左側のメニューで、アプリの機能ごとの設定を行うことができます。

まず、「OAuth&Permissions」の項目で、①アプリの権限を設定し、②トークンを取得します。

OAuth&Permission内のScopesの欄を見ます。Bot Token ScopesとUser Token Scopesがありますが、User Token Scopesはこのアプリを有効化したユーザーに依存する権限を設定するもので、通常はBot Token Scopesを設定することが多いです。

Bot Token Scopesの欄で設定したい権限を選択します。
権限は、ドキュメントを見ながら、使用したいメソッドに必要な権限を選択していくことになります。

たとえば、「chat:write」スコープは、Botがメッセージを投稿することを可能にする権限であり、chat.postMessageなどのメソッドを使用するのに必要となります。

適当な権限を付与したら、次にワークスペースにアプリをインストールし、トークンを取得します。

上部にある「Install App to Workspace」を押してください。

遷移した画面でインストールを許可すると、上の画像のように、トークンが現れます。このトークンを使って、今後APIを使用していくことになります。

ドキュメントを見る

SlackのAPIには、Web API、Event API、リアルタイムAPIなどの種類がありますが、ここではWeb APIのメソッドを見ていきます。

Web APIのメソッドは豊富に用意されており、たとえば、チャンネルにメッセージを投稿する、リアクションを付ける、チャンネルを作成する、など様々なことが可能です。

Web APIの一覧はこちらから見ることができます。
https://api.slack.com/web#methods

メソッドのドキュメントの見方

ここでは、chat.postMessageを詳しくみていきましょう。
chat.postMessageメソッドの詳細ページを開くと次のような画面が現れます。

ページの最初にそのメソッドで何ができるのかが書かれています。

Method URLは、リクエストを送る際に必要となるURLです。

Works withの欄には、このメソッドを使用するのに必要なスコープが書かれています。chat.postMessageメソッドの場合はchat:writeスコープが必要であることが分かります。

ページをスクロールすると「Arguments」の一覧を見ることができます。

ここには、このメソッドを利用する際に指定できる引数とその説明が書かれています。
Requiredと表示されている項目は、必ず指定しなければいけません。
chat.postMessageの場合、token、channel、textは必須項目であることが分かります。

テスターを利用する

ドキュメントページにあるTesterを利用することで、コードを書かずにAPIメソッドを実行することができます。（スコープの設定は必要です。）

上部のタブからTesterを開いてください。

タブを開くと、前述の引数を入力するフォームが現れます。
tokenには、スコープを適当に設定した、使用したいアプリのトークンを入力します。
channelやtextなどの項目にも、先ほどのドキュメントを見ながら適切な値を設定してください。
入力後に、下の方にある「Test Method」を押すとメソッドが実行されます。この場合には、Slackに投稿がなされるはずです。

エラーが出た場合は、エラーコードを確認します。各エラーコードの意味は、ドキュメントのページに記載されているので参照してください。

【補足】チャンネルID、ユーザーIDの確認方法

Slackには、チャンネルごとに割り振られているConversation ID、ユーザーごとに割り振られているUser IDがあります。（ワークスペースに割り振られているWorkspace IDもあります。）

確認方法はいくつかありますが、頻繁に使う場合に簡単なのは「Slack Developer Tools」を使う方法です。Slack公式アプリ「Slack Developer Tools」をワークスペースにインストールし、/sdt whoamiのコマンドを実行すると、各種ＩＤを教えてくれます。
また、Slack Developer Toolsを使うと、各投稿をJSON形式で見ることもできます。

Web APIを使う

いくつかのコードで、APIにリクエストを送る方法を紹介します。

GAS(Google Apps Script)

UrlFetchAppクラスを使用する例です。URLにクエストリングでパラメーターを付加できます。

postToSlackFromGas.js

var URL = "https://slack.com/api/chat.postMessage" //メソッドのURL
var SLACK_TOKEN = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" //引数tokenの値（環境変数に入れておいた方がよいです。）
var text = "Hello World" //引数textの値
var channelId = "CXXXXXXX"  //引数channelの値

var urlToFetch = URL+"?token="+SLACK_TOKEN+"&channel="+channelId+"&text="+text;
UrlFetchApp.fetch(urlToFetch);

Node.js

requestモジュールを使用する方法です。ドキュメント通りに設定します。こちらもトークンは環境変数に設定しておいた方がよいでしょう。

postToSlack.js

const request = require('request');

var options = {
    url: "https://slack.com/api/chat.postMessage",
    method: 'POST',
    headers: {
      "Content-type": "application/x-www-form-urlencoded"
    },
    form: {
      "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "channel": "CXXXXXX",
      "text": "Hello World"
    }
  };
request(options, function (error, response, body) { });