Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
..
Failed to load latest commit information.
Sources
README.md
SKServer.xcconfig

README.md

SKServer

A server-side Swift framework for creating Slack apps.

Installation

Swift Package Manager Add SlackKit as a dependency to your Package.swift and specify SKServer as a target dependency:
import PackageDescription
  
let package = Package(
    name: "SampleApp",
    products: [
        .executable(
            name: "SampleApp",
            targets: ["SampleApp"]),
    ],
    dependencies: [
        .package(url: "https://github.com/pvzig/SlackKit.git", .upToNextMinor(from: "4.3.0")),
    ],
    targets: [
        .target(
            name: "SampleApp",
            dependencies: ["SKServer"])
    ]
)
Carthage Add SlackKit to your Cartfile:
github "pvzig/SlackKit"

and run

carthage bootstrap

Drag the built SKServer.framework and it's dependencies SKCore.framework, SKWebAPI.framework, and Swifter.framework into your Xcode project.

CocoaPods Add SKServer to your Podfile:
use_frameworks!
pod 'SlackKit/SKServer'

Usage

To use the library in your project import it:

Carthage & SPM

import SKServer

CocoaPods

import SlackKit

The Basics

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

Initialize an instance of SKServer with a SlackKitResponder:

let middleware = ResponseMiddleware(token: "xoxp-SLACK_AUTH_TOKEN", response: SKResponse(text: "👋"))
let route = RequestRoute(path: "/hello", middleware: middleware)
let responder = SlackKitResponder(routes: [route])
// Without OAuth
let server = SKServer(responder: responder)
// With OAuth
let oauthConfig = OAuthConfig(clientID: "CLIENT_ID", clientSecret: "CLIENT_SECRET")
let server = SKServer(responder: responder, oauth: oauthConfig)
server.start()

OAuth is configured by default to use the /oauth route.

Middleware

Use the provided ResponseMiddleware to respond to requests:

let middleware = ResponseMiddleware(token: "xoxp-SLACK_AUTH_TOKEN", response: SKResponse(text: "👋"))

Or create your own custom middleware by conforming to the Middleware protocol:

public protocol Middleware {
    func respond(to request: (RequestType, ResponseType)) -> (RequestType, ResponseType)
}

RequestRoute

Use the RequestRoute type to assign a middleware to a specific route:

let route = RequestRoute(path: "/hello", middleware: middleware)

SlackKitResponder

Add your routes to a SlackKitResponder:

let responder = SlackKitResponder(routes: [route])

SKServer

Finally, initialize and start your SKServer:

let server = SKServer(responder: responder)
server.start()

Custom Integrations

Outgoing Webhook

To use an outgoing webhook, configure middleware and a route with the Slack verification token after configuring your outgoing webhook in Slack and pointing it at your server:

let outgoingMiddleware = ResponseMiddleware(token: "xoxp-SLACK_AUTH_TOKEN", response: SlackResponse(text: "Hello, 🌎", responseType: .inChannel))
let outgoingRoute = RequestRoute(path: "/world", middleware: outgoingMiddleware)
let responder = SlackKitResponder(routes: [outgoingRoute])
let server = SKServer(responder: responder)
server.start()

Slack App Features

Slash Commands

After configuring your slash command in Slack (you can also provide slash commands as part of a Slack App), create a route, response middleware for that route, and add it to a responder:

let middleware = ResponseMiddleware(token: "SLASH_COMMAND_TOKEN", response: SKResponse(text: "👋"))
let route = RequestRoute(path: "/hello", middleware: middleware)
let responder = SlackKitResponder(routes: [route])
let server = SKServer(responder: responder)
server.start()

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

Message Buttons

To use message buttons, create actions using the Action type and attach them to your SlackResponse as attachments:

let confirm = Action.Confirm(text: "Are you sure?", title: "Confirm", okText: "All Systems Go", dismissText: "Abort!")
let action = Action(name: "launch", text: "Blast Off!", style: .Danger, confirm: confirm)
let attachment = Attachment(fallback: "launch", title: "Misson Control", callbackID: "launch_id", actions: [action])
let response = SlackResponse(text: "T-Minus 10…", responseType: .InChannel, attachments: [attachment])

To respond to message button presses, create a MessageActionRoute for each action, with a corresponding middleware:

let responseMiddleware = ResponseMiddleware(token: "slack-verification-token", response: SlackResponse(text: "Initiate Launch Sequence"))
let messageActionRoute = MessageActionRoute(action: action, middleware: responseMiddleware)

Add your MessageActionRoute to a MessageActionResponder:

let responder = MessageActionResponder(routes: [messageActionRoute])

Finally, create a MessageActionMiddleware and specify the route to reach it:

let actionMiddleware = MessageActionMiddleware(token: "slack-verification-token", responder: responder)
let actionRoute = RequestRoute(path: "/actions", middleware: actionMiddleware)
let responder = SlackKitResponder(routes: [actionRoute])
let server = SKServer(responder: responder)
server.start()

Provide your own server implementation by conforming to SlackKitServer:

public protocol SlackKitServer {
	func start()
}
let server = YourServer()
let slackApp = SKServer(server: YourServer(), responder: aResponder)
You can’t perform that action at this time.