Slack Integration

• slack_search lets the agent search the workspace with the permissions of the person who asked.
• slack_post_message lets an agent reached over HTTP, A2A, or the CLI post into a channel as the bot, so an alert-driven or scheduled run can report into Slack.

​

Create the Slack app

{
  "display_information": {
    "name": "AURA"
  },
  "features": {
    "bot_user": {
      "display_name": "aura",
      "always_online": true
    },
    "app_home": {
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "agent_view": {
      "agent_description": "Answers questions in threads and direct messages and searches public channels with the permissions of the person asking."
    }
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "app_mentions:read",
        "chat:write",
        "channels:history",
        "groups:history",
        "im:history",
        "reactions:write",
        "search:read.public",
        "assistant:write"
      ]
    }
  },
  "settings": {
    "event_subscriptions": {
      "bot_events": [
        "app_mention",
        "message.im",
        "message.channels",
        "message.groups",
        "app_home_opened"
      ]
    },
    "org_deploy_enabled": false,
    "socket_mode_enabled": true,
    "token_rotation_enabled": false
  }
}

1. Under Basic Information → App-Level Tokens, generate a token with the connections:write scope. This is the xapp- token.
2. Under Install App, install the app to the workspace. The Bot User OAuth Token on that page is the xoxb- token.
3. Invite the bot to any channel it should answer in (/invite @aura).

​

Enable the ingress

AURA_ENABLE_SLACK=true \
AURA_SLACK_BOT_TOKEN=xoxb-... \
AURA_SLACK_APP_TOKEN=xapp-... \
AURA_SLACK_AGENT="My Agent" \
aura webserver

​

What the bot answers

​

Replies without a mention

​

Search Slack as the asker

• The tool takes query, an optional limit, and an optional cursor for the next page.
• Plain words or a natural-language question find things; quoted phrases and OR chains usually return nothing.
• One message has a budget of six searches shared by every agent working on it; a spent budget comes back as a tool error. Slack also rate limits searches per person, so the prompt tells the agent to spend one plain query first and reword at most once.
• The system prompt gains a citation instruction: results are cited inline as <permalink|label>, which Slack renders as a link.
• A bot token can hold only search:read.public (plus search:read.files and search:read.users), so only public channels are searched. The search scopes for private channels, direct messages, and group direct messages exist for user tokens only.
• Under orchestration, every worker gets its own instance of the tool; the coordinator, whose tools are routing only, gets none.

​

Post to Slack from any ingress

[agent]
name = "Alert Reporter"
enable_slack_tools = true

• Arguments: channel (an id such as C0123456789 or a name such as #incidents), text (mrkdwn), and an optional thread_ts to reply in a thread.
• Returns the message ts, the channel id, and a permalink the agent can cite.
• One run may post five times. Under orchestration every worker gets an instance and the run shares one budget.
• Slack errors are rephrased for the agent (channel not found, bot not a member, archived, text too long, missing scope, rate limited) and never carry the token.
• GET /aura/info?detail=tools lists the tool under the opted-in agent, beside its MCP servers.

​

Connection lifecycle

• Slack asks for a fresh Socket Mode connection roughly every five hours; the server reconnects at once.
• Any other end of the connection, including a peer that drops the link, reconnects after a delay that doubles from one second up to one minute.
• A connection with no frame for two minutes, Slack’s keepalive pings included, is dropped and redialled. A network path that dies without a close (a route change, an expired NAT entry) would otherwise leave the connection established and silent forever.
• Slack-driven runs count as active requests: on SIGTERM the server stops accepting new messages and gives in-flight runs the SHUTDOWN_TIMEOUT_SECS grace period.

​

Limitations

• No human-in-the-loop approvals. The conversational Slack surface has nowhere to approve a tool call, so the ingress refuses to start on an agent config that has a [hitl] block (the error names the agent). Give the Slack agent a config without [hitl], and keep gated write tools out of its mcp_filter since nothing would gate them. The HITL webhook route remains available to the same server’s HTTP and A2A callers.
• Thread follow-ups cannot search. Slack attaches the action_token to mention and direct-message events but not to the thread replies delivered by message.channels and message.groups. A reply without a mention therefore runs without slack_search, even in a thread whose first question had it. Mentioning the bot in the follow-up restores the tool. Tracked as mezmo/aura#776.
• Public channels only. slack_search sees what search:read.public allows. Private channels, direct messages, and group direct messages are not searchable with a bot token.
• Orchestration planners may not see run tools. With tools_in_planning = "summary", the planner lists the first max_tools_per_worker tool names per worker (default 10) and the run’s own tools come last, so on workers with long mcp_filter lists slack_search hides behind (+N more). Raise max_tools_per_worker, or tell the coordinator in its system prompt that every worker holds slack_search on a run that a mention or DM started.
• One agent per server. The ingress runs the agent named by --slack-agent; other loaded configs stay reachable over HTTP and A2A only.
• Replies come from the bot, not the agent that was asked. Runs started from Slack reply in place and do not get slack_post_message; cross-posting from a Slack-started run is not supported.

​

See also

• Web Server Reference: the full flag and environment-variable list
• Configuration Reference: enable_slack_tools and the [orchestration] planner settings
• HITL: approval gates on the HTTP and A2A paths