Build Slack apps, in Swift

Overview

SlackKit

Build Status

Swift Version Plaforms License MIT SwiftPM compatible Carthage compatible CocoaPods compatible

SlackKit: Slack Apps in Swift

Description

SlackKit makes it easy to build Slack apps 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.

Installation

Swift Package Manager

Add SlackKit to your Package.swift

let package = Package(
	dependencies: [
		.package(url: "https://github.com/pvzig/SlackKit.git", .upToNextMinor(from: "4.6.0"))
	]
)

When built using Swift Package Manager, SlackKit includes the vapor websocket framework by default which requires libressl.

You can install it with homebrew: brew install libressl

For additional details, see the SKRTMAPI readme.

Carthage

Add SlackKit to your Cartfile:

github "pvzig/SlackKit"

SlackKit is now using .xcframeworks. When building your dependencies with carthage, please specify a platform: carthage bootstrap --use-xcframeworks --platform macos

CocoaPods

Add SlackKit to your Podfile:

pod 'SlackKit'

Usage

To use the library in your project import it:

import SlackKit

The Basics

Create a bot user with an API token:

import SlackKit

let bot = SlackKit()
bot.addRTMBotWithAPIToken("xoxb-SLACK-BOT-TOKEN")
// Register for event notifications
bot.notificationForEvent(.message) { (event, _) in
	// Your bot logic here
	print(event.message)
}

or create a ready-to-launch Slack app with your application’s Client ID and Client Secret:

import SlackKit

let bot = SlackKit()
let oauthConfig = OAuthConfig(clientID: "CLIENT_ID", clientSecret: "CLIENT_SECRET")
bot.addServer(oauth: oauthConfig)

or just make calls to the Slack Web API:

import SlackKit

let bot = SlackKit()
bot.addWebAPIAccessWithToken("xoxb-SLACK-BOT-TOKEN")
bot.webAPI?.authenticationTest(success: { (success) in
	print(success)
}, failure: nil)

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 slackkit = SlackKit()
let middleware = ResponseMiddleware(token: "SLASH_COMMAND_TOKEN", response: SKResponse(text: "👋"))
let route = RequestRoute(path: "/hello", middleware: middleware)
let responder = SlackKitResponder(routes: [route])
slackkit.addServer(responder: responder)

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

Message Buttons

Add message buttons to your responses for additional interactivity.

To send messages with actions, add them to an attachment and send them using the Web API:

let helloAction = Action(name: "hello", text: "🌎")
let attachment = Attachment(fallback: "Hello World", title: "Welcome to SlackKit", callbackID: "hello_world", actions: [helloAction])
slackkit.webAPI?.sendMessage(channel: "CXXXXXX", text: "", attachments: [attachment], success: nil, failure: nil)

To respond to message actions, add a RequestRoute with MessageActionMiddleware using your app’s verification token to your SlackKitResponder:

let response = ResponseMiddleware(token: "SLACK_APP_VERIFICATION_TOKEN", response: SKResponse(text: "Hello, world!"))
let actionRoute = MessageActionRoute(action: helloAction, middleware: response)
let actionMiddleware = MessageActionMiddleware(token: "SLACK_APP_VERIFICATION_TOKEN", routes:[actionRoute])
let actions = RequestRoute(path: "/actions", middleware: actionMiddleware)
let responder = SlackKitResponder(routes: [actions])
slackkit.addServer(responder: responder)

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.

For local development of things like OAuth, slash commands, and message buttons, you may want to use a tool like ngrok.

Advanced Usage

Don’t need the whole banana? Want more control over the low-level implementation details? Use the extensible frameworks SlackKit is built on:

Framework Description
SKClient Write your own client implementation
SKRTMAPI Connect to the Slack RTM API
SKServer Spin up a server for a Slack app
SKWebAPI Access the Slack Web API

Examples

You can find the source code for several example applications here.

Tutorials

Get In Touch

Twitter: @pvzig

Email: [email protected]

Comments
  • Unknown error (404) when sending message with question mark at the end

    Unknown error (404) when sending message with question mark at the end

    When trying to send message (bot.webApi?.sendMessage()) with text that has question mark (?) I get failure with unknownError type. When I removed this question mark my message got through. I think there is something wrong with escaping this sign from request url and it's messing with url query.

    bug 
    opened by ghost 9
  • How to observer changes in client?

    How to observer changes in client?

    I'm a bit confused how one would observe changes on the Client. A callback api would be appreciated. Essentially when messages are handled my client, state changes and etc. how would one go about observing these changes in a controller?

    enhancement 
    opened by hamin 7
  • channels.history is deprecated, should we migrate to conversations.history instead?

    channels.history is deprecated, should we migrate to conversations.history instead?

    I've just started playing around with SKWebAPI, and it seems like channelsHistory() fails since the whole family if channels* API methods is now deprecated and doesn't work for new apps already.

    I'd love to work on this and port the deprecated methods from channel* to conversations*, but I'm fairly new to Swift and will need your help reviewing my PRs. Should I work on that?

    opened by natikgadzhi 6
  • Issue with `slackFormatEscaping`

    Issue with `slackFormatEscaping`

    Hi :)

    I have some issues with the slackFormatEscaping function When I use it I am unable to make mentions because it escape the characters but after when URLQueryItem convert params it encodes this to Percent-encoding

    For the moment I have fork all the repositories to remove this function, Am I wrong or Am i missing something ?

    opened by PoissonBallon 6
  • Add support for Attachments

    Add support for Attachments

    I actually need support for Attachments in the app I'm working on. @muratayusuke's fork has this actually already done along with a bunch of other enhancements: https://github.com/muratayusuke/SlackKit/commit/0baf74dacb98c6a4d3186ef4ce2370bc5741e40d

    Would love to see a PR @muratayusuke to pull his fork's changes into upstream. If not I can always make a PR just for the Attachment support but really it would just be duplicating @muratayusuke's efforts. Thoughts?

    opened by hamin 6
  • Slack API expects token passed in Authorization header instead of a GET parameter?

    Slack API expects token passed in Authorization header instead of a GET parameter?

    The code I'm running to run is simple:

    let bot = SlackKit()
    bot.addWebAPIAccessWithToken(token)
    bot.webAPI?.conversationsList(success: { channels, nextCursor in
        print(channels)
    }, failure: { error in
        print(error.localizedDescription)
    })
    

    I traced the URLRequest being sent and it seems like the url is: https://slack.com/api/conversations.list?token=xoxb-SLACK-BOT-TOKEN

    I tried sending this same request with Postman and got this response:

    {
        "ok": false,
        "error": "invalid_auth"
    }
    

    But when I send a request to https://slack.com/api/conversations.list with the following header:

    Authorization: Bearer xoxb-SLACK-BOT-TOKEN
    

    it returns the expected response:

    {
        "ok": true,
        "channels": [
            {
    ...
    

    So I'm not sure why I'm the only one having the issue, but maybe it's because I created my app on the Slack Api portal yesterday and it uses this new header auth style?

    If that's the case, then it looks this library needs to be updated to pass the token in the Authorization header for new Slack Apps.

    Edit: Here's the changelog where they deprecated querystring authentication: https://api.slack.com/changelog/2020-11-no-more-tokens-in-querystrings-for-newly-created-apps

    opened by katzenbaer 5
  • Build fails on Ubuntu 18.04

    Build fails on Ubuntu 18.04

    Ubuntu 18.04.03, Swift 5.0.2, SlackKit "upToNextMinor 4.3.0"

    Build silently fails, final output from swift build --verbose is like this:

    /usr/bin/clang -target x86_64-unknown-linux --sysroot / -fPIC -g -O0 -DSWIFT_PACKAGE=1 -DDEBUG=1 -fblocks -fmodules -fmodule-name=CNIOOpenSSL -I /home/pseudo/gaijinbot/.build/checkouts/swift-nio-ssl/Sources/CNIOOpenSSL/include -fmodule-map-file=/home/pseudo/gaijinbot/.build/checkouts/swift-nio-ssl-support/module.modulemap -fmodules-cache-path=/home/pseudo/gaijinbot/.build/x86_64-unknown-linux/debug/ModuleCache -MD -MT dependencies -MF /home/pseudo/gaijinbot/.build/x86_64-unknown-linux/debug/CNIOOpenSSL.build/shims.c.d -c /home/pseudo/gaijinbot/.build/checkouts/swift-nio-ssl/Sources/CNIOOpenSSL/shims.c -o /home/pseudo/gaijinbot/.build/x86_64-unknown-linux/debug/CNIOOpenSSL.build/shims.c.o :

    . $

    bug SlackKit 
    opened by khakionion 5
  • iOS: Cocoapods framework not found SlackKit

    iOS: Cocoapods framework not found SlackKit

    I try install this framework via Cocoapods for iOS application. But can not import be cause of error:

    Showing Recent Messages :-1: framework not found SlackKit

    question 
    opened by tandinhle 5
  • `sendEphemeral` should have an equivalent `sendThreadedEphemeral`

    `sendEphemeral` should have an equivalent `sendThreadedEphemeral`

    Much like sendMessage has sendThreadedMessage. There is currently no way to respond in a thread with an ephemeral message.

    Alternatively, networkInterface could be exposed or another extension point could be added for library consumers, such as an "additionalParameters" function parameter that would allow passing in additional fields to help build the payload.

    Or perhaps there's something else I missed that might allow us to do this?

    enhancement SKWebAPI 
    opened by allenhumphreys 5
  • Type 'SlackKit' does not conform to protocol 'RTMAdapter'

    Type 'SlackKit' does not conform to protocol 'RTMAdapter'

    After dependencies update a few days ago I've got the error:

    Type 'SlackKit' does not conform to protocol 'RTMAdapter'
    

    Error repeats even after fresh install. Adding a stub for connectionClosed(with error: Error, instance: SKRTMAPI) method fixes the problem, but not sure that this is the proper solution (: Looks

    Is it only my problem or there some bug of SlackKit conformance to SKRTMAPI? Thanks in advance!

    bug 
    opened by ihityouback 5
  • Unable to build with Swift Package Manager

    Unable to build with Swift Package Manager

    Attempts to build recent versions of SlackKit fail when using SPM.

    Using the following steps, building an application including SlackKit fails when specifying version 4.2.0 rather than 4.1.0 (which still works):

    mkdir x6
    cd x6
    swift package init --type executable
    

    edit Package.swift to include dependencies

    swift package generate-xcodeproj
    open x6.xcodeproj
    

    build project using Xcode UI

    $ swift --version
    Apple Swift version 4.2.1 (swiftlang-1000.11.42 clang-1000.11.45.1)
    Target: x86_64-apple-darwin18.2.0
    

    Xcode Version 10.1 (10B61)

    Build errors are in dependencies of packages required by SlackKit. e.g.

    ... x6/.build/checkouts/swift-nio-ssl.git--5028798909648298346/Sources/CNIOOpenSSL/include/c_nio_openssl.h:17:10: fatal error: 'openssl/conf.h' file not found
    #include <openssl/conf.h>
             ^~~~~~~~~~~~~~~~
    1 error generated.
    

    I see this problem on both of my systems. Hopefully this isn't an embarrassing pilot error on my behalf.

    slackkit.bug.txt

    opened by ObscureBug 4
Releases(4.8.0)
Owner
Peter Zignego
iOS, Server-side Swift
Peter Zignego
The Swift-est way to build native mobile apps that connect to Salesforce.

Swiftly Salesforce is the Swift-est way to build native mobile apps that connect to Salesforce: Written entirely in Swift. Very easy to install and up

Michael Epstein 131 Nov 23, 2022
A Swift Framework build for the Ark Ecosystem

Introduction Overview SwiftyArk is a simple, lightweight framework for the Ark Ecosystem. SwiftyArk provides a simple wrapper for accessing Ark accoun

Andrew Walz 8 May 12, 2019
Wanikani-swift - Unofficial Swift client for the WaniKani API

WaniKani A Swift library and client for the WaniKani REST API. It currently supp

Aaron Sky 5 Oct 28, 2022
AWS Full Stack Swift with Apple CarPlay

This application demonstrates a full-stack Apple CarPlay app that uses Swift for both the UI and the backend services in AWS. The app accesses Lambda functions written in Swift and deployed from Docker images. The app accesses Amazon Location Service and a 3rd party weather api to display information in the vicinity of the user.

AWS Samples 100 Jan 6, 2023
A Swift wrapper for Foursquare API. iOS and OSX.

Das Quadrat Das Quadrat is Foursquare API wrapper written in Swift. Features Supports iOS and OSX. Covers all API endpoints. Authorization process imp

Constantine Fry 171 Jun 18, 2022
Pokeapi wrapper, written in Swift

PokemonKit What is this? PokemonKit is a swift wrapper for Pokeapi. PokemonKit use Alamofire and PromiseKit for async web requests handling. Usage imp

Continuous Learning 105 Nov 16, 2022
Unofficial GitHub API client in Swift

Github.swift ❤️ Support my apps ❤️ Push Hero - pure Swift native macOS application to test push notifications PastePal - Pasteboard, note and shortcut

Khoa 184 Nov 25, 2022
A swift SDK for Medium's OAuth2 API

Medium SDK - Swift A library to allow access to Medium API for any Swift iOS application. Features Medium.com authorization & token handling Login sta

null 11 Jan 22, 2022
A Twitter framework for iOS & OS X written in Swift

Getting Started Installation If you're using Xcode 6 and above, Swifter can be installed by simply dragging the Swifter Xcode project into your own pr

Matt Donnelly 2.4k Dec 30, 2022
👤 Framework to Generate Random Users - An Unofficial Swift SDK for randomuser.me

RandomUserSwift is an easy to use Swift framework that provides the ability to generate random users and their accompanying data for your Swift applic

Wilson Ding 95 Sep 9, 2022
Swift 3 framework for accessing data in Event Registry (http://eventregistry.org/)

PPEventRegistryAPI Swift 3 framework for accessing data in Event Registry (http://eventregistry.org/) Supported API calls Log In Get Event By Identifi

Pavel Pantus 8 Nov 1, 2016
Swift client for Unsplash

Unsplash API client written in Swift. Unsplash offers 2 APIs: Source API (unlimited requests) Official API JSON API (5000 requests / hour) JSON API is

Modo 188 Nov 12, 2022
An Elegant Spotify Web API Library Written in Swift for iOS and macOS

Written in Swift 4.2 Spartan is a lightweight, elegant, and easy to use Spotify Web API wrapper library for iOS and macOS written in Swift 3. Under th

Dalton Hinterscher 107 Nov 8, 2022
An Elegant Financial Markets Library Written in Swift

Notice As of May 20th, 2017, it appears that Yahoo is dropping support for a few features that BigBoard supports or there is an outage on their end ca

Dalton Hinterscher 66 Dec 7, 2022
Swift Wrapper For Bittrex API

BittrexApiKit Swift client for Bittrex api. It support all APIs with most recent changes. more info here let api = Bittrex(apikey: "api key", secretke

Saeid 8 Apr 5, 2021
iOS/macOS Cross-platform Ark-Ecosystem Framework in Swift | Powered by Ѧrk.io |

a macOS & iOS Swift Framework for Ark.io. What is ARKKit? ARKKit is wrapper for interacting with the Ark Ecosystem. It is written purely in Swift 4.0,

Simon 19 Jun 28, 2022
Instagram API client written in Swift

SwiftInstagram is a wrapper for the Instagram API written in Swift. It allows you to authenticate users and request data from Instagram effortlessly.

Ander Goig 579 Dec 31, 2022
The Waterwheel Swift SDK provides classes to natively connect iOS, macOS, tvOS, and watchOS applications to Drupal 7 and 8.

Waterwheel Swift SDK for Drupal Waterwheel makes using Drupal as a backend with iOS, macOS, tvOS, or watchOS enjoyable by combining the most used feat

Kyle Browning 414 Jul 26, 2022
A Swift library for the Forecast.io Dark Sky API

Requirements To use ForecastIO, all you need is an API key for the Dark Sky API. ForecastIO supports iOS (≥9.0), macOS (≥10.10), watchOS (≥2.0), and t

Satyam Ghodasara 163 Jul 26, 2022