StandUp Mate - User Troubleshooting Guide

When Users Can't Open Standup Modals

If a user reports they cannot open their standup when clicking the "Start Standup" button, here are the steps to diagnose and fix the issue:

Immediate Diagnosis

Run the diagnostics tool to check the user's status:

python slack_diagnostics.py  diagnose

This will show:

• Whether the user is included in active standups
• If they've already submitted responses
• Slack workspace permissions
• Recommendations for fixing the issue

Common Issues and Solutions

1. User Already Submitted

Symptom: User sees "Already Submitted ✅" button Solution: This is normal - user has already completed their standup for today

2. Slack Modal Not Opening

Symptoms:

• Button clicks but nothing happens
• Modal doesn't appear

Solutions:

1. Refresh Slack: Ask user to refresh their Slack client
2. Resend Standup: Use the resend command:

   python slack_diagnostics.py  resend

   

1. Check App Permissions: Verify StandUp Mate has proper workspace permissions
2. Reinstall App: If persistent, remove and re-add the Slack app

3. Network/Connectivity Issues

Symptom: Intermittent failures Solution: These usually resolve automatically. Try resending the standup.

4. User Not Found in Workspace

Symptom: Diagnostics shows "User not found in workspace user list" Possible Causes:

• User has restricted permissions
• User is in private channels not visible to bot
• Rate limiting from Slack API

Solutions:

• Check if user is actually in the workspace
• Verify bot has access to channels where user is a member
• Wait and try again if rate limited

Step-by-Step Resolution Process

1. Run Diagnostics:

   python slack_diagnostics.py  diagnose

   

1. If user hasn't responded, try resending:

   python slack_diagnostics.py  resend

   

1. If still failing:

- Ask user to refresh Slack

- Check if user can see the StandUp Mate app in their workspace

- Verify app permissions in Slack admin settings

1. Last resort:

- Remove and reinstall the StandUp Mate app in the workspace

- This will require re-authentication

Prevention Tips

• Monitor the application logs for interaction errors
• Set up alerts for failed standup deliveries
• Regular health checks on Slack API connectivity
• Keep the app permissions up to date

Getting User IDs

To find a user's Slack ID:

1. Go to the user's Slack profile
2. Click "More" → "Copy member ID"
3. Or check the standup logs for their ID when standups are sent

5. "Unknown User" Display Issues

Symptom: Standup responses show "Unknown User" or "User-XXXX" instead of real names Causes:

• Slack API rate limiting during high usage
• Bot token missing user read permissions
• Network connectivity issues

Solutions:

1. Wait for rate limits to clear (usually resolves in 1-2 minutes)
2. Refresh user cache:

   python fix_user_display.py

   

1. Check bot permissions in Slack app settings
2. Update OAuth scopes to include users:read

6. Non-Clickable Standup Buttons

Symptom: Users can see standup message but "Start Standup" button doesn't work Root Cause: Slack app Interactive Components not configured Solutions:

1. Configure Interactive Components:

- Go to https://api.slack.com/apps

- Select your StandUp Mate app

- Go to "Interactivity & Shortcuts"

- Turn ON "Interactivity"

- Set Request URL: https://your-domain.replit.app/slack/interactive

- Save changes

1. Verify OAuth scopes include:

- chat:write

- im:write

- channels:read

- users:read

1. Reinstall app if needed after scope changes

Example Workflow for Joseph's Issue

1. Diagnose the problem
python slack_diagnostics.py U016XUR9PAQ diagnose

2. Try resending if needed
python slack_diagnostics.py U016XUR9PAQ resend

3. Check logs for any errors
grep -i "U016XUR9PAQ" logs/*.log

4. Fix user display issues
python fix_user_display.py

This should resolve most standup modal issues users encounter.

---

API Documentation

StandUp Mate provides a simple REST API for programmatically managing team members. This is useful for integrating with your HR systems, employee onboarding tools, or other automation workflows.

Authentication

All API requests require an API key to be sent in the X-API-Key header:

X-API-Key: your-api-key-here

Your API Key: Found in your .env file as API_SECRET_KEY Security Note: Keep your API key secure and never commit it to version control.

Base URL

http://localhost:5002

For production deployments, use your production domain (e.g., https://standup.yourcompany.com).

Endpoints

1. Health Check

Simple health check endpoint to verify the API is running.

Endpoint: GET /api/health Request Headers: None required Success Response (200 OK):

{
  "status": "ok"
}

Example with cURL:

curl http://localhost:5002/api/health

Notes:

• No authentication required
• Useful for monitoring and load balancer health checks
• Returns 200 OK if the API is responsive

---

2. Add Employee to Team

Add an employee to a team by their email address. If the team doesn't exist, it will be created automatically.

Endpoint: POST /api/sync/add-employee Request Headers:

X-API-Key: your-api-key-here
Content-Type: application/json

Request Body:

{
  "email": "employee@company.com",
  "team_name": "Engineering"
}

Success Response (200 OK):

{
  "message": "Employee added successfully",
  "user_id": "U12345ABC",
  "user_name": "John Doe",
  "team_name": "Engineering"
}

Example with cURL:

curl -X POST "http://localhost:5002/api/sync/add-employee" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"email": "john@company.com", "team_name": "Engineering"}'

Notes:

• The employee must already exist in your Slack workspace
• Their email in the request must match their Slack email
• If they're already in the team, you'll get a success message (idempotent)
• The employee is automatically added to all standup schedules for that team

---

3. Remove Employee from Teams

Remove an employee from all teams by their email address.

Endpoint: POST /api/sync/remove-employee Request Headers:

X-API-Key: your-api-key-here
Content-Type: application/json

Request Body:

{
  "email": "employee@company.com"
}

Success Response (200 OK):

{
  "message": "Employee removed successfully",
  "user_id": "U12345ABC",
  "user_name": "John Doe",
  "teams_removed": ["Engineering", "Product"]
}

Example with cURL:

curl -X POST "http://localhost:5002/api/sync/remove-employee" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"email": "john@company.com"}'

Notes:

• Removes the employee from ALL teams they're a member of
• Also removes them from all associated standup schedules
• If they're not in any teams, you'll get a success message (idempotent)

---

Error Responses

401 Unauthorized

{
  "error": "Invalid API key"
}

Cause: Missing or incorrect API key in the X-API-Key header

---

400 Bad Request

{
  "error": "email and team_name required"
}

Cause: Missing required fields in the request body

---

404 Not Found

{
  "error": "User with email john@company.com not found in Slack"
}

Cause: The email doesn't match any user in your Slack workspace

---

500 Internal Server Error

{
  "error": "Failed to add employee: [error details]"
}

Cause: Server-side error (check application logs)

---

Integration Examples

Python Example

import requests

API_KEY = "your-api-key-here"
BASE_URL = "http://localhost:5002"

def add_employee_to_team(email, team_name):
    """Add an employee to a team"""
    response = requests.post(
        f"{BASE_URL}/api/sync/add-employee",
        headers={
            "X-API-Key": API_KEY,
            "Content-Type": "application/json"
        },
        json={
            "email": email,
            "team_name": team_name
        }
    )
    return response.json()

def remove_employee(email):
    """Remove an employee from all teams"""
    response = requests.post(
        f"{BASE_URL}/api/sync/remove-employee",
        headers={
            "X-API-Key": API_KEY,
            "Content-Type": "application/json"
        },
        json={"email": email}
    )
    return response.json()

Usage
result = add_employee_to_team("john@company.com", "Engineering")
print(result)

Node.js Example

const axios = require('axios');

const API_KEY = 'your-api-key-here';
const BASE_URL = 'http://localhost:5002';

async function addEmployeeToTeam(email, teamName) {
  const response = await axios.post(
    ${BASE_URL}/api/sync/add-employee,
    {
      email: email,
      team_name: teamName
    },
    {
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );
  return response.data;
}

async function removeEmployee(email) {
  const response = await axios.post(
    ${BASE_URL}/api/sync/remove-employee,
    { email: email },
    {
      headers: {
        'X-API-Key': API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );
  return response.data;
}

// Usage
addEmployeeToTeam('john@company.com', 'Engineering')
  .then(result => console.log(result))
  .catch(error => console.error(error));

---

Common Use Cases

1. Automated Onboarding

When a new employee joins, automatically add them to their team's standups:

Add new employee to their team
curl -X POST "http://localhost:5002/api/sync/add-employee" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"email": "newemployee@company.com", "team_name": "Engineering"}'

2. Automated Offboarding

When an employee leaves, remove them from all standups:

Remove employee from all teams
curl -X POST "http://localhost:5002/api/sync/remove-employee" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"email": "former@company.com"}'

3. Team Reorganization

Bulk add employees to a new team:

Script to add multiple employees to a new team
for email in employee1@company.com employee2@company.com employee3@company.com; do
  curl -X POST "http://localhost:5002/api/sync/add-employee" \
    -H "X-API-Key: your-api-key-here" \
    -H "Content-Type: application/json" \
    -d "{\"email\": \"$email\", \"team_name\": \"New Product Team\"}"
done

---

Best Practices

1. Error Handling: Always check the response status code and handle errors gracefully
2. Idempotency: The API is idempotent - you can safely retry requests
3. Rate Limiting: For bulk operations, add a small delay between requests
4. Security: Store your API key securely in environment variables
5. Validation: Verify the employee exists in Slack before calling the API
6. Logging: Log API calls for audit trails and debugging

---

FAQ

Q: What happens if I add an employee to a team they're already in?

A: You'll get a success response saying "User already in team" - the operation is idempotent.

Q: Can I add someone who's not in our Slack workspace?

A: No, the user must already exist in your Slack workspace. You'll get a 404 error if they don't exist.

Q: Does removing an employee delete them from Slack?

A: No, it only removes them from StandUp Mate teams and schedules. Their Slack account is unaffected.

Q: Can I specify which schedules to add them to?

A: No, they're automatically added to all schedules for their team. You can manage schedules through the web UI.

Q: How do I get a new API key?

A: Generate a new secure key and update the API_SECRET_KEY in your .env file, then restart the application.

---

Support

For API issues or questions:

1. Check the application logs for detailed error messages
2. Verify your API key is correct
3. Ensure the employee exists in Slack with the correct email
4. Contact your StandUp Mate administrator