Slack

The SlackConnector integrates Machina with Slack using the Bolt SDK in Socket Mode — no public URL or ingress required.

Prerequisites

1. Create a Slack App at api.slack.com/apps
2. Enable Socket Mode in the app settings
3. Generate an App-Level Token (xapp-…) with connections:write scope
4. Install the app to your workspace and note the Bot User OAuth Token (xoxb-…)
5. Add the following Bot Token Scopes: chat:write, channels:read, channels:history

Installation

pip install machina-ai[slack]

Configuration

PythonYAML

from machina.connectors import Slack

slack = Slack(
    bot_token="xoxb-...",
    app_token="xapp-...",
    allowed_channel_ids=["C0123456789"],  # optional whitelist
)

connectors:
  messaging:
    type: slack
    bot_token: ${SLACK_BOT_TOKEN}
    app_token: ${SLACK_APP_TOKEN}
    allowed_channel_ids:
      - C0123456789

Capabilities

Capability	Method	Description
send_message	send_message(channel, text)	Send a message to a channel or DM
receive_message	listen(handler)	Receive messages via Socket Mode

Usage with Agent

from machina import Agent
from machina.connectors import Slack

agent = Agent(
    llm="openai:gpt-4o",
    connectors=[Slack(bot_token="xoxb-...", app_token="xapp-...")],
)
await agent.start()

Known Limitations

• Slash commands and interactive messages (buttons, modals) are not yet exposed as agent tools.
• Thread replies are sent as top-level messages (threading support planned).
• File uploads are not supported yet.

API Reference

SlackConnector

SlackConnector(*, bot_token: str = '', app_token: str = '', allowed_channel_ids: list[str] | None = None)

Connector for Slack via the Bolt SDK (Socket Mode).

Receives messages from technicians in Slack channels and sends responses back. Socket Mode uses a WebSocket connection so no public URL or ingress is required — ideal for on-premise plants.

Parameters:

Name	Type	Description	Default
bot_token	str	Slack Bot User OAuth Token (xoxb-…).	''
app_token	str	Slack App-Level Token (xapp-…) for Socket Mode.	''
allowed_channel_ids	list[str] | None	Optional whitelist of channel IDs that may interact.	None

Example

from machina.connectors import Slack

slack = Slack(bot_token="xoxb-...", app_token="xapp-...")
await slack.connect()

async def handler(msg):
    return f"Echo: {msg.text}"

await slack.listen(handler)

connect async

connect() -> None

Validate tokens and initialise the Slack Bolt application.

disconnect async

disconnect() -> None

Shut down the Slack Socket Mode handler.

health_check async

health_check() -> ConnectorHealth

Check Slack connectivity.

send_message async

send_message(channel: str, text: str) -> None

Send a message to a Slack channel or DM.

Parameters:

Name	Type	Description	Default
channel	str	Slack channel ID (e.g. C0123456789) or user ID for DMs.	required
text	str	Message text to send.	required

Raises:

Type	Description
ConnectorError	If not connected or the Slack API call fails.

listen async

listen(handler: MessageHandler) -> None

Start listening for incoming Slack messages via Socket Mode.

This is a blocking call that maintains the WebSocket connection until cancelled.

Parameters:

Name	Type	Description	Default
handler	MessageHandler	Async callback that receives an :class:IncomingMessage and returns the response text.	required