Slack Connector (experimental)

Post messages to a Slack workspace from a Caffeine canister.

⚠️ Experimental (
slack-client@0.0.3
). The request path is fixed and verified — a real
chat.postMessage
posts successfully against the live Slack API (the earlier query-vs-form bug is resolved; POST params now go in an
application/x-www-form-urlencoded
body). NOT yet runtime-verified: the success-response decode (
{"ok":true,…}
→ the success schema) and the
{"ok":false}
error envelope (see Known limitations). Treat as pre-release; don't advertise Slack as fully supported until a >= 0.1.0 release.

Orchestrator routing notes

Load this skill when the user, spec, or a prior task mentions Slack, posting to a channel, or notifying a Slack workspace. The generated

slack-client

package is the preferred path; raw

ic.http_request

https://slack.com/api/*

is an anti-pattern that re-implements auth, percent-encoding, and JSON parsing by hand.

Intent → capability mapping:

User intent	Capability
Post a message to a Slack channel as the app	`slack-client` `chatPostMessage` with a bot token ( `xoxb-` )
Post to Slack as a named person	`slack-client` `chatPostMessage` with a user token ( `xoxp-` )

Before generating code, report the token choice back to the prompting user (bot vs user — see Auth model for the one-line rule and the trade-offs) and tell them where to obtain it. They cannot proceed without pasting a token, so surfacing this early avoids an app that traps on first use.

Scope of this generated drop: the messaging-core families

chat

conversations

users

files

reactions

, and

pins

(10 API modules). Other Slack methods are out of scope until the spec is regenerated.

Auth model — bot token (

xoxb-

) or user token (

xoxp-

)

Both are bearer credentials and the client treats them identically, but they differ in who the workspace sees acting. Ask the prompting user which one they want before writing code, and state the trade-off — the answer changes what their app looks like in Slack, and it cannot be swapped later without a re-install.

The user wants messages to appear as…	Token	Consequences to report back
the app itself (posts show the app's name with an `APP` badge)	`xoxb-` (default — prefer this)	One workspace-wide credential, independent of any employee. The bot must be invited to every channel it posts in ( `/invite @YourApp` ), else Slack answers `not_in_channel` . Cannot see private channels or DMs it isn't in.
a specific person (posts show that human's name and avatar)	`xoxp-`	Every action is attributed to, and audited as, that person. Reaches whatever they can reach, no channel invite needed. Dies when they leave the workspace or revoke the app. Required for a few user-only APIs (e.g. `search.messages` ).

If the request is "post notifications/alerts from my app", that is

xoxb-

. Only choose

xoxp-

when the user explicitly wants messages to look like they came from a human, or needs a user-only API. Say which you picked and why.

Obtaining a bot token (

xoxb-

)

https://api.slack.com/apps → Create New App → From scratch, pick the workspace.
OAuth & Permissions → Scopes → Bot Token Scopes: add
```
chat:write
```
(plus
```
channels:read
```
,
```
reactions:write
```
, … only as needed).
Install to Workspace → authorize → copy the Bot User OAuth Token, which starts with
```
xoxb-
```
.
In Slack, invite the app to each target channel:
```
/invite @YourApp
```
. Skipping this is the most common first failure (
```
not_in_channel
```
).

Obtaining a user token (

xoxp-

)

Same app → OAuth & Permissions → Scopes → User Token Scopes (a separate list from bot scopes): add e.g.
```
chat:write
```
,
```
search:read
```
.
Install to Workspace (or Reinstall, if the app already exists) and authorize — the token represents whoever clicks Allow.
Copy the User OAuth Token, which starts with
```
xoxp-
```
.

A single admin-supplied

xoxp-

is supported by this recipe: it goes through the same setter and the same

config.auth

. What is out of scope here is per-user OAuth, i.e. each end-user authorising their own account — that needs a full redirect + code-exchange + refresh flow, for which no Slack helper exists yet. Do not attempt to hand-roll it.

Handing the token to the canister

Whichever flavour, the workspace admin pastes it into the canister through an admin-gated setter — gated on

AccessControl.hasPermission(state, caller, #admin)

. The token is held by the canister only and is never returned to the frontend.

⚠️ Never gate the setter on a first-caller-claims-ownership scheme. On the IC every unauthenticated caller is the same anonymous principal, so if an anonymous call claims ownership first, every anonymous caller passes the
caller == owner
check and can overwrite the workspace token. Use the authorization component's
#admin
permission, as the example below does.

The canister then hands that token to the client only through

config.auth = ?#bearer(token)

, which every method turns into an

Authorization: Bearer …

header. No method takes a token argument and no method puts the credential in the URL, so it cannot leak through a logged query string.

is_replicated = ?false

is REQUIRED

Every Slack outcall must set

is_replicated = ?false

on its

Config

Security. A replicated outcall repeats the request from every node in the subnet, each carrying the
```
Authorization: Bearer xoxb-…
```
/
```
xoxp-…
```
header — a leak from any node compromises the workspace token.
Billing & side effects. Replicated outcalls fan out to N identical API calls: ~13× the cycles and N duplicate messages posted to the channel.
Determinism. Slack responses carry per-request fields (message
```
ts
```
), so replicated consensus would fail; non-replicated bypasses consensus.

Backend

Add dependencies

The admin gate in the recipe below needs the authorization component alongside the client:

bash

mops add slack-client@0.0.3
mops add caffeineai-authorization@1.0.1

The generated function is

ChatApi.chatPostMessage(config, channel, asUser, attachments, blocks, iconEmoji, iconUrl, linkNames, mrkdwn, parse, replyBroadcast, text, threadTs, unfurlLinks, unfurlMedia, username)

. Pass empty strings /

false

for the options you don't use. The token is not an argument — it travels only in

config.auth

(see Auth model above); this holds for every method in the client.

motoko

import AccessControl "mo:caffeineai-authorization/access-control";
import MixinAuthorization "mo:caffeineai-authorization/MixinAuthorization";
import MixinSlackConfig "mixins/slack-config";
import MixinSlackMessaging "mixins/slack-messaging";

actor {
  let accessControlState = AccessControl.initState();
  include MixinAuthorization(accessControlState, null);

  // Admin-held Slack token, `xoxb-…` or `xoxp-…` — never returned to the frontend.
  let slackConfig = { var token : Text = "" };
  include MixinSlackConfig(accessControlState, slackConfig);
  include MixinSlackMessaging(slackConfig);
};

motoko

import AccessControl "mo:caffeineai-authorization/access-control";
import Runtime "mo:core/Runtime";

mixin (
  accessControlState : AccessControl.AccessControlState,
  slackConfig : { var token : Text },
) {
  public query func isSlackConfigured() : async Bool {
    slackConfig.token.size() > 0;
  };

  // Admin-only; accepts either token flavour. NOTE: `#admin` — never a
  // first-caller-claims-ownership check,
  // which the shared anonymous principal would defeat.
  public shared ({ caller }) func setSlackToken(token : Text) : async () {
    if (not AccessControl.hasPermission(accessControlState, caller, #admin)) {
      Runtime.trap("Unauthorized: Only admins can set the Slack token");
    };
    slackConfig.token := token;
  };
};

motoko

import Principal "mo:core/Principal";
import Runtime "mo:core/Runtime";
import { chatPostMessage } "mo:slack-client/Apis/ChatApi";
import { defaultConfig; type Config } "mo:slack-client/Config";

mixin (slackConfig : { var token : Text }) {
  // Non-replicated outcall carrying the Slack token as a bearer credential.
  func slackClientConfig(token : Text) : Config {
    {
      defaultConfig with
      auth = ?#bearer(token);
      is_replicated = ?false;
      max_response_bytes = ?(1_000_000 : Nat64);
    };
  };

  // Post `text` to `channel` (channel ID like "C012AB3CD" or "#general").
  // Returns the posted message timestamp (`ts`).
  public shared ({ caller }) func postSlackMessage(channel : Text, text : Text) : async Text {
    if (caller.isAnonymous()) Runtime.trap("Sign in to post to Slack");
    if (slackConfig.token.size() == 0) {
      Runtime.trap("Slack is not configured (an admin must set the token)");
    };
    let res = await* chatPostMessage(
      slackClientConfig(slackConfig.token), // token rides config.auth — never a URL param
      channel,
      "", "", "", "", "", // asUser, attachments, blocks, iconEmoji, iconUrl
      false, // linkNames
      true, // mrkdwn
      "", // parse
      false, // replyBroadcast
      text, // text
      "", // threadTs
      false, // unfurlLinks
      false, // unfurlMedia
      "", // username
    );
    res.ts;
  };
};

Known limitations (experimental)

{"ok": false}
envelope. Slack signals logical failures (bad token, missing scope, channel not found) as
```
{"ok": false, "error": "…"}
```
over HTTP 200. The status-code-based error path does not see those, and the body fails to convert into the success schema, so the call rejects (
```
Error.reject
```
, i.e. a failed
```
await
```
) instead of returning a value. Handle it as a rejected call —
```
try { … } catch (e) { Error.message(e) }
```
; with
```
diagnostics
```
on that message carries the raw Slack body, including Slack's
```
error
```
string. Do not write
```
if (res.ok) …
```
: a returned value has already decoded, so
```
ok
```
is always
```
true
```
there and the check is dead code. A
```
responseEnvelope
```
/
```
okEnvelope
```
generator feature that turns this into a clean error value is the next fix.
Reachability (IPv4) — no proxy needed.
```
slack.com
```
is IPv4-only, which used to put it out of reach of IC HTTPS outcalls. Since 2025-08-04 the IC tries a direct (IPv6) connection and automatically retries through an IC-managed SOCKS proxy when that fails, so IPv4-only hosts work: leave
```
config.baseUrl
```
at the default
```
https://slack.com/api
```
. The TLS session is end-to-end between node and Slack, so the proxy sees only ciphertext. Expect some added latency on the fallback path (non-replicated outcalls are also the slower path — see above).
Auth is header-based, for every method. The token rides the
```
Authorization: Bearer
```
header only — never in the URL, so it cannot land in a logged query string, and it is never a method argument.
Partial runtime verification. The request shape is proven against live Slack (a real post lands); the success-response decode is not yet runtime-confirmed —
```
diagnostics
```
is on, so any decode failure surfaces the raw Slack body. The schema is also generated from an archived (~2020) spec revision.

connector-slack

NPX Install

Tags

SKILL.md Content

Slack Connector (experimental)

Orchestrator routing notes

Auth model — bot token (
`xoxb-`
) or user token (
`xoxp-`
)

Obtaining a bot token (
`xoxb-`
)

Obtaining a user token (
`xoxp-`
)

Handing the token to the canister

`is_replicated = ?false`
is REQUIRED

Backend

Add dependencies

Known limitations (experimental)

connector-slack

NPX Install

Tags

SKILL.md Content

Slack Connector (experimental)

Orchestrator routing notes

Auth model — bot token (xoxb-) or user token (xoxp-)

Obtaining a bot token (xoxb-)

Obtaining a user token (xoxp-)

Handing the token to the canister

is_replicated = ?false is REQUIRED

Backend

Add dependencies

Known limitations (experimental)

Auth model — bot token (
`xoxb-`
) or user token (
`xoxp-`
)

Obtaining a bot token (
`xoxb-`
)

Obtaining a user token (
`xoxp-`
)

`is_replicated = ?false`
is REQUIRED