matimo-slack

Slack tools for Matimo - send messages, manage channels, upload files, and more.

Installation

pip install matimo matimo-slack

Available Tools (16 Total)

⚠️ slack_upload_file only performs step 1 of Slack's modern upload flow (files.getUploadURLExternal) - it returns an upload_url you must PUT the file binary to yourself, then call Slack's files.completeUploadExternal directly. Matimo does not ship tools for those remaining two steps.

Quick Start

import asyncio
import os
from matimo import Matimo
from matimo_slack import get_tools_path

async def main():
    matimo = await Matimo.init(get_tools_path())

    # Send a message
    await matimo.execute('slack_send_channel_message', {
        'channel': '#general',
        'text': 'Hello from Matimo!',
    })

    # List channels
    result = await matimo.execute('slack-list-channels', {})
    print(result)

asyncio.run(main())

Authentication

All tools authenticate using a Slack Bot Token:

export SLACK_BOT_TOKEN="xoxb-your-bot-token"

Setting Up a Slack App

1. Go to api.slack.com/apps → Create New App → From scratch
2. Navigate to OAuth & Permissions and add scopes (see table below)
3. Click Install to Workspace and copy the Bot User OAuth Token
4. Set SLACK_BOT_TOKEN in your environment

Required OAuth Scopes

LangChain Agent Example

from matimo import Matimo
from matimo_slack import get_tools_path
from matimo.integrations.langchain import convert_tools_to_langchain
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate

matimo = await Matimo.init(get_tools_path())
lc_tools = convert_tools_to_langchain(
    matimo.list_tools(),
    matimo,
    credentials={'SLACK_BOT_TOKEN': os.environ['SLACK_BOT_TOKEN']},
)
llm = ChatOpenAI(model='gpt-4o-mini')
prompt = ChatPromptTemplate.from_messages([
    ('system', 'You are a Slack assistant.'),
    ('human', '{input}'),
    ('placeholder', '{agent_scratchpad}'),
])
agent = create_tool_calling_agent(llm, lc_tools, prompt)
executor = AgentExecutor(agent=agent, tools=lc_tools)
result = await executor.ainvoke({'input': 'List all public channels'})

Usage Notes

• The bot must be a member of a channel before it can post messages or read history
• Use slack_upload_file (not the deprecated files.upload) for file uploads
• slack_search_messages requires the search:read scope which needs special approval from Slack
• Rate limits apply - add delays between rapid API calls in bulk operations

Documentation

• Slack Integration Guide
• Slack Web API Reference
• Python Examples

Links

• PyPI: https://pypi.org/project/matimo-slack/
• GitHub: https://github.com/tallclub/matimo
• Slack API Docs: https://api.slack.com/