SlackKit: A Swift Slack Client Library

Description

This is a Slack client library for OS X, iOS, and tvOS written in Swift. It's intended to expose all of the functionality of Slack's Real Time Messaging API as well as the web APIs that are accessible to bot users. SlackKit also supports Slack’s OAuth 2.0 flow including the Add to Slack and Sign in with Slack buttons, incoming webhooks, slash commands, and message buttons.

This is the Swift 3 branch of SlackKit. SlackKit also has support for Swift 2.3 and Linux.

Building the SlackKit Framework

To build the SlackKit project directly, first build the dependencies using Carthage or CocoaPods. To use the framework in your application, install it in one of the following ways:

Installation

Carthage

Add SlackKit to your Cartfile:

github "https://github.com/pvzig/slackkit.git"

and run

carthage bootstrap

Note: SlackKit currently takes a long time for the compiler to compile with optimizations turned on. I'm currently exploring a potential fix for this issue. In the meantime, you may want to skip the waiting and build it in the debug configuration instead:

carthage bootstrap --configuration "Debug"

Drag the built SlackKit.framework into your Xcode project.

CocoaPods

Swift Package Manager

SlackKit doesn’t currently build correctly using CocoaPods or Swift Package Manager and Swift 3. I’m hoping to restore support for both soon.

To use the library in your project import it:

import SlackKit

Usage

OAuth

Slack has many different oauth scopes that can be combined in different ways. If your application does not request the proper OAuth scopes, your API calls will fail.

If you authenticate using OAuth and the Add to Slack or Sign in with Slack buttons this is handled for you.

If you wish to make OAuth requests yourself, you can generate them using the authorizeRequest function on SlackKit’s oauth property:

func authorizeRequest(scope:[Scope], redirectURI: String, state: String = "slackkit", team: String? = nil)

For local development of things like OAuth, slash commands, and message buttons that require connecting over https, you may want to use a tool like ngrok or localtunnel.

Incoming Webhooks

After configuring your incoming webhook in Slack, initialize IncomingWebhook with the provided URL and use postMessage to send messages.

let incoming = IncomingWebhook(url: "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX")
let message = Response(text: "Hello, World!")
incoming.postMessage(message)

Slash Commands

After configuring your slash command in Slack (you can also provide slash commands as part of a Slack App), initialize a webhook server with the token for the slash command, a configured route, and a response.

let response = Response(text: "Hello, World!", responseType: .InChannel)
let webhook = WebhookServer(token: "SLASH-COMMAND-TOKEN", route: "hello_world", response: response)
webhook.start()

When a user enters that slash command, it will hit your configured route and return the response you specified.

To add additional routes and responses, you can use WebhookServer’s addRoute function:

func addRoute(route: String, response: Response)

Message Buttons

If you are developing a Slack App and are authorizing using OAuth, you can use message buttons.

To send messages with actions, add them to an attachment:

let helloAction = Action(name: "hello_world", text: "Hello, World!")
let attachment = Attachment(fallback: "Hello World Attachment", title: "Attachment with an Action Button", callbackID: "helloworld", actions: [helloAction])

To act on message actions, initialize an instance of the MessageActionServer using your app’s verification token, your specified interactive messages request URL route, and a MessageActionResponder:

let action = Action(name: "hello_world", text: "Hello, World!")
let response = Response(text: "Hello, 🌎!", responseType: .InChannel)
let responder = MessageActionResponder(responses: [(action, response)])
let server = MessageActionServer(token: "SLACK-APP-VERIFICATION-TOKEN", route: "actions", responder: responder)
server.start()

Bot Users

To deploy a bot user using SlackKit you'll need a bearer token which identifies a single user. You can generate a full access token or create one using OAuth 2.

Initialize a SlackKit instance using your application’s Client ID and Client Secret to set up SlackKit for OAuth authorization:

let bot = SlackKit(clientID: "CLIENT_ID", clientSecret: "CLIENT_SECRET")

or use a manually acquired token:

let bot = SlackKit(withAPIToken: "xoxp-YOUR-SLACK-API-TOKEN")

Client Connection Options

You can also set options for a ping/pong interval, timeout interval, and automatic reconnection:

let options = ClientOptions(pingInterval: 2, timeout: 10, reconnect: false)
let bot = SlackKit(clientID: "CLIENT_ID", clientSecret: "CLIENT_SECRET", clientOptions: options)

Once connected, the client will begin to consume any messages sent by the Slack RTM API.

Web API Methods

SlackKit currently supports the a subset of the Slack Web APIs that are available to bot users:

• api.test
• auth.revoke
• auth.test
• channels.history
• channels.info
• channels.list
• channels.mark
• channels.setPurpose
• channels.setTopic
• chat.delete
• chat.postMessage
• chat.update
• emoji.list
• files.comments.add
• files.comments.edit
• files.comments.delete
• files.delete
• files.info
• files.upload
• groups.close
• groups.history
• groups.info
• groups.list
• groups.mark
• groups.open
• groups.setPurpose
• groups.setTopic
• im.close
• im.history
• im.list
• im.mark
• im.open
• mpim.close
• mpim.history
• mpim.list
• mpim.mark
• mpim.open
• oauth.access
• pins.add
• pins.list
• pins.remove
• reactions.add
• reactions.get
• reactions.list
• reactions.remove
• rtm.start
• stars.add
• stars.remove
• team.info
• users.getPresence
• users.info
• users.list
• users.setActive
• users.setPresence

They can be accessed through a Client object’s webAPI property:

client.webAPI.authenticationTest({(auth) in
	print(auth)
}, failure: {(error) in
	print(error)
})

Delegate methods

To receive delegate callbacks for events, register an object as the delegate for those events using the onClientInitalization block:

let bot = SlackKit(clientID: clientID, clientSecret: clientSecret)
bot.onClientInitalization = { (client: Client) in
    DispatchQueue.main.async(execute: {
	    client.messageEventsDelegate = self
    })
}

Delegate callbacks contain a reference to the Client where the event occurred.

There are a number of delegates that you can set to receive callbacks for certain events.

ConnectionEventsDelegate

connected(_ client: Client)
disconnected(_ client: Client)
connectionFailed(_ client: Client, error: SlackError)

MessageEventsDelegate

sent(_ message: Message, client: Client)
received(_ message: Message, client: Client)
changed(_ message: Message, client: Client)
deleted(_ message: Message?, client: Client)

ChannelEventsDelegate

userTypingIn(_ channel: Channel, user: User, client: Client)
marked(_ channel: Channel, timestamp: String, client: Client)
created(_ channel: Channel, client: Client)
deleted(_ channel: Channel, client: Client)
renamed(_ channel: Channel, client: Client)
archived(_ channel: Channel, client: Client)
historyChanged(_ channel: Channel, client: Client)
joined(_ channel: Channel, client: Client)
left(_ channel: Channel, client: Client)

DoNotDisturbEventsDelegate

updated(_ status: DoNotDisturbStatus, client: Client)
userUpdated(_ status: DoNotDisturbStatus, user: User, client: Client)

GroupEventsDelegate

opened(_ group: Channel, client: Client)

FileEventsDelegate

processed(_ file: File, client: Client)
madePrivate(_ file: File, client: Client)
deleted(_ file: File, client: Client)
commentAdded(_ file: File, comment: Comment, client: Client)
commentEdited(_ file: File, comment: Comment, client: Client)
commentDeleted(_ file: File, comment: Comment, client: Client)

PinEventsDelegate

pinned(_ item: Item, channel: Channel?, client: Client)
unpinned(_ item: Item, channel: Channel?, client: Client)

StarEventsDelegate

starred(_ item: Item, starred: Bool, _ client: Client)

ReactionEventsDelegate

added(_ reaction: String, item: Item, itemUser: String, client: Client)
removed(_ reaction: String, item: Item, itemUser: String, client: Client)

SlackEventsDelegate

preferenceChanged(_ preference: String, value: Any?, client: Client)
userChanged(_ user: User, client: Client)
presenceChanged(_ user: User, presence: String, client: Client)
manualPresenceChanged(_ user: User, presence: String, client: Client)
botEvent(_ bot: Bot, client: Client)

TeamEventsDelegate

userJoined(_ user: User, client: Client)
planChanged(_ plan: String, client: Client)
preferencesChanged(_ preference: String, value: Any?, client: Client)
nameChanged(_ name: String, client: Client)
domainChanged(_ domain: String, client: Client)
emailDomainChanged(_ domain: String, client: Client)
emojiChanged(_ client: Client)

SubteamEventsDelegate

event(_ userGroup: UserGroup, client: Client)
selfAdded(_ subteamID: String, client: Client)
selfRemoved(_ subteamID: String, client: Client)

TeamProfileEventsDelegate

changed(_ profile: CustomProfile, client: Client)
deleted(_ profile: CustomProfile, client: Client)
reordered(_ profile: CustomProfile, client: Client)

Examples

Check out example applications here.

Get In Touch

@pvzig

peter@launchsoft.co