Slack

Slack is in beta.

Connect your existing Inkbox identity to Slack. Each identity has its own Slack app, created in a workspace your organization has configured. The connection has its own permissions and disconnect action. Your agent can read accessible conversations and threads, send and edit messages, use reactions and pins, upload and download files, and receive Slack webhooks. Inkbox also captures retained message history for keyword search and controlled backfills. File bytes remain live reads, not archived copies. The SDK and CLI examples in this guide require version 0.7.11 or later.

Connect your workspace

Open your identity’s Slack page in the Inkbox Console, or go to Channels → Slack, choose Enable Slack, and select an agent.
For your first workspace, follow Your Slack apps, select the intended workspace, and generate an app-configuration access token and refresh token under Your App Configuration Tokens. Paste both into the Console. For later apps, the Workspace dropdown defaults to a saved workspace. Select Connect another workspace to enter a new token pair.
Choose Continue. Inkbox saves any new workspace credentials and starts preparing the agent’s app in one step.
After Preparing your Slack app… finishes, choose Add to Slack and approve access in Slack. The Console detects the connection and returns you to conversations.
Add the bot to the channels where it should participate.

Channels → Slack lists agents once their Slack apps have been created. Your organization can reuse saved workspace credentials when setting up other identity apps, or add a new token pair for a different workspace. Credentials are write-only; only verified workspace metadata is shown afterward. Each identity app connects to one workspace in this version and stays bound to the workspace selected during setup. This flow does not use client invitations or require enabling public distribution. Set the identity’s display name, description, and avatar before connecting. Apps created through Inkbox use that profile and sync later changes automatically, without reconnecting. Removing the avatar restores the Inkbox icon. Profile updates run in the background, so Slack may take a moment to display them. A workspace approval does not create a separate Inkbox identity. App preparation runs in the background and retries temporary limits automatically. Reloading resumes the same preparation. If configuration credentials need attention, update them before retrying. Installation is workspace-scoped, including individual workspaces in an Enterprise organization. Organization-wide Enterprise installations are not supported. Workspace installation and channel membership are separate. Installation does not grant access to every conversation or the workspace’s entire history. Private channels require an invitation from someone with the necessary permission. Slack workspace policies, app approval, granted permissions, and rate limits still apply. The Console and connection list report app creation, preparation status, and installation availability. Setup creates the app directly for an active identity; there is no separate identity setting to enable first. Live Slack operations require an active identity and a connected workspace. Pausing the identity stops live operations and agent webhook delivery while preserving connections and history. Eligible incoming messages can still be captured, and received deletions can remove saved content. Capture is independent of webhook event selection.

Start installation from code

Use an organization admin API key or the identity’s claimed agent key, save both workspace configuration tokens, then prepare the app with that saved workspace UUID. Wait for setup.status to be ready, then request the installation URL below. Open the returned URL in a browser; the SDK does not open it for you. Treat it as a secret, use it before expires_at, and finish approval in the same browser.

from inkbox import Inkbox

inkbox = Inkbox(api_key="YOUR_API_KEY")
installation = inkbox.slack.start_installation(
    "11111111-1111-4111-8111-111111111111"
)
# Open installation.authorization_url in a browser. Do not log it.

import { Inkbox } from "@inkbox/sdk";

const inkbox = new Inkbox({ apiKey: "YOUR_API_KEY" });
const installation = await inkbox.slack.startInstallation(
  "11111111-1111-4111-8111-111111111111",
);
// Open installation.authorizationUrl in a browser. Do not log it.

inkbox slack installation start \
  --identity-id 11111111-1111-4111-8111-111111111111

The default completion page is in the Inkbox Console. To choose an approved Console completion URL, pass return_url in Python, returnUrl in the TypeScript options, or --return-url in the CLI. Its path must be exactly /console/slack/complete; see installation options. Omitting this option keeps the default.

Contacts from Slack

When the agent encounters a human participant, Inkbox can match a confirmed Slack email to an existing organization contact or create a shared, unreviewed contact. Workspace and user IDs keep the account linked. Missing or unconfirmed email stays a Slack-only contact; a profile phone number is not automatically added as an active contact phone number. This does not import every channel member. See automatic contacts for copied fields and visibility.

Choose a workspace explicitly

Every live read, connection-specific archive read, file operation, and send uses a connection_id. Identity-level retained search can search all of the identity’s workspaces without selecting one. Get it from the connection list for your identity. Do not treat a Slack conversation ID as sufficient to select a workspace.

connections = inkbox.slack.list_connections(
    "11111111-1111-4111-8111-111111111111"
)
for connection in connections.connections:
    print(connection.id, connection.workspace_name, connection.status)

const connections = await inkbox.slack.listConnections(
  "11111111-1111-4111-8111-111111111111",
);
for (const connection of connections.connections) {
  console.log(connection.id, connection.workspaceName, connection.status);
}

inkbox slack connection list \
  --identity-id 11111111-1111-4111-8111-111111111111

curl "https://inkbox.ai/api/v1/slack/connections?identity_id=11111111-1111-4111-8111-111111111111" \
  -H "X-API-Key: YOUR_API_KEY"

Every organization member can set up Slack through the Console. Organization members in the Console, organization admin API keys, and claimed agent keys can save and reuse workspace credentials within their organization. Claimed keys can prepare and install apps, and read and use connections, only for their own identity. Disconnecting a workspace still requires the Console or an organization admin API key. Unclaimed keys cannot set up or use Slack.

Read and reply

Start with conversation discovery, then read messages or thread replies. Pagination is explicit. Request another page only when you need it and honor rate-limit responses. Send a channel message or supply the root message’s thread_ts to reply in a thread:

action = inkbox.slack.send_message(
    "22222222-2222-4222-8222-222222222222",
    conversation_id="C0123456789",
    text="I will check the project notes.",
    idempotency_key="project-reply-01",
    thread_ts="1789552800.000100",
)
print(action.id, action.status)

const action = await inkbox.slack.sendMessage(
  "22222222-2222-4222-8222-222222222222",
  {
    conversationId: "C0123456789",
    text: "I will check the project notes.",
    idempotencyKey: "project-reply-01",
    threadTs: "1789552800.000100",
  },
);
console.log(action.id, action.status);

inkbox slack message send \
  --connection-id 22222222-2222-4222-8222-222222222222 \
  --conversation-id C0123456789 \
  --text "I will check the project notes." \
  --idempotency-key project-reply-01 \
  --thread-ts 1789552800.000100

curl -X POST "https://inkbox.ai/api/v1/slack/connections/22222222-2222-4222-8222-222222222222/messages" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: project-reply-01" \
  -d '{
    "conversation_id": "C0123456789",
    "text": "I will check the project notes.",
    "thread_ts": "1789552800.000100"
  }'

Keep Slack timestamps as strings. Reuse the same idempotency key and request body when retrying the same logical send. A successful HTTP response still requires inspecting the action’s status: sending, sent, failed, or unknown. sent means Slack accepted the message. It is not a delivery or read receipt. Poll the action status while it is sending. An unknown result does not automatically settle later. Reconcile with the live conversation before deciding what to do. Do not blindly send again with a new key.

Read conversations in the Console

Open Channels → Slack to start setup for an agent or open its existing Slack conversations. Each identity connects to one workspace in this version. The Console does not expose disable or remove actions; lifecycle controls remain available through the management API. Open your identity’s Slack section to browse Channels and Direct messages, including group DMs. Each row opens one conversation. Open replies from the message timeline to read a thread. Member profile images and your identity’s avatar identify message authors. Workspace setup lives on the Slack pages. Reauthorize when a connection needs updated permissions. Retention, retained-message search, history imports, and connection lifecycle controls remain available through the API, SDKs, and CLI.

Decide when your agent should act

In the Console, use Webhooks to manage notification subscriptions across channels. Subscribe an HTTPS endpoint to the events your runtime needs; one identity-owned subscription can combine Slack with other notification types. Choose DMs, group DMs, mentions, channel messages, and thread replies directly in the event list. These selections cover all accessible conversations across the identity’s connected workspaces, without a separate filter configuration. Inkbox delivers matching events. Your runtime decides when to wake the agent, what to respond to, which threads to keep watching, and what memory to retain. slack.thread_reply_received matches any thread reply; it does not remember whether your agent was mentioned earlier in that thread. Deduplicate events by the webhook envelope’s stable id. One post can qualify as both a channel message and a mention, but overlapping matches do not create separate logical events. Interaction and session-stop events are notifications for your runtime to handle. Receiving one does not automatically execute an action or cancel agent work.

Capture history without waking on everything

All eligible messages received through the connection are captured automatically, independently of webhook event selection. There is no capture switch or conversation allowlist. Use archive settings to set a retention period and webhook event selection to choose what wakes your agent. Search across the identity’s retained messages with identity-level search. Use an explicit backfill to import accessible conversation or thread history, then inspect coverage. A completed conversation pass is not proof that every thread or every historical message is present.

matches = inkbox.slack.search_messages(
    "project notes",
    identity_id="11111111-1111-4111-8111-111111111111",
    limit=20,
)
for message in matches.messages:
    print(message.connection_id, message.message_ts, message.text)

const matches = await inkbox.slack.searchMessages({
  q: "project notes",
  identityId: "11111111-1111-4111-8111-111111111111",
  limit: 20,
});
for (const message of matches.messages) {
  console.log(message.connectionId, message.messageTs, message.text);
}

inkbox slack search \
  --identity-id 11111111-1111-4111-8111-111111111111 \
  --q "project notes" \
  --limit 20

Search uses plain keywords and ranks matches by text relevance, with newer messages first for ties. It searches retained message text, not attachment contents; semantic search is not supported. A claimed agent-scoped key can omit the identity; an organization admin key must specify it. Use connection_id in Python, connectionId in TypeScript, or --connection-id in the CLI to narrow a search to one workspace. Keep all filters unchanged when following next_cursor in Python or nextCursor in TypeScript and CLI output. Continue even when a page is short or empty if a cursor is present. Retained history still requires current conversation access. Pausing the identity can retain incoming messages without waking the runtime. Disconnect stops capture through that connection and schedules that connection’s archive for deletion.

Files, pins, and richer actions

Fetch file metadata and bytes on demand, or upload a file of up to 10 MiB. Uploads require their own idempotency key. File metadata can be retained; file bytes are not archived.
A pin marks an existing conversation item for easy reference; it is not a file copy. You can read, add, and remove pins.
Edit or delete the bot’s messages, manage its reactions, and join or leave supported conversations, subject to Slack permissions.
Inspect capabilities before choosing an optional operation. Granted scopes do not guarantee every native feature is available.
Native processing status is an explicit runtime action for eligible Slack agent sessions. It is not a universal typing indicator and does not run or cancel work automatically.
Slack webhook delivery diagnostics contain event coordinates and status, not recoverable message bodies. Historical Slack webhook replay remains unsupported even when retained history is enabled.

Slack Connect and access boundaries

Slack Connect conversations are supported when the selected connection can access them. Use that connection’s authority, not a message author’s home workspace, for follow-up requests. The same shared conversation can be visible through separate installations; do not merge their permissions or archives. An incoming event uses the installation identified by Slack’s event context. Inkbox does not copy it to every connected workspace that might share the conversation. Installation does not grant entire-workspace access. Private channels need an authorized invitation. External users and files may expose fewer fields, and access can change after an event arrives. A file reference does not prove the file’s original workspace. Slack does not use the identity’s email or phone contact allow/block rules. Slack membership, granted permissions, and workspace restrictions control access. Your runtime still decides which events deserve a response.

Connection lifecycle

When a workspace requires reauthorization, start installation again for the same identity and workspace. Reauthorization does not grant access to other workspaces or replay missed webhooks. Request a backfill explicitly when you need accessible history. The disconnect API removes Inkbox’s access through a connection. It also stops capture and schedules that connection’s retained history for deletion. Reconnection does not restore the deleted archive. This does not uninstall the app from Slack. A workspace administrator can remove the Slack app separately. The Console does not expose a disconnect action. After reconnecting, capture resumes automatically. Import earlier accessible history explicitly if needed.

Reference

Sender profiles and contacts

Message webhooks include available sender names and profile details under the connection’s Slack permissions. Email requires the profile email permission; existing connections can grant newly requested permissions by completing authorization again. Missing profile details do not stop message delivery. Inkbox links encountered people to organization contacts, including their Slack workspace and user identifiers. The contact card shows those linked accounts. This is not a full workspace directory import. Inkbox contact visibility controls the webhook’s linked contact_id and contact-card accounts; matching an email does not grant additional contact access.

Get started

Capabilities

API keys

MCP

Webhooks

Signing keys

Skills

Integrations

Connect your workspace

Start installation from code

Contacts from Slack

Choose a workspace explicitly

Read and reply

Read conversations in the Console

Decide when your agent should act

Capture history without waking on everything

Files, pins, and richer actions

Slack Connect and access boundaries

Connection lifecycle

Reference

Sender profiles and contacts

​Connect your workspace

​Start installation from code

​Contacts from Slack

​Choose a workspace explicitly

​Read and reply

​Read conversations in the Console

​Decide when your agent should act

​Capture history without waking on everything

​Files, pins, and richer actions

​Slack Connect and access boundaries

​Connection lifecycle

​Reference

​Sender profiles and contacts

Connect your workspace

Start installation from code

Contacts from Slack

Choose a workspace explicitly

Read and reply

Read conversations in the Console

Decide when your agent should act

Capture history without waking on everything

Files, pins, and richer actions

Slack Connect and access boundaries

Connection lifecycle

Reference

Sender profiles and contacts