Slack

Slack

Access the Slack API with managed OAuth authentication. Send messages, manage channels, list users, and automate Slack workflows.

Quick Start

# Post a message to a channel
python <<'EOF'
import urllib.request, os, json
data = json.dumps({'channel': 'C0123456789', 'text': 'Hello from Maton!'}).encode()
req = urllib.request.Request('https://gateway.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://gateway.maton.ai/slack/{method}

The gateway proxies requests to slack.com and automatically injects your OAuth token.

Authentication

All requests require the Maton API key in the Authorization header:

Authorization: Bearer $MATON_API_KEY

Environment Variable: Set your API key as MATON_API_KEY:

export MATON_API_KEY="YOUR_API_KEY"

Getting Your API Key

1. Sign in or create an account at maton.ai
2. Go to maton.ai/settings
3. Copy your API key

Connection Management

Manage your Slack OAuth connections at https://ctrl.maton.ai.

List Connections

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.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

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'app': 'slack'}).encode()
req = urllib.request.Request('https://ctrl.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

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.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:

{
  "connection": {
    "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80",
    "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

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.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 with the Maton-Connection header:

python <<'EOF'
import urllib.request, os, json
data = json.dumps({'channel': 'C0123456789', 'text': 'Hello!'}).encode()
req = urllib.request.Request('https://gateway.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', '21fd90f9-5935-43cd-b6c8-bde9d915ca80')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

If omitted, the gateway uses the default (oldest) active connection.

API Reference

Authentication

Auth Test

GET /slack/api/auth.test

Returns current user and team info.

Messages

Post Message

POST /slack/api/chat.postMessage
Content-Type: application/json

{
  "channel": "C0123456789",
  "text": "Hello, world!"
}

With blocks:

POST /slack/api/chat.postMessage
Content-Type: application/json

{
  "channel": "C0123456789",
  "blocks": [
    {"type": "section", "text": {"type": "mrkdwn", "text": "*Bold* and _italic_"}}
  ]
}

Post Thread Reply

POST /slack/api/chat.postMessage
Content-Type: application/json

{
  "channel": "C0123456789",
  "thread_ts": "1234567890.123456",
  "text": "This is a reply in a thread"
}

Update Message

POST /slack/api/chat.update
Content-Type: application/json

{
  "channel": "C0123456789",
  "ts": "1234567890.123456",
  "text": "Updated message"
}

Delete Message

POST /slack/api/chat.delete
Content-Type: application/json

{
  "channel": "C0123456789",
  "ts": "1234567890.123456"
}

Schedule Message

POST /slack/api/chat.scheduleMessage
Content-Type: application/json

{
  "channel": "C0123456789",
  "text": "Scheduled message",
  "post_at": 1734567890
}

List Scheduled Messages

GET /slack/api/chat.scheduledMessages.list

Delete Scheduled Message

POST /slack/api/chat.deleteScheduledMessage
Content-Type: application/json

{
  "channel": "C0123456789",
  "scheduled_message_id": "Q1234567890"
}

Get Permalink

GET /slack/api/chat.getPermalink?channel=C0123456789&message_ts=1234567890.123456

Conversations (Channels)

List Channels

GET /slack/api/conversations.list?types=public_channel,private_channel&limit=100

Types: public_channel, private_channel, im, mpim

Get Channel Info

GET /slack/api/conversations.info?channel=C0123456789

Get Channel History

GET /slack/api/conversations.history?channel=C0123456789&limit=100

With time range:

GET /slack/api/conversations.history?channel=C0123456789&oldest=1234567890&latest=1234567899

Get Thread Replies

GET /slack/api/conversations.replies?channel=C0123456789&ts=1234567890.123456

Get Channel Members

GET /slack/api/conversations.members?channel=C0123456789&limit=100

Create Channel

POST /slack/api/conversations.create
Content-Type: application/json

{
  "name": "new-channel-name",
  "is_private": false
}

Join Channel

POST /slack/api/conversations.join
Content-Type: application/json

{
  "channel": "C0123456789"
}

Leave Channel

POST /slack/api/conversations.leave
Content-Type: application/json

{
  "channel": "C0123456789"
}

Archive Channel

POST /slack/api/conversations.archive
Content-Type: application/json

{
  "channel": "C0123456789"
}

Unarchive Channel

POST /slack/api/conversations.unarchive
Content-Type: application/json

{
  "channel": "C0123456789"
}

Rename Channel

POST /slack/api/conversations.rename
Content-Type: application/json

{
  "channel": "C0123456789",
  "name": "new-name"
}

Set Channel Topic

POST /slack/api/conversations.setTopic
Content-Type: application/json

{
  "channel": "C0123456789",
  "topic": "Channel topic here"
}

Set Channel Purpose

POST /slack/api/conversations.setPurpose
Content-Type: application/json

{
  "channel": "C0123456789",
  "purpose": "Channel purpose here"
}

Invite to Channel

POST /slack/api/conversations.invite
Content-Type: application/json

{
  "channel": "C0123456789",
  "users": "U0123456789,U9876543210"
}

Kick from Channel

POST /slack/api/conversations.kick
Content-Type: application/json

{
  "channel": "C0123456789",
  "user": "U0123456789"
}

Mark Channel Read

POST /slack/api/conversations.mark
Content-Type: application/json

{
  "channel": "C0123456789",
  "ts": "1234567890.123456"
}

Direct Messages

Open DM Conversation

POST /slack/api/conversations.open
Content-Type: application/json

{
  "users": "U0123456789"
}

For group DM:

POST /slack/api/conversations.open
Content-Type: application/json

{
  "users": "U0123456789,U9876543210"
}

List DM Channels

GET /slack/api/conversations.list?types=im

List Group DM Channels

GET /slack/api/conversations.list?types=mpim

My Conversations

GET /slack/api/users.conversations?limit=100

Users

List Users

GET /slack/api/users.list?limit=100

Get User Info

GET /slack/api/users.info?user=U0123456789

Get User Presence

GET /slack/api/users.getPresence?user=U0123456789

Set User Presence

POST /slack/api/users.setPresence
Content-Type: application/json

{
  "presence": "away"
}

Lookup User by Email

GET /slack/api/users.lookupByEmail?email=user@example.com

Reactions

Add Reaction

POST /slack/api/reactions.add
Content-Type: application/json

{
  "channel": "C0123456789",
  "name": "thumbsup",
  "timestamp": "1234567890.123456"
}

Remove Reaction

POST /slack/api/reactions.remove
Content-Type: application/json

{
  "channel": "C0123456789",
  "name": "thumbsup",
  "timestamp": "1234567890.123456"
}

Get Reactions on Message

GET /slack/api/reactions.get?channel=C0123456789&timestamp=1234567890.123456

List My Reactions

GET /slack/api/reactions.list?limit=100

Stars

List Stars

GET /slack/api/stars.list?limit=100

Add Star

POST /slack/api/stars.add
Content-Type: application/json

{
  "channel": "C0123456789",
  "timestamp": "1234567890.123456"
}

Remove Star

POST /slack/api/stars.remove
Content-Type: application/json

{
  "channel": "C0123456789",
  "timestamp": "1234567890.123456"
}

Bots

Get Bot Info

GET /slack/api/bots.info?bot=B0123456789

Files

Upload File

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)

GET /slack/api/files.getUploadURLExternal?filename=example.txt&length=1024

Complete File Upload

POST /slack/api/files.completeUploadExternal
Content-Type: application/json

{
  "files": [{"id": "F0123456789", "title": "My File"}],
  "channel_id": "C0123456789"
}

Delete File

POST /slack/api/files.delete
Content-Type: application/json

{
  "file": "F0123456789"
}

Get File Info

GET /slack/api/files.info?file=F0123456789

Search

Search Messages

GET /slack/api/search.messages?query=keyword

Code Examples

JavaScript

const response = await fetch('https://gateway.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

import os
import requests

response = requests.post(
    'https://gateway.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

Missing Scope Errors: If you encounter missing_scope errors, contact Maton Support to request additional scopes for your connection.

Troubleshooting: API Key Issues

1. Check that the MATON_API_KEY environment variable is set:

echo $MATON_API_KEY

2. Verify the API key is valid by listing connections:

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.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://gateway.maton.ai/slack/api/chat.postMessage
• Incorrect: https://gateway.maton.ai/api/chat.postMessage

Resources

• Slack API Methods
• Web API Reference
• Block Kit Reference
• Message Formatting
• Rate Limits
• Maton Community
• Maton Support