Did you know ... | Search Documentation: |
Pack slack_prolog -- README.md |
This library provides a websocket API to slack
https://github.com/swi-to-yap/slack_prolog/
Run ?- pack_install(slack_prolog)
.
This is something done in Slack, under integrations. Create a new bot, and note its API token.
![](t/register-bot.png)
export SLACK_API_TOKEN=xoxb-01234567890-xxxxxxxxxxxxxxxx
The Real Time Messaging API is a WebSocket-based API that allows you to receive events from Slack in real time and send messages as user.
% navigats the web api and switches to the real time messaging system ?- Client = slack_client.clients.new(). ?- $Client.register(hello , debug.print. ["Successfully connected, welcome ", $Client.self.name, "to the '", $Client.team.name,"' team at https://", team.domain, ".slack.com."]). ?- $Client.register(message , data.text.contains("bot hi") -> message(channel: data.channel, text: ["Hi <@",data.user,">!"]) ; not(data.text.contains('bot')) -> message( channel: data.channel, text: ["Sorry <@",data.user,">, what?"])). ?- $Client.register(close , debug.print( "Client is about to disconnect")). % can register on the last created client (returned by slack_client.clients.new ) ?- slack_client.current.register(closed , debug.print. "Client has disconnected successfully!"). ?- $Client.start().
You can send typing indicators with typing
.
?- $Client.typing(channel: data.channel).
You can send a ping with ping
.
?- $Client.ping().
You can configure the RealTime client ping rate.
?- $Client.set(websocket_ping: 42).
By default, the RealTime client exposes and maintains a local store with the properties of rtm.start upon a successful connection.
property | description ---------|------------------------------------------------------------------------------------------------- url | A WebSocket Message Server URL. self | The authenticated bot user. team | Details on the authenticated user's team. users | A hash of user objects by user ID. channels | A hash of channel objects, one for every channel visible to the authenticated user. groups | A hash of group objects, one for every group the authenticated user is in. ims | A hash of IM objects, one for every direct message channel visible to the authenticated user. bots | Details of the integrations set up on this team. text | textual utils. debug | Debugger fidling. events | Registered callbacks. files | registered storage. |
It also tracks changes, such as users being renamed, added or deleted, therefore ?- $Client.users
is always up-to-date.
Tracking with a local store can be disabled with slack_client.new_client().(store_class: nil)
. Other stores are also available.
Send messages with chat_PostMessage.
?- $Client.chat_postMessage(channel: '#general', text: 'Hello World', as_user: true).
See a fully working example in t/first_slack_bot.pl
List channels with channels_list.
?- Channels = $Client.channels_list.channels. ?- General_channel = $Channels.detect{ c.name :< 'general' }.
Upload a file with files_upload.
?- $Client.files_upload( channels: '#general', as_user: true, file: slack_client.files.new_upload('/path/to/avatar.jpg', 'image/jpeg'), title: 'My Avatar', filename: 'avatar.jpg', initial_comment: 'Attached a selfie.' ).
You can use a channel ID or name (prefixed with #
) in all functions that take a `:channel argument.
Lookup by name is not supported by the Slack API and the
channels_id` method called invokes channels_list
in order to locate the channel ID.
?- $Client.channels_info(channel: 'C04KB5X4D'). # calls channels_info %% teh same command ?- $Client.channels.channels_info(channel: 'C04KB5X4D'). # calls channels_info
?- $Client.channels_info(channel: '#general'). # calls channels_list followed by channels_info
You can use a user ID or name (prefixed with @
) in all functions that take a `:user argument. Lookup by name is not supported by the Slack API and the
users_id` method called invokes users_list
in order to locate the user ID.
?- $Client.users_info(user: 'U092BDCLV'). # calls users_info
?- $Client.users_info(user: '@logicmoo'). # calls users_list followed by users_info
Constructs an in-memory index of users and searches it. If you want to use this functionality, add the picky gem to your project's Gemfile.
?- $Client.users_search(user: "logicmoo").
All text in Slack uses the same system of escaping: chat messages, direct messages, file comments, etc. Use prolog_client.text to unescape/2 incoming messages. This comes handy, for example, you want to treat all input to a real time bot as plain text.
?- $Client.text.unescape('Hello & <world>',OUT). OUT = "Hello & <world>" ?- prolog_client.text.unescape('Hey <@U024BE7LH|bob>, did you see my file?',OUT). OUT = "Hey @bob, did you see my file?" ?- $Client.text.unescape('Hey <@U02BEFY4U>',OUT). OUT = "Hey @U02BEFY4U" ?- $Client.text.unescape('This message contains a URL <http://foo.com/>',OUT). OUT = "This message contains a URL http://foo.com/" ?- $Client.text.unescape('So does this one: <http://www.foo.com|www.foo.com>',OUT). OUT = "So does this one: www.foo.com" ?- $Client.text.unescape('<mailto:bob@example.com|Bob>',OUT). OUT = "Bob" ?- $Client.text.unescape('Hello <@U123|bob>, say hi to <!everyone> in <#C1234|general>',OUT). OUT = "Hello @bob, say hi to @everyone in #general" ?- $Client.text.unescape('Hello <@U123|bob> > file.txt',OUT). OUT = "Hello @bob > file.txt" ?- $Client.text.unescape('�hello�',OUT). OUT = "\"hello\"" ?- $Client.text.unescape('�hello�',OUT). % sends: "'hello'"
Copyright (c) 2017, Douglas Miles
This project is licensed under the MIT License.
There're no hard rules about when to release slack_prolog. Release bug fixes frequently, features not so frequently and breaking API changes rarely.
Run tests, check that all tests succeed locally.
?- run_tests(slack_client).
Increment the version, modify pack.pl.
0.0.1
to 0.0.2
).0.0.1
to 0.2.0
).
### 0.0.2 (2/10/2017)
Remove the line with "Your contribution here.", since there will be no more contributions to this release.
Remove the "Stable Release" section in README that warns users that they are reading the documentation for an unreleased version.
Commit your changes.
git add README.md CHANGELOG.md pack.pl git commit -m "Preparing for release, 0.0.2." git push origin master
Release.
$ @TODO Tagged v0.0.2. Pushed git commits and tags. Pushed slack_prolog 0.0.2 to swi-prolog.org.
Add the next release to CHANGELOG.md.
Next Release ============ * Your contribution here.
Increment the third version number in pack.pl.
Commit your changes.
git add CHANGELOG.md pack.pl git commit -m "Preparing for next development iteration, 0.0.2." git push origin master
Document this pack! Write tests Untangle the 'pack' install deps Still in progress (Moving predicates over here from logicmoo_base)
Copyright (c) 2017, Douglas Miles <logicmoo@gmail.com> and TeamSPoon All rights reserved.
(Why feel obligated to maintain a git fork just to contribute ?)
Please ask to be added to TeamSPoon !