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.
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:
Add SlackKit to your pod file:
use_frameworks!
pod 'SlackKit', '~> 3.1.7'
and run
# Use CocoaPods version >= 1.1.0
pod install
Add SlackKit to your Cartfile:
github "https://github.com/pvzig/slackkit.git"
and run
carthage bootstrap
Drag the built SlackKit.framework into your Xcode project.
Add SlackKit to your Package.swift
import PackageDescription
let package = Package(
dependencies: [
.Package(url: "https://github.com/pvzig/SlackKit.git", majorVersion: 3)
]
)Run swift build on your application’s main directory.
To use the library in your project import it:
import SlackKit
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.
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)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)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()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")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.
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.meMessage
- 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)
})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.
connected(_ client: Client)
disconnected(_ client: Client)
connectionFailed(_ client: Client, error: SlackError)sent(_ message: Message, client: Client)
received(_ message: Message, client: Client)
changed(_ message: Message, client: Client)
deleted(_ message: Message?, client: Client)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)updated(_ status: DoNotDisturbStatus, client: Client)
userUpdated(_ status: DoNotDisturbStatus, user: User, client: Client)opened(_ group: Channel, client: Client)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)pinned(_ item: Item, channel: Channel?, client: Client)
unpinned(_ item: Item, channel: Channel?, client: Client)starred(_ item: Item, starred: Bool, _ client: Client)added(_ reaction: String, item: Item, itemUser: String, client: Client)
removed(_ reaction: String, item: Item, itemUser: String, client: Client)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)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)event(_ userGroup: UserGroup, client: Client)
selfAdded(_ subteamID: String, client: Client)
selfRemoved(_ subteamID: String, client: Client)changed(_ profile: CustomProfile, client: Client)
deleted(_ profile: CustomProfile, client: Client)
reordered(_ profile: CustomProfile, client: Client)