A Slack bot that lets your team chat with a Neo4j graph database in natural language. Ask questions in plain English - the bot translates them into Cypher queries and returns results directly in Slack.

You:      Who are the key bridges between departments?
Bot:      Based on betweenness centrality, Alice Chen and Bob Kumar connect ...

Slack (DM or @mention)
        │
        ▼
  Slack Bot (app.py)          ← Python, runs locally or on a server
        │
        ▼
  Neo4j Agent API             ← Hosted AI agent on neo4j.io
  /invoke endpoint            ← Translates NL → Cypher, runs query, returns answer
        │
        ▼
  Neo4j Graph Database        ← Your data

The Neo4j Agent is an AI-powered service that translates natural language to Cypher, executes it against your graph, and returns a human-readable answer. No LLM API key needed - the intelligence is built into the agent.

1. Go to api.slack.com/apps → Create New App → From a manifest
2. Select your workspace and paste the manifest below:

display_information:
  name: Neo4j Bot
  description: Chat with your Neo4j graph using natural language
  background_color: "#003865"

features:
  bot_user:
    display_name: Neo4j Bot
    always_online: true
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false

oauth_config:
  scopes:
    bot:
      - chat:write
      - app_mentions:read
      - im:history
      - im:read
      - im:write
      - channels:history

settings:
  event_subscriptions:
    bot_events:
      - app_mention
      - message.im
  interactivity:
    is_enabled: false
  org_deploy_enabled: false
  socket_mode_enabled: true
  token_rotation_enabled: false

3. Click Next → Create

1. Log in to console.neo4j.io
2. Navigate to your project → Agents
3. Create or select a Graph Agent connected to your database
4. From the agent settings, copy:
   • Invoke URL - looks like https://api.neo4j.io/v2beta1/organizations/.../agents/.../invoke
   • Client ID and Client Secret - used for OAuth2 authentication

git clone https://github.com/neo4j-field/neo4j-slack-bot
cd neo4j-slack-bot

cp .env.example .env

Edit .env and fill in all values:

SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...
SLACK_SIGNING_SECRET=...
NEO4J_INVOKE_URL=https://api.neo4j.io/v2beta1/organizations/<org-id>/projects/<project-id>/agents/<agent-id>/invoke
NEO4J_CLIENT_ID=...
NEO4J_CLIENT_SECRET=...

python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate

pip install -r requirements.txt

python app.py
# Neo4j Slack Bot is running! Press Ctrl+C to stop.

The bot uses Socket Mode - no public URL or ngrok needed.

Direct message the bot:

How many employees are in the Engineering department?

Or @mention it in a channel (after /invite @Neo4j Bot):

@Neo4j Bot who owns the most open opportunities?

Org & Reporting

• Who does [name] report to?
• Show me the org chart for the Sales department
• Who manages both direct reports and customer accounts?

Skills & Staffing

• Which employees have Python and SQL skills?
• Find employees most similar to [name] based on skills

Customers & Opportunities

• Which employees support the most customers?
• List all open opportunities linked to customers in London

Graph Analytics (GDS)

• Which employees act as key bridges between departments?
• Identify natural clusters of employees based on their connections
• Who are the most influential employees by PageRank?

.
├── app.py              # Slack bot + Neo4j agent integration
├── requirements.txt    # Python dependencies
├── .env.example        # Environment variable template
└── .gitignore

Bot not responding in Slack

• Make sure python app.py is running and shows "Bolt app is running!"
• Check the bot is invited to the channel: /invite @Neo4j Bot

401 Unauthorized from Neo4j

• Double-check NEO4J_CLIENT_ID and NEO4J_CLIENT_SECRET in .env
• Verify the agent is active in console.neo4j.io

ModuleNotFoundError

• Make sure your virtual environment is activated: source .venv/bin/activate
• Re-run pip install -r requirements.txt

Neo4j

• Neo4j Aura Agent - Developer Guide
• Neo4j Aura Docs
• Neo4j Graph Data Science (GDS)
• Neo4j Aura Console

Slack

• Slack API Docs