Introduction
# Slack
Access the Slack API with managed OAuth authentication. Send messages, manage channels, list users, and automate Slack workflows.
## Quick Start
```bash # 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`:
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### Getting Your API Key
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
## Connection Management
Manage your Slack OAuth connections at `https://ctrl.maton.ai`.
### List Connections
```bash 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
```bash 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
```bash 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:** ```json { "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
```bash 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:
```bash 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
### Post Message
```bash POST /slack/api/chat.postMessage Content-Type: application/json
{ "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_"}} ] } ```
### 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" } ```
### Update Message
```bash POST /slack/api/chat.update Content-Type: application/json
{ "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" } ```
### List Channels
```bash GET /slack/api/conversations.list?types=public_channel,private_channel ```
### Get Channel Info
```bash GET /slack/api/conversations.info?channel=C0123456789 ```
### Get Channel Members
```bash GET /slack/api/conversations.members?channel=C0123456789&limit=100 ```
### List Messages in Channel
```bash GET /slack/api/conversations.history?channel=C0123456789&limit=100 ```
### Get Thread Replies
```bash GET /slack/api/conversations.replies?channel=C0123456789&ts=1234567890.123456 ```
### List Users
```bash GET /slack/api/users.list ```
### Get User Info
```bash GET /slack/api/users.info?user=U0123456789 ```
### Search Messages
```bash GET /slack/api/search.messages?query=keyword ```
### Open DM Conversation
```bash POST /slack/api/conversations.open Content-Type: application/json
{ "users": "U0123456789" } ```
### Add Reaction
```bash POST /slack/api/reactions.add Content-Type: application/json
{ "channel": "C0123456789", "name": "thumbsup", "timestamp": "1234567890.123456" } ```
### Upload File
```bash POST /slack/api/files.upload Content-Type: multipart/form-data
channels=C0123456789 content=file content here filename=example.txt ```
### Auth Test
Get current user and team info:
```bash GET /slack/api/auth.test ```
## Code Examples
### JavaScript
```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!' }) }); ```
### Python
```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!'} ) ```
## Notes
- Channel IDs start with `C` (public), `G` (private/group), or `D` (DM) - User IDs start with `U`, Team IDs start with `T` - Message timestamps (`ts`) are used as unique identifiers - Use `mrkdwn` type for Slack-flavored markdown formatting - Thread replies use `thread_ts` to reference the parent message - 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 |
### Troubleshooting: API Key Issues
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://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 Overview](https://api.slack.com/apis) - [Post Message](https://api.slack.com/methods/chat.postMessage) - [Update Message](https://api.slack.com/methods/chat.update) - [Delete Message](https://api.slack.com/methods/chat.delete) - [List Channels](https://api.slack.com/methods/conversations.list) - [Channel History](https://api.slack.com/methods/conversations.history) - [Thread Replies](https://api.slack.com/methods/conversations.replies) - [List Users](https://api.slack.com/methods/users.list) - [Get User Info](https://api.slack.com/methods/users.info) - [Search Messages](https://api.slack.com/methods/search.messages) - [Block Kit Reference](https://api.slack.com/reference/block-kit) - [LLM Reference](https://docs.slack.dev/llms.txt) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[email protected])