Slack's newest coworker never logs off

Text your agent on Slack. Your agent is an app in your workspace that needs no public address, and answers you and the chats you share it with.

lnk agent start               # your agent, unless it runs already
lnk agent connect slack       # make the app, paste its two tokens, send it the code

Connect it

lnk opens Slack's page for a new app, already filled in. Create it in your workspace, then paste the app-level token (Basic Information > App-Level Tokens, with connections:write) and, once you install the app, its bot token. Send the bot the code in a direct message within 10 minutes. Link opens Socket Mode before displaying the code, receives your direct message there and acknowledges the event. It does not poll your direct-message history to pair you.

lnk agent connect slack

An app made before

If an earlier try made the app, open it at api.slack.com/apps and give lnk its tokens, rather than make another app.

Without prompts

From a script, give the tokens in their variables. They keep the tokens off the command line, which other users of this machine can see while lnk runs, and no flag takes them.

LNK_SLACK_APP_TOKEN=xapp-... LNK_SLACK_BOT_TOKEN=xoxb-... lnk agent connect slack   # from the variables

Photos and documents

For a harness that takes images and documents (Link Harness), the photos and documents a message holds go to the agent with its text: PNG, JPEG, GIF or WebP images and PDF or text documents, up to 10 MiB each and 8 a message, downloaded with the bot's token from Slack's own files.slack.com alone (the app's files:read scope).

What it leaves out

Anything else, a voice note or a video, is named to the agent as left out; sent alone, it's answered with what the agent reads. For another harness, a message holding only them is answered "I can read text only, for now."

In a channel

Mention the app in a channel and it answers in a thread on your message. Each Slack thread is a conversation of its own: mention it again in that thread and it carries on there; mention it in a new message and it starts afresh. Your direct messages to it are one conversation.

Share a channel

Mention the bot with the one-time code share prints, in the channel, within ten minutes. Anyone there in your workspace can then mention it, and the agent knows their name and who sent each message.

lnk agent share add slack
lnk agent share list
lnk agent share remove general --connection slack

Who stays out

Their direct messages stay private to you. Only a paired user's code shares a channel, and bots and members of other workspaces in Slack Connect stay out.

What it gives them

Everyone in a shared channel can use everything the agent reaches, including its files and memory, on your bill: make a separate agent for separate files. Sharing needs a harness that reads who is speaking, and group answers on.

When Slack pushes its messages

At home, the app runs in Socket Mode: Link connects out to Slack, and nothing on your machine listens. On a machine that packs agents, which runs each only while it answers, Slack pushes the app's messages to an address instead, by its Events API (lnk-slack hook).

Its two secrets come with the push

lnk agent connect slack keeps neither the app's signing secret nor a configuration token, which can edit your Slack apps. Whatever pushes the agent's messages gives them to hook in the app's settings (signing_secret, config_token). The configuration token is used for the switch and never kept.

Without the signing secret

Without the signing secret, hook says where it is, Basic Information and then App Credentials on the app's page, and switches nothing, so the app stays in Socket Mode.

Switching the app

With the app's configuration token, Link turns Socket Mode off and sets the request URL itself, in the app's manifest (apps.manifest.export and apps.manifest.update), and back when the pushes stop. Slack checks the address as it's saved (url_verification), and Link answers.

Two steps, by hand

Without a configuration token, or once Slack refuses it (one lasts 12 hours), Link gives you two steps on the app's page: Socket Mode off, then Event Subscriptions' Request URL.

What's read

Slack signs each push with the app's signing secret. Link drops one whose signature is wrong, or whose timestamp is more than 5 minutes from now, and reads the rest as the bridge does: your direct messages, your mentions of the app, and members' mentions in the channels you share. A push Slack sends again has the same event id, so it's answered once. Security has how a push is checked, and how the signing secret rolls.

Answers

Answers are posted with the bot token, as at home: Slack takes no answer in a push's response. When Slack refuses the bot token (revoked, or the app uninstalled), answering, or lnk-slack send, says so as its own failure, apart from any other. So does an answer Slack refuses, its conversation gone or archived, or the app no longer in it.

Where the secrets stay

A signing secret and configuration token stay outside the sandbox, with the tokens: a harness that speaks Slack is never handed them. A connection made before keeps them, until it's connected again.

Disconnect

disconnect forgets Slack's tokens and restarts your agent if it runs. The app stays yours, so delete it at api.slack.com/apps if you no longer want it.

lnk agent disconnect slack

When it doesn't work: Troubleshooting.

Docs

  • Security: How a push from Slack is checked on a machine that packs agents (When Slack pushes its messages), beyond what every webhook's secret gets (Link's Credentials page)
  • Decisions: Why the Slack plugin gives each agent an app of its own, and how it hears messages
  • Troubleshooting: What to do when your agent's Slack app doesn't connect, or its messages don't arrive (Slack)