A server module for creating Slack apps in Swift
Swift Ruby
Switch branches/tags
Nothing to show

README.md

SKServer: SlackKit Server Module

Swift Version Plaforms License MIT SwiftPM compatible Carthage compatible CocoaPods compatible

A server-side Swift module for creating Slack apps.

Installation

CocoaPods

Add SKServer to your pod file:

use_frameworks!
pod 'SKServer'

and run

# Use CocoaPods version >= 1.1.0
pod install

Carthage

Add SKServer to your Cartfile:

github "SlackKit/SKServer"

and run

carthage bootstrap

Drag the built SKServer.framework into your Xcode project.

Swift Package Manager

Add SKServer to your Package.swift

import PackageDescription
  
let package = Package(
	dependencies: [
		.Package(url: "https://github.com/SlackKit/SKServer.git", majorVersion: 4)
	]
)

Run swift build on your application’s main directory.

To use the library in your project import it:

import SKServer

Usage

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)