Skill: byungkyu/slack-api (version 1.0.10)

--- name: slack description: | Slack API integration with managed OAuth. Send messages, manage channels, search conversations, and interact with Slack workspaces. Use this skill when users want to post messages, list channels, get user info, or automate Slack workflows. For other third party apps, use the api-gateway skill (https://clawhub.ai/byungkyu/api-gateway). compatibility: Requires network access and valid Maton API key metadata: author: maton version: "1.0" clawdbot: emoji: homepage: "https://maton.ai" requires: env: - MATON_API_KEY --- # Slack Access the Slack API with managed OAuth authentication. Send messages, manage channels, list users, and automate Slack workflows. ## Quick Start **CLI:** ```bash maton slack message send --channel C0123456789 --text 'Hello from Maton!' ``` ```bash maton api '/slack/api/chat.postMessage' ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'channel': 'C0123456789', 'text': 'Hello from Maton!'}).encode() req = urllib.request.Request('https://api.maton.ai/slack/api/chat.postMessage', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ## Base URL ``` https://api.maton.ai/slack/{method} ``` Maton proxies requests to `slack.com` and automatically injects your OAuth token. ## Installation **NPM:** ```bash npm install -g @maton-ai/cli ``` **Homebrew:** ```bash brew install maton-ai/cli/maton ``` ## Authentication **CLI:** ```bash maton login # Opens browser for API key maton login --interactive # Skip browser, paste API key directly maton whoami # Show current auth state ``` **Manual:** 1. Sign in or create an account at [maton.ai](https://maton.ai) 2. Go to [maton.ai/settings](https://maton.ai/settings) 3. Copy your API key 4. Set your API key as `MATON_API_KEY`: ```bash export MATON_API_KEY="YOUR_API_KEY" ``` ## Connection Management Manage your Slack OAuth connections at `https://api.maton.ai`. ### List Connections **CLI:** ```bash maton connection list slack --status ACTIVE ``` ```bash maton api -X GET /connections -f app=slack -f status=ACTIVE ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections?app=slack&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Create Connection **CLI:** ```bash maton connection create slack ``` ```bash maton api /connections -f app=slack ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'slack'}).encode() req = urllib.request.Request('https://api.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Get Connection **CLI:** ```bash maton connection view {connection_id} ``` ```bash maton api /connections/{connection_id} ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` **Response:** ```json { "connection": { "connection_id": "{connection_id}", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "slack", "metadata": {} } } ``` Open the returned `url` in a browser to complete OAuth authorization. ### Delete Connection **CLI:** ```bash maton connection delete {connection_id} ``` ```bash maton api -X DELETE /connections/{connection_id} ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Specifying Connection If you have multiple Slack connections, specify which one to use: **CLI:** ```bash maton slack message send --channel C0123456789 --text 'Hello!' --connection {connection_id} ``` ```bash maton api /slack/api/chat.postMessage --connection {connection_id} ``` **Python:** ```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'channel': 'C0123456789', 'text': 'Hello!'}).encode() req = urllib.request.Request('https://api.maton.ai/slack/api/chat.postMessage', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '{connection_id}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` If you have multiple connections, always specify the connection to ensure requests go to the intended account. ## Security & Permissions - Access is scoped to messages, channels, users, files, and reactions within the connected Slack account. - **All write operations require explicit user approval.** Before executing any create, update, or delete call, confirm the target resource and intended effect with the user. ## API Reference ### Authentication #### Auth Test ```bash GET /slack/api/auth.test ``` Returns current user and team info. Example: ```bash maton slack whoami ``` --- ### Messages #### Post Message ```bash POST /slack/api/chat.postMessage Content-Type: application/json { "channel": "C0123456789", "text": "Hello, world!" } ``` Example: ```bash maton slack message send --channel C0123456789 --text 'Hello, world!' ``` With blocks: ```bash POST /slack/api/chat.postMessage Content-Type: application/json { "channel": "C0123456789", "blocks": [ {"type": "section", "text": {"type": "mrkdwn", "text": "*Bold* and _italic_"}} ] } ``` Example: ```bash maton slack message send --channel C0123456789 --blocks '[{"type":"section","text":{"type":"mrkdwn","text":"*Bold* and _italic_"}}]' ``` #### Post /me-style Message ```bash maton slack message me --channel C0123456789 --text 'is deploying' ``` #### Post Thread Reply ```bash POST /slack/api/chat.postMessage Content-Type: application/json { "channel": "C0123456789", "thread_ts": "1234567890.123456", "text": "This is a reply in a thread" } ``` Example: ```bash maton slack message reply --channel C0123456789 --thread-ts 1234567890.123456 --text 'This is a reply in a thread' ``` #### Update Message ```bash POST /slack/api/chat.update Content-Type: application/json { "channel": "C0123456789", "ts": "1234567890.123456", "text": "Updated message" } ``` Example: ```bash maton slack message update --channel C0123456789 --ts 1234567890.123456 --text 'Updated message' ``` #### Delete Message ```bash POST /slack/api/chat.delete Content-Type: application/json { "channel": "C0123456789", "ts": "1234567890.123456" } ``` Example: ```bash maton slack message delete --channel C0123456789 --ts 1234567890.123456 ``` #### Schedule Message ```bash POST /slack/api/chat.scheduleMessage Content-Type: application/json { "channel": "C0123456789", "text": "Scheduled message", "post_at": 1734567890 } ``` Example: ```bash maton slack schedule create --channel C0123456789 --text 'Scheduled message' --post-at 1734567890 ``` #### List Scheduled Messages ```bash GET /slack/api/chat.scheduledMessages.list ``` Example: ```bash maton slack schedule list ``` #### Delete Scheduled Message ```bash POST /slack/api/chat.deleteScheduledMessage Content-Type: application/json { "channel": "C0123456789", "scheduled_message_id": "Q1234567890" } ``` Example: ```bash maton slack schedule delete --channel C0123456789 --id Q1234567890 ``` #### Get Permalink ```bash GET /slack/api/chat.getPermalink?channel=C0123456789&message_ts=1234567890.123456 ``` Example: ```bash maton slack message permalink --channel C0123456789 --message-ts 1234567890.123456 ``` --- ### Conversations (Channels) #### List Channels ```bash GET /slack/api/conversations.list?types=public_channel,private_channel&limit=100 ``` Types: `public_channel`, `private_channel`, `im`, `mpim` Example: ```bash maton slack channel list --types public_channel,private_channel --limit 100 ``` #### Get Channel Info ```bash GET /slack/api/conversations.info?channel=C0123456789 ``` Example: ```bash maton slack channel view C0123456789 ``` #### Get Channel History ```bash GET /slack/api/conversations.history?channel=C0123456789&limit=100 ``` Example: ```bash maton slack message list --channel C0123456789 --limit 100 ``` With time range: ```bash GET /slack/api/conversations.history?channel=C0123456789&oldest=1234567890&latest=1234567899 ``` Example: ```bash maton slack message list --channel C0123456789 --oldest 1234567890 --latest 1234567899 ``` #### Get Thread Replies ```bash GET /slack/api/conversations.replies?channel=C0123456789&ts=1234567890.123456 ``` Example: ```bash maton slack message replies --channel C0123456789 --ts 1234567890.123456 ``` #### Get Channel Members ```bash GET /slack/api/conversations.members?channel=C0123456789&limit=100 ``` Example: ```bash maton slack channel members C0123456789 --limit 100 ``` #### Create Channel ```bash POST /slack/api/conversations.create Content-Type: application/json { "name": "new-channel-name", "is_private": false } ``` Example: ```bash maton slack channel create --name new-channel-name ``` #### Join Channel ```bash POST /slack/api/conversations.join Content-Type: application/json { "channel": "C0123456789" } ``` Example: ```bash maton slack channel join C0123456789 ``` #### Leave Channel ```bash POST /slack/api/conversations.leave Content-Type: application/json { "channel": "C0123456789" } ``` Example: ```bash maton slack channel leave C0123456789 ``` #### Archive Channel ```bash POST /slack/api/conversations.archive Content-Type: application/json { "channel": "C0123456789" } ``` Example: ```bash maton slack channel archive C0123456789 ``` #### Unarchive Channel ```bash POST /slack/api/conversations.unarchive Content-Type: application/json { "channel": "C0123456789" } ``` Example: ```bash maton slack channel unarchive C0123456789 ``` #### Rename Channel ```bash POST /slack/api/conversations.rename Content-Type: application/json { "channel": "C0123456789", "name": "new-name" } ``` Example: ```bash maton slack channel rename C0123456789 --name new-name ``` #### Set Channel Topic ```bash POST /slack/api/conversations.setTopic Content-Type: application/json { "channel": "C0123456789", "topic": "Channel topic here" } ``` Example: ```bash maton slack channel set-topic C0123456789 --topic 'Channel topic here' ``` #### Set Channel Purpose ```bash POST /slack/api/conversations.setPurpose Content-Type: application/json { "channel": "C0123456789", "purpose": "Channel purpose here" } ``` Example: ```bash maton slack channel set-purpose C0123456789 --purpose 'Channel purpose here' ``` #### Invite to Channel ```bash POST /slack/api/conversations.invite Content-Type: application/json { "channel": "C0123456789", "users": "U0123456789,U9876543210" } ``` Example: ```bash maton slack channel invite C0123456789 --users U0123456789,U9876543210 ``` #### Kick from Channel ```bash POST /slack/api/conversations.kick Content-Type: application/json { "channel": "C0123456789", "user": "U0123456789" } ``` Example: ```bash maton slack channel kick C0123456789 --user U0123456789 ``` #### Mark Channel Read ```bash POST /slack/api/conversations.mark Content-Type: application/json { "channel": "C0123456789", "ts": "1234567890.123456" } ``` Example: ```bash maton slack channel mark C0123456789 --ts 1234567890.123456 ``` --- ### Direct Messages #### Open DM Conversation ```bash POST /slack/api/conversations.open Content-Type: application/json { "users": "U0123456789" } ``` Example: ```bash maton slack conversation open --users U0123456789 ``` For group DM: ```bash POST /slack/api/conversations.open Content-Type: application/json { "users": "U0123456789,U9876543210" } ``` Example: ```bash maton slack conversation open --users U0123456789,U9876543210 ``` #### List DM Channels ```bash GET /slack/api/conversations.list?types=im ``` Example: ```bash maton slack channel list --types im ``` #### List Group DM Channels ```bash GET /slack/api/conversations.list?types=mpim ``` Example: ```bash maton slack channel list --types mpim ``` #### My Conversations ```bash GET /slack/api/users.conversations?limit=100 ``` Example: ```bash maton slack conversation list --limit 100 ``` --- ### Users #### List Users ```bash GET /slack/api/users.list?limit=100 ``` Example: ```bash maton slack user list --limit 100 ``` #### Get User Info ```bash GET /slack/api/users.info?user=U0123456789 ``` Example: ```bash maton slack user view U0123456789 ``` #### Get User Presence ```bash GET /slack/api/users.getPresence?user=U0123456789 ``` Example: ```bash maton slack user presence U0123456789 ``` #### Lookup User by Email ```bash GET /slack/api/users.lookupByEmail?email=[REDACTED_SECRET] ``` Example: ```bash maton slack user lookup --email [REDACTED_SECRET] ``` --- ### Reactions #### Add Reaction ```bash POST /slack/api/reactions.add Content-Type: application/json { "channel": "C0123456789", "name": "thumbsup", "timestamp": "1234567890.123456" } ``` Example: ```bash maton slack reaction add --channel C0123456789 --ts 1234567890.123456 --emoji thumbsup ``` #### Remove Reaction ```bash POST /slack/api/reactions.remove Content-Type: application/json { "channel": "C0123456789", "name": "thumbsup", "timestamp": "1234567890.123456" } ``` Example: ```bash maton slack reaction remove --channel C0123456789 --ts 1234567890.123456 --emoji thumbsup ``` #### Get Reactions on Message ```bash GET /slack/api/reactions.get?channel=C0123456789&timestamp=1234567890.123456 ``` Example: ```bash maton slack reaction get --channel C0123456789 --ts 1234567890.123456 ``` #### List My Reactions ```bash GET /slack/api/reactions.list?limit=100 ``` Example: ```bash maton slack reaction list --limit 100 ``` --- ### Stars #### List Stars ```bash GET /slack/api/stars.list?limit=100 ``` Example: ```bash maton slack star list --limit 100 ``` #### Add Star ```bash POST /slack/api/stars.add Content-Type: application/json { "channel": "C0123456789", "timestamp": "1234567890.123456" } ``` Example: ```bash maton slack star add --channel C0123456789 --ts 1234567890.123456 ``` #### Remove Star ```bash POST /slack/api/stars.remove Content-Type: application/json { "channel": "C0123456789", "timestamp": "1234567890.123456" } ``` Example: ```bash maton slack star remove --channel C0123456789 --ts 1234567890.123456 ``` --- ### Pins #### List Pins ```bash GET /slack/api/pins.list?channel=C0123456789 ``` Example: ```bash maton slack pin list C0123456789 ``` #### Add Pin ```bash POST /slack/api/pins.add Content-Type: application/json { "channel": "C0123456789", "timestamp": "1234567890.123456" } ``` Example: ```bash maton slack pin add --channel C0123456789 --ts 1234567890.123456 ``` #### Remove Pin ```bash POST /slack/api/pins.remove Content-Type: application/json { "channel": "C0123456789", "timestamp": "1234567890.123456" } ``` Example: ```bash maton slack pin remove --channel C0123456789 --ts 1234567890.123456 ``` --- ### Bookmarks #### List Bookmarks ```bash GET /slack/api/bookmarks.list?channel_id=C0123456789 ``` Example: ```bash maton slack bookmark list --channel C0123456789 ``` #### Add Bookmark ```bash POST /slack/api/bookmarks.add Content-Type: application/json { "channel_id": "C0123456789", "title": "Team Handbook", "type": "link", "link": "https://example.com/handbook" } ``` Example: ```bash maton slack bookmark add --channel C0123456789 --title 'Team Handbook' --type link --link https://example.com/handbook ``` #### Edit Bookmark ```bash POST /slack/api/bookmarks.edit Content-Type: application/json { "bookmark_id": "Bk0123456789", "channel_id": "C0123456789", "title": "Updated Title", "link": "https://example.com/new" } ``` Example: ```bash maton slack bookmark edit --channel C0123456789 --bookmark-id Bk0123456789 --title 'Updated Title' --link https://example.com/new ``` #### Remove Bookmark ```bash POST /slack/api/bookmarks.remove Content-Type: application/json { "bookmark_id": "Bk0123456789", "channel_id": "C0123456789" } ``` Example: ```bash maton slack bookmark remove --channel C0123456789 --bookmark-id Bk0123456789 ``` --- ### Bots #### Get Bot Info ```bash GET /slack/api/bots.info?bot=B0123456789 ``` Example: ```bash maton slack bot view B0123456789 ``` Note: this expects the `B`-prefixed bot ID (from `bot_id` on a message), not the bot's `U`-prefixed user ID. Passing a `U…` ID returns `bot_not_found`. --- ### Files #### List Files ```bash GET /slack/api/files.list?count=100 ``` Filter by channel, user, or file types: ```bash GET /slack/api/files.list?channel=C0123456789&user=U0123456789&types=images,pdfs ``` Example: ```bash maton slack file list --count 100 ``` ```bash maton slack file list --channel C0123456789 --user U0123456789 --types images,pdfs ``` #### Upload File ```bash POST /slack/api/files.upload Content-Type: multipart/form-data channels=C0123456789 content=file content here filename=example.txt title=Example File ``` #### Upload File v2 (Get Upload URL) ```bash GET /slack/api/files.getUploadURLExternal?filename=example.txt&length=1024 ``` #### Complete File Upload ```bash POST /slack/api/files.completeUploadExternal Content-Type: application/json { "files": [{"id": "F0123456789", "title": "My File"}], "channel_id": "C0123456789" } ``` Example: ```bash maton slack file upload --file ./example.txt --channel C0123456789 --title 'My File' ``` #### Delete File ```bash POST /slack/api/files.delete Content-Type: application/json { "file": "F0123456789" } ``` Example: ```bash maton slack file delete F0123456789 ``` #### Get File Info ```bash GET /slack/api/files.info?file=F0123456789 ``` Example: ```bash maton slack file view F0123456789 ``` --- ### Search #### Search Messages ```bash GET /slack/api/search.messages?query=keyword ``` Example: ```bash maton slack search messages 'keyword' ``` #### Search Files ```bash GET /slack/api/search.files?query=keyword ``` Note: `search.files` matches against filename and title, not file body content. Newly uploaded files may take a moment to appear in results due to indexing lag. --- ## Code Examples ### CLI ```bash # Send a message to a channel maton slack message send --channel C0123456789 --text 'Hello team' # List channels maton slack channel list --types public_channel,private_channel # Look up a user by email maton slack user lookup --email [REDACTED_SECRET] # Add a reaction to a message maton slack reaction add --channel C012 --ts 1700000000.000100 --emoji thumbsup ``` ### JavaScript ```javascript const response = await fetch('https://api.maton.ai/slack/api/chat.postMessage', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${process.env.MATON_API_KEY}` }, body: JSON.stringify({ channel: 'C0123456', text: 'Hello!' }) }); const result = await response.json(); console.log(result); ``` ### Python ```python import os import requests response = requests.post( 'https://api.maton.ai/slack/api/chat.postMessage', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, json={'channel': 'C0123456', 'text': 'Hello!'} ) print(response.json()) ``` --- ## Notes - Channel IDs: `C` (public), `G` (private/group), `D` (DM) - User IDs start with `U`, Bot IDs start with `B`, Team IDs start with `T` - Message timestamps (`ts`) are unique identifiers - Use `mrkdwn` type for Slack-flavored markdown formatting - Thread replies use `thread_ts` to reference the parent message - Cursor-based pagination: use `cursor` from `response_metadata.next_cursor` ### Shell Notes - IMPORTANT: When using curl commands, use `curl -g` when URLs contain brackets (`fields[]`, `sort[]`, `records[]`) to disable glob parsing - IMPORTANT: When piping curl output to `jq` or other commands, environment variables like `$MATON_API_KEY` may not expand correctly in some shell environments. You may get "Invalid API key" errors when piping. ## Error Handling | Status | Meaning | |--------|---------| | 400 | Missing Slack connection | | 401 | Invalid or missing Maton API key | | 429 | Rate limited (10 req/sec per account) | | 4xx/5xx | Passthrough error from Slack API | **Missing Scope Errors:** If you encounter `missing_scope` errors, contact [Maton Support](mailto:[REDACTED_SECRET]) to request additional scopes for your connection. ### Troubleshooting: API Key Issues **CLI:** 1. Check your auth state: ```bash maton whoami ``` 2. Verify the API key is valid by listing connections: ```bash maton connection list ``` **Manual:** 1. Check that the `MATON_API_KEY` environment variable is set: ```bash echo $MATON_API_KEY ``` 2. Verify the API key is valid by listing connections: ```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://api.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ``` ### Troubleshooting: Invalid App Name 1. Ensure your URL path starts with `slack`. For example: - Correct: `https://api.maton.ai/slack/api/chat.postMessage` - Incorrect: `https://api.maton.ai/api/chat.postMessage` ## Resources - [Slack API Methods](https://api.slack.com/methods) - [Web API Reference](https://api.slack.com/web) - [Block Kit Reference](https://api.slack.com/reference/block-kit) - [Message Formatting](https://api.slack.com/reference/surfaces/formatting) - [Rate Limits](https://api.slack.com/docs/rate-limits) - [Maton CLI Manual](https://cli.maton.ai/manual) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[REDACTED_SECRET])


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)