Slack

@housecall connects to Slack over Socket Mode, so it needs no public URL. It works behind a firewall or on a laptop.

1. Create the app

1. Go to api.slack.com/apps and choose Create New App, then From a manifest.
2. Pick your workspace and paste the contents of deploy/slack-manifest.yml from your project.

The manifest turns on Socket Mode and interactivity, subscribes to the app_mention and message.im events, and requests these bot scopes:

app_mentions:read  chat:write  channels:history  groups:history  im:history  files:read

files:read lets @housecall download screenshots. If you created the app before this scope was in the manifest, add files:read under OAuth & Permissions and reinstall the app. Until then, Slack answers downloads with its sign-in page, @housecall logs [attachments] slack <file>: ... answered with a web page, not the file, and the model is told it could not see the image.

Under Basic Information → Display Information, upload deploy/icon.png from your project as the app icon.

2. Get the tokens

1. Basic Information → App-Level Tokens → Generate Token and Scopes. Add the connections:write scope. This is your xapp- token.
2. Install App → Install to Workspace. Copy the Bot User OAuth Token. This is your xoxb- token.

SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

3. Enable it

chat:
  slack: { enabled: true }

docker compose -f deploy/docker-compose.yml up -d --build

Invite the app to a channel before mentioning it there:

/invite @housecall

How it behaves

• It always answers in a thread under the message.
• In channels it answers messages that mention it. When mentioned inside a thread, it first reads the replies it hasn’t seen yet.
• In a DM no mention is needed. Each top-level DM starts a conversation, and every reply in its thread continues it.
• It first posts “Looking into it…”, then edits that message into the answer.
• Approvals show as Approve and Deny buttons in the thread. If someone else clicks, they get a note only they can see.
• Messages sent while @housecall is stopped are not answered. Ask again once it is back.
• Images attached to a DM or to a message that mentions @housecall are downloaded with the bot token. When mentioned in a thread, it also reads the images that person posted in the thread since its last reply. Files shared from another organization through Slack Connect are skipped.