connector-slack

name	connector-slack
description	EXPERIMENTAL, UNTESTED recipe for posting messages to a Slack workspace from a Caffeine canister via the `slack-client` mops package (Slack Web API). Use it when the user wants their app to send a message to a Slack channel — "post to Slack", "notify a channel", "send a Slack message", or equivalent. The client is a pre-release 0.0.3 drop (bot `xoxb-` or user `xoxp-` token): its request path is verified against the live Slack API (a real message posts), but the success-response decode is not yet runtime-confirmed, so treat it as a starting point and do NOT present Slack as a fully supported platform feature yet. Hand-rolling `ic.http_request` calls to `slack.com/api` is still the wrong move — prefer the generated client so bearer auth, percent-encoding, and JSON parsing come for free.
version	0.0.3
caffeineai-subscription	["none"]
compatibility	{"mops":{"slack-client":"0.0.3","caffeineai-authorization":"~1.0.1"}}

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 to 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-)

1. https://api.slack.com/apps → Create New App → From scratch, pick the workspace.
2. OAuth & Permissions → Scopes → Bot Token Scopes: add chat:write (plus channels:read, reactions:write, … only as needed).
3. Install to Workspace → authorize → copy the Bot User OAuth Token, which starts with xoxb-.
4. 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-)

1. Same app → OAuth & Permissions → Scopes → User Token Scopes (a separate list from bot scopes): add e.g. chat:write, search:read.
2. Install to Workspace (or Reinstall, if the app already exists) and authorize — the token represents whoever clicks Allow.
3. 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:

1. 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.
2. Billing & side effects. Replicated outcalls fan out to N identical API calls: ~13× the cycles and N duplicate messages posted to the channel.
3. 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:

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.

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);
};

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;
  };
};

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.