はじめに

こんにちは！大ちゃんの駆け出し技術ブログです。

今回は自分が今まで使用してきたSlack のAPIのメソッドをまとめてみました！メソッドの使用方法と使用するために必要なscopeなどを載せておきます。1から詳しくは説明しませんがメソッドでできることを大まかにお伝えできたらと思います。

※「scopeとはなんぞ？」と思った方は以前自分が書いた記事のscopeの節を読んでいただければと思います。

【Slack API】user scopeとbot scope - 大ちゃんの駆け出し技術ブログ

users.identity

「Sign in with Slack」でトークンを取得した後に、ユーザに関する情報を取得するメソッド。

【概要】

メソッドのURL: https://slack.com/api/users.identity
推奨HTTPメソッド: GET
必要なscope: identity.basic(tokenの種類: user)

取得できる情報

ユーザの名前
ユーザのID
ユーザのいるワークスペースのID

【JSON】

{
    "ok": true,
    "user": {
        "name": "Sonny Whether",
        "id": "U0G9QF9C6"
    },
    "team": {
        "id": "T0G9PQBBK"
    }
}

【公式サイト】

api.slack.com

以下の3つのscopeを追加で付与することで取得するユーザ情報を増やすことができます。

identity.email
identity.avatar
identity.team

【identity.emailを追加した場合のJSON】

{
    "ok": true,
    "user": {
        "name": "Sonny Whether",
        "id": "U0G9QF9C6",
        "email": "bobby@example.com" // emailアドレスの追加
    },
    "team": {
        "id": "T0G9PQBBK"
    }
}

【identity.avatarを追加した場合のJSON】

{
    "ok": true,
    "user": {
        "name": "Sonny Whether",
        "id": "U0G9QF9C6",
                // 各サイズごとの画像の追加(数字はサイズを表している)
        "image_24": "https://cdn.example.com/sonny_24.jpg",
        "image_32": "https://cdn.example.com/sonny_32.jpg",
        "image_48": "https://cdn.example.com/sonny_48.jpg",
        "image_72": "https://cdn.example.com/sonny_72.jpg",
        "image_192": "https://cdn.example.com/sonny_192.jpg"
    },
    "team": {
        "id": "T0G9PQBBK"
    }
}

【identity.teamを追加した場合のJSON】

{
    "ok": true,
    "user": {
        "name": "Sonny Whether",
        "id": "U0G9QF9C6"
    },
    "team": {
        "name": "Captain Fabian's Naval Supply", // teamの名前の追加
        "id": "T0G9PQBBK"
    }
}

基本的にidentity.basicのJSONレスポンスだけだと不十分なので、identity.avatarなどを追加で付与することが多いのかなと思っています。

conversations.list

ワークスペースにあるチャンネルをリストとして返してくれるメソッド。

【概要】

メソッドのURL: https://slack.com/api/conversations.list
推奨HTTPメソッド: GET
必要なscope: channels:read, groups:read, im:read, mpim:read(tokenの種類: bot)

取得できる情報

ワークスペースのチャンネルリスト
チャンネルごとの名前やID、その他細かい情報

【JSON】

{
    "ok": true,
    "channels": [
        {
            "id": "C012AB3CD",
            "name": "general",
            "is_channel": true,
            "is_group": false,
            "is_im": false,
            "created": 1449252889,
            "creator": "U012A3CDE",
            "is_archived": false,
            "is_general": true,
            "unlinked": 0,
            "name_normalized": "general",
            "is_shared": false,
            "is_ext_shared": false,
            "is_org_shared": false,
            "pending_shared": [],
            "is_pending_ext_shared": false,
            "is_member": true,
            "is_private": false,
            "is_mpim": false,
            "topic": {
                "value": "Company-wide announcements and work-based matters",
                "creator": "",
                "last_set": 0
            },
            "purpose": {
                "value": "This channel is for team-wide communication and announcements. All team members are in this channel.",
                "creator": "",
                "last_set": 0
            },
            "previous_names": [],
            "num_members": 4
        },
        {
            "id": "C061EG9T2",
            "name": "random",
            "is_channel": true,
            "is_group": false,
            "is_im": false,
            "created": 1449252889,
            "creator": "U061F7AUR",
            "is_archived": false,
            "is_general": false,
            "unlinked": 0,
            "name_normalized": "random",
            "is_shared": false,
            "is_ext_shared": false,
            "is_org_shared": false,
            "pending_shared": [],
            "is_pending_ext_shared": false,
            "is_member": true,
            "is_private": false,
            "is_mpim": false,
            "topic": {
                "value": "Non-work banter and water cooler conversation",
                "creator": "",
                "last_set": 0
            },
            "purpose": {
                "value": "A place for non-work-related flimflam, faffing, hodge-podge or jibber-jabber you'd prefer to keep out of more focused work-related channels.",
                "creator": "",
                "last_set": 0
            },
            "previous_names": [],
            "num_members": 4
        }
    ],
    "response_metadata": {
        "next_cursor": "dGVhbTpDMDYxRkE1UEI="
    }
}

【公式サイト】

api.slack.com

少しわかりづらい値としてis_channelなどがあるかと思いますが、それも公式で説明してくれています。

conversation type

調べてみると同じような情報が乱立しているようです。数が多いので抜粋して説明します。

is_channel・・・チャンネルがパブリックチャンネルであればtrue、プライベートであればfalseを返す
is_group・・・チャンネルがパブリックチャンネルであればfalse、プライベートであればtrueを返す
is_im・・・DMの会話であるかどうか
created・・・unixのタイムスタンプ
creator・・・チャンネルを作成したユーザのID

ちなみに必要なscopeはchannels:read, groups:read, im:read, mpim:readと書かれていますが、全ての説明が必要と言うわけではありません。users.identityの時と同じようにscopeによって取得できるチャンネルの種類が変わります。

channels:read・・・ワークスペース内のパブリックチャンネル
groups:read・・・アプリボットが参加しているチャンネル
im:read・・・アプリボットがDMを送った会話
mpim:read・・・アプリボットがグループにDMを送った会話

conversations.create

ワークスペース内にチャンネルを作成するメソッド。

【概要】

メソッドのURL: https://slack.com/api/conversations.create
推奨HTTPメソッド: POST
必要なscope: channels:manage, groups:write, im:write, mpim:write(tokenの種類: bot)
必要な値: name(作成するチャンネルの名前)

取得できる情報

作成したチャンネル
チャンネルの名前やID、その他細かい情報

【JSON】

{
    "ok": true,
    "channel": {
        "id": "C0EAQDV4Z",
        "name": "endeavor",
        "is_channel": true,
        "is_group": false,
        "is_im": false,
        "created": 1504554479,
        "creator": "U0123456",
        "is_archived": false,
        "is_general": false,
        "unlinked": 0,
        "name_normalized": "endeavor",
        "is_shared": false,
        "is_ext_shared": false,
        "is_org_shared": false,
        "pending_shared": [],
        "is_pending_ext_shared": false,
        "is_member": true,
        "is_private": false,
        "is_mpim": false,
        "last_read": "0000000000.000000",
        "latest": null,
        "unread_count": 0,
        "unread_count_display": 0,
        "topic": {
            "value": "",
            "creator": "",
            "last_set": 0
        },
        "purpose": {
            "value": "",
            "creator": "",
            "last_set": 0
        },
        "previous_names": [],
        "priority": 0
    }

【公式サイト】

api.slack.com

こちらのメソッドではURLに作成するチャンネル名を含める必要があります。

def create_channel_in_team(channel_name, access_token)
  encoded_name = URI.encode_www_form_component(channel_name)
  access_token.post("api/conversations.create?name=#{encoded_name}&pretty=1").parsed
end

こちらのメソッドも複数のscopeを必要としますが、channels:manageとgroups:writeで使い分ける必要がありそうです。

channels:manage・・・新規チャンネルの作成権限とアプリボットが参加しているパブリックチャンネルの管理権限(チャンネル名を変えたり、チャンネルのトピックを追加するなどの権利)
groups:write・・・新規チャンネルの作成権限とアプリボットが参加しているプライベートチャンネルの管理権限(チャンネル名を変えたり、チャンネルのトピックを追加するなどの権利)
im:write・・・ダイレクトメッセージの開始
mpim:write・・・複数人とのダイレクトメッセージの開始

パブリックチャンネルを作成する場合channels:manageを、プライベートチャンネルを作成する場合はgroups:writeを使用しましょう。

conversations.invite

チャンネルにユーザを参加させるメソッド。

【概要】

メソッドのURL: https://slack.com/api/conversations.invite
推奨HTTPメソッド: POST
必要なscope: channels:manage, groups:write, im:write, mpim:write(tokenの種類: bot)
必要な値: channel(招待するチャンネルのID), users(招待するユーザのリスト)

取得できる情報

招待したチャンネル
チャンネルの名前やID、その他細かい情報

【JSON】

{
    "ok": true,
    "channel": {
        "id": "C012AB3CD",
        "name": "general",
        "is_channel": true,
        "is_group": false,
        "is_im": false,
        "created": 1449252889,
        "creator": "W012A3BCD",
        "is_archived": false,
        "is_general": true,
        "unlinked": 0,
        "name_normalized": "general",
        "is_read_only": false,
        "is_shared": false,
        "is_ext_shared": false,
        "is_org_shared": false,
        "pending_shared": [],
        "is_pending_ext_shared": false,
        "is_member": true,
        "is_private": false,
        "is_mpim": false,
        "last_read": "1502126650.228446",
        "topic": {
            "value": "For public discussion of generalities",
            "creator": "W012A3BCD",
            "last_set": 1449709364
        },
        "purpose": {
            "value": "This part of the workspace is for fun. Make fun here.",
            "creator": "W012A3BCD",
            "last_set": 1449709364
        },
        "previous_names": [
            "specifics",
            "abstractions",
            "etc"
        ]
    }
}

【公式サイト】

api.slack.com

こちらのメソッドではURLに招待するチャンネルのIDと招待するユーザのID群を含める必要があります。以下の例は1人のユーザを招待しています。

def try_invite_user(info, channel, access_token)
    channel_id = channel.dig("id")
    user_id = info.dig("user", "id")
    access_token.post("api/conversations.invite?channel=#{channel_id}&users=#{user_id}&pretty=1").parsed
  end

conversations.createでチャンネルを作成し、conversations.inviteでそのチャンネルに招待するという流れになるかと思うので、必要となるscopeについてはconversations.createと同じかと思います。

chat.postMessage

メッセージを送信するためのメソッド。Slack APIに関する記事の例で最も使われるメソッドです。

【概要】

メソッドのURL: https://slack.com/api/chat.postMessage
推奨HTTPメソッド: POST
必要なscope: chat:write(tokenの種類: bot)
必要な値: channel(送信するチャンネルのID)

取得できる情報

送信したしたチャンネルのID
送信したメセージの内容

【JSON】

{
    "ok": true,
    "channel": "C1H9RESGL",
    "ts": "1503435956.000247",
    "message": {
        "text": "Here's a message for you",
        "username": "ecto1",
        "bot_id": "B19LU7CSY",
        "attachments": [
            {
                "text": "This is an attachment",
                "id": 1,
                "fallback": "This is an attachment's fallback"
            }
        ],
        "type": "message",
        "subtype": "bot_message",
        "ts": "1503435956.000247"
    }
}

【公式サイト】

api.slack.com

こちらのメソッドではURLに招待するチャンネルのIDを含める必要があります。しかし、チャンネルのIDの代わりにユーザのIDを指定するとユーザにDMを送信することができます。

def post_direct_message_to_user(info, access_token)
  user_id = info.dig("user", "id")
  encoded_mgs = get_msg
  text = "こんにちは"
  encoded_text = URI.encode_www_form_component(text)
  access_token.post("api/chat.postMessage?channel=#{user_id}&blocks=#{encoded_mgs}&text=#{encoded_text}&pretty=1").parsed
end

また、送信するメッセージとして、text(テキスト)、blocks(Block Kit)、もしくはattachments(添付)のどれかを必ず値としてURLに含める必要があります。そうでないとno_textというエラーを返します。

必要なscopeは1つのみです。基本的にアプリbotからメッセージに送信をすることはSlack アプリを作成すると必ず必要になると思いますので以下のscopeは覚えておきましょう。

chat:write・・・アプリbotからメッセージを送信する権限

参考

api.slack.com

大ちゃんの駆け出し技術ブログ

RUNTEQ受講生のかわいいといわれるアウトプットブログ

【Slack API】APIメソッドまとめ

はじめに

users.identity

conversations.list

conversations.create

conversations.invite

chat.postMessage

参考