> ## Documentation Index
> Fetch the complete documentation index at: https://inkbox.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack contact rules

> Allow or block Slack people and workspaces with directional rules and whitelist or blacklist defaults

Slack rules belong to an Inkbox identity. Manage them in the [Inkbox Console](https://inkbox.ai/console) or with an organization admin API key. SDK and CLI examples require version `0.7.14` or later.

Claimed agent keys can list and read their own identity's rules, but cannot change rules or defaults.

## Choose the default

Set modes through the [identity update API](/docs/api/identities/manage), just like email and phone rules:

| Field | Meaning |
| :- | :- |
| `slack_filter_mode` | Set both directions to `whitelist` or `blacklist`. |
| `slack_inbound_filter_mode` | Set the receive default only. |
| `slack_outbound_filter_mode` | Set the send default only. |

The default is **blacklist** in both directions. Whitelist mode blocks unmatched people. Blacklist mode allows unmatched people. A shared mode update replaces both directional defaults. Do not combine shared and directional Slack fields in one update. Omitted fields stay unchanged; explicit null is not accepted. Identity responses report the effective directional modes. In the Console, choose the desired mode, then select **Save changes** to apply it; **Cancel** discards unsaved mode changes.

```bash cURL theme={null}
curl -X PATCH "https://inkbox.ai/api/v1/identities/project-agent" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"slack_filter_mode":"whitelist"}'
```

## Match people or workspaces

| `match_type` | `match_target` | Meaning |
| :- | :- | :- |
| `exact_user` | `T0123456789:U0123456789` | One verified Slack account: home workspace ID plus user ID. |
| `workspace` | `T0123456789` | People whose verified home workspace matches this ID. |

A person's exact rule wins over a workspace rule. A workspace rule wins over the directional default. A workspace rule is analogous to an email-domain rule: allowing the connected workspace does not allow every external participant in a shared channel.

Use the Slack accounts on a [contact card](/docs/capabilities/contacts), [contact import](/docs/api/slack/contact-import#import-contacts), or a verified user profile to select targets. Do not substitute a display name, email address, or the connection's workspace for a person's home workspace.

In the Console, choose a contact first. If they have multiple Slack accounts, **All saved Slack accounts** is selected by default; you can choose one account instead. A contact with one account uses it automatically. Saving all accounts creates one exact rule per currently saved account; accounts added later are not covered automatically. If only some rules save, the Console shows progress and **Retry remaining** retries only the unfinished accounts.

Contact rules govern communication, not [native directory profiles or conversation-member lists](/docs/api/slack/users). Reading that metadata does not grant permission to message someone or access their linked Inkbox contact.

## Rule endpoints

```text theme={null}
GET    /api/v1/identities/{agent_handle}/slack-contact-rules
POST   /api/v1/identities/{agent_handle}/slack-contact-rules
GET    /api/v1/identities/{agent_handle}/slack-contact-rules/{rule_id}
PATCH  /api/v1/identities/{agent_handle}/slack-contact-rules/{rule_id}
DELETE /api/v1/identities/{agent_handle}/slack-contact-rules/{rule_id}
GET    /api/v1/slack/contact-rules
```

Create with `action` (`allow` or `block`), `match_type`, and `match_target`. Optional `direction` is `inbound`, `outbound`, or `both`; omission means `both`.

Lists return arrays. Filter with `action`, `match_type`, or `direction`, and paginate with `limit` and `offset`. An inbound or outbound filter also includes rules covering both directions. The organization-wide list additionally accepts `agent_identity_id`.

Each rule contains `id`, `agent_identity_id`, `action`, `match_type`, `match_target`, `direction`, `status`, `created_at`, `updated_at`, and a nullable `contact`. A workspace rule has no single contact card.

A PATCH can change `action` or `direction`. To change only one covered side while preserving the other, send `action` with `apply_to: "inbound"` or `"outbound"`. Do not combine `apply_to` and `direction`. Compatible coverage can retain the existing rule ID. Duplicate coverage returns `409`.

<CodeGroup>
  ```python Python theme={null}
  from inkbox import Inkbox

  client = Inkbox(api_key="YOUR_API_KEY")
  rule = client.slack.contact_rules.create(
      "project-agent",
      action="allow",
      match_type="exact_user",
      match_target="T0123456789:U0123456789",
  )
  client.slack.contact_rules.update(
      "project-agent", rule.id, action="block", apply_to="outbound"
  )
  ```

  ```typescript TypeScript theme={null}
  import { Inkbox, SlackRuleAction, SlackRuleMatchType } from "@inkbox/sdk";

  const client = new Inkbox({ apiKey: "YOUR_API_KEY" });
  const rule = await client.slack.contactRules.create("project-agent", {
    action: SlackRuleAction.ALLOW,
    matchType: SlackRuleMatchType.EXACT_USER,
    matchTarget: "T0123456789:U0123456789",
  });
  await client.slack.contactRules.update("project-agent", rule.id, {
    action: SlackRuleAction.BLOCK,
    applyTo: "outbound",
  });
  ```

  ```bash CLI theme={null}
  inkbox slack contact-rule create project-agent \
    --action allow --match-type workspace --match-target T0123456789
  inkbox identity update project-agent --slack-filter-mode whitelist
  ```
</CodeGroup>

Rust exposes `client.slack().contact_rules` with `list`, `list_all`, `get`, `create`, `update`, and `delete`. Use `SlackContactRuleCreateOptions`, `SlackContactRuleListOptions`, and `SlackContactRuleUpdateOptions`. Set modes with `IdentityFilterModeOptions` and `update_filter_modes`.

## Companion and mentions

Rules decide **who** may communicate. Webhook subscriptions decide **which events** reach your runtime. Subscribe to `slack.mention_received` for mentions; there is no separate mention-mode contact rule.

[Companion mode](/docs/capabilities/companion-mode#slack) is the existing identity-level enabled preference. Slack requires an exact verified human account allowed in both directions to sponsor a conversation. Workspace allows and blacklist defaults do not make sponsors. Importing contacts or inviting the app does not activate Companion. A fresh qualifying sponsor message grants access to the whole channel or group DM, including all its threads. A new participant joining or the sponsor leaving requires fresh sponsorship; another participant leaving alone does not. Explicit blocks still apply.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.