How to Automate Slack Team Onboarding using the API

Understanding the Slack API

Setting Up Slack API Authentication

Bot tokens (xoxb-) are workspace-scoped and long-lived by default. Team onboarding requires the team_join event subscription, chat:write scope for messaging, conversations:invite for channel additions, and users:read if you need to look up user details. The 3-second ack deadline on events is enforced strictly — always respond immediately and process asynchronously.

1. 1Go to https://api.slack.com/apps and click Create New App > From scratch.
2. 2Name your app and select your workspace.
3. 3Click OAuth & Permissions in the left sidebar. Add Bot Token Scopes: chat:write, conversations:invite, channels:read, users:read, im:write (for DMs).
4. 4Click Event Subscriptions in the left sidebar. Toggle Enable Events to On.
5. 5Set the Request URL to your app's HTTPS endpoint (e.g., https://yourapp.com/slack/events). Slack will verify by sending a challenge.
6. 6Under Subscribe to bot events, add: team_join.
7. 7Click Install to Workspace and authorize. Copy the Bot User OAuth Token (xoxb-).
8. 8Store SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET in environment variables.

1import os
2from slack_bolt import App
3from slack_bolt.adapter.flask import SlackRequestHandler
4from flask import Flask, request
5
6# pip install slack-bolt flask
7app = App(token=os.environ["SLACK_BOT_TOKEN"],
8          signing_secret=os.environ["SLACK_SIGNING_SECRET"])
9
10@app.event("team_join")
11def handle_team_join(event, say, client, logger):
12    user_id = event["user"]["id"]
13    logger.info(f"New member joined: {user_id}")
14    # Note: ack() is handled automatically by Bolt
15    # Do work here or dispatch to async task
16
17flask_app = Flask(__name__)
18handler = SlackRequestHandler(app)
19
20@flask_app.route("/slack/events", methods=["POST"])
21def events():
22    return handler.handle(request)
23
24if __name__ == "__main__":
25    flask_app.run(port=3000)

Key endpoints

1{"channel":"C01234567","users":"U0987654"}

1{"ok":true,"channel":{"id":"C01234567","name":"general","is_member":true}}

1{"channel":"U0987654","text":"Welcome to the team!","blocks":[{"type":"section","text":{"type":"mrkdwn","text":"*Welcome to Acme Inc!* :wave:\n\nHere's your onboarding checklist:\n- [ ] Read the handbook\n- [ ] Set up 2FA\n- [ ] Introduce yourself in #introductions"}}]}

1{"ok":true,"channel":"D01234567","ts":"1746612000.000100","message":{"type":"message","text":"Welcome to the team!"}}

1{"channel":"C01234567","user":"U0987654","text":"Welcome! Only you can see this message."}

1{"ok":true,"message_ts":"1746612000.000200"}

1{"ok":true,"channels":[{"id":"C01234567","name":"general"},{"id":"C02345678","name":"announcements"}],"response_metadata":{"next_cursor":""}}

Step-by-step automation

1# Handle Slack's URL verification challenge
2# Your endpoint must respond with: {"challenge": "<value from request>"}
3# Test your endpoint is reachable:
4curl -X POST \
5  -H "Content-Type: application/json" \
6  -d '{"type":"url_verification","challenge":"test_challenge_123"}' \
7  "https://yourapp.com/slack/events"

1curl -X POST \
2  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{"channel":"C01234567","users":"U0987654"}' \
5  "https://slack.com/api/conversations.invite"

1curl -X POST \
2  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "channel": "U0987654",
6    "text": "Welcome to the team!",
7    "blocks": [
8      {"type":"section","text":{"type":"mrkdwn","text":"*Welcome to Acme Inc, <@U0987654>!* :wave:"}},
9      {"type":"section","text":{"type":"mrkdwn","text":"*Your onboarding checklist:*\n:white_square_button: Read the <https://handbook.acme.com|Employee Handbook>\n:white_square_button: Set up <https://mfa.acme.com|2FA> on your accounts\n:white_square_button: Introduce yourself in <#C04444444>\n:white_square_button: Book your first <https://calendly.com/manager|1:1 with your manager>"}}
10    ]
11  }' \
12  "https://slack.com/api/chat.postMessage"

1# Your endpoint should respond 200 immediately
2# Test response time:
3time curl -s -o /dev/null -w '%{time_total}' -X POST \
4  -H "Content-Type: application/json" \
5  -d '{"type":"event_callback","event":{"type":"team_join","user":{"id":"U123"}}}' \
6  "https://yourapp.com/slack/events"
7# Target: < 1.0 seconds

Complete working code

A complete Slack onboarding bot built with slack-bolt and Flask. On team_join, it immediately acks the event, then invites the new user to configured default channels and sends a personalized DM with an onboarding checklist.

1import os, logging
2from slack_bolt import App
3from slack_bolt.adapter.flask import SlackRequestHandler
4from flask import Flask, request as flask_req
5
6logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
7
8app = App(
9    token=os.environ["SLACK_BOT_TOKEN"],
10    signing_secret=os.environ["SLACK_SIGNING_SECRET"]
11)
12
13# Configure your default channels here (use IDs, not names)
14DEFAULT_CHANNELS = [
15    os.environ.get("SLACK_CHANNEL_GENERAL", ""),
16    os.environ.get("SLACK_CHANNEL_TEAM", ""),
17    os.environ.get("SLACK_CHANNEL_RANDOM", "")
18]
19DEFAULT_CHANNELS = [c for c in DEFAULT_CHANNELS if c]  # Remove empty
20
21def invite_user(client, user_id: str) -> None:
22    for channel_id in DEFAULT_CHANNELS:
23        resp = client.conversations_invite(channel=channel_id, users=user_id)
24        if not resp["ok"] and resp.get("error") != "already_in_channel":
25            logging.warning(f"Invite to {channel_id} failed: {resp.get('error')}")
26
27def send_onboarding_dm(client, user_id: str) -> None:
28    blocks = [
29        {"type": "section", "text": {"type": "mrkdwn",
30             "text": f"*Welcome to the team, <@{user_id}>!* :tada:"}},
31        {"type": "divider"},
32        {"type": "section", "text": {"type": "mrkdwn", "text":
33             "*Your onboarding checklist:*\n"
34             ":white_square_button: Read the <https://handbook.example.com|Handbook>\n"
35             ":white_square_button: Set up 2FA on your accounts\n"
36             ":white_square_button: Introduce yourself in your team channel\n"
37             ":white_square_button: Schedule your first 1:1 with your manager"}},
38        {"type": "context", "elements": [{"type": "mrkdwn",
39             "text": "Questions? Post in #help-desk or DM @hr-bot"}]}
40    ]
41    resp = client.chat_postMessage(
42        channel=user_id,
43        text="Welcome to the team!",
44        blocks=blocks
45    )
46    if not resp["ok"]:
47        logging.error(f"Failed to DM {user_id}: {resp.get('error')}")
48
49@app.event("team_join")
50def handle_team_join(event, client, logger):
51    user = event.get("user", {})
52    user_id = user.get("id") if isinstance(user, dict) else user
53    if not user_id:
54        logger.warning("team_join event missing user ID")
55        return
56    logger.info(f"Onboarding new member: {user_id}")
57    invite_user(client, user_id)
58    send_onboarding_dm(client, user_id)
59    logger.info(f"Onboarding complete for: {user_id}")
60
61flask_app = Flask(__name__)
62handler = SlackRequestHandler(app)
63
64@flask_app.route("/slack/events", methods=["POST"])
65def events():
66    return handler.handle(flask_req)
67
68if __name__ == "__main__":
69    flask_app.run(port=int(os.environ.get("PORT", 3000)))
70

Error handling

Rate Limits for Slack API

1import time
2
3def slack_call_with_retry(client_method, max_retries=5, **kwargs):
4    for i in range(max_retries):
5        try:
6            return client_method(**kwargs)
7        except Exception as e:
8            if hasattr(e, 'response') and e.response.get('error') == 'ratelimited':
9                retry_after = int(e.response.headers.get('Retry-After', 2))
10                time.sleep(retry_after + 0.5)
11                continue
12            raise
13    raise RuntimeError('Max retries exceeded')

• Acknowledge team_join events within 3 seconds — always use Bolt or dispatch onboarding logic to a background thread.
• Add 100ms delays between sequential conversations.invite calls to stay well under the Tier 3 limit.
• Cache channel IDs at startup using conversations.list — avoid re-fetching on every onboarding event.
• Implement idempotency: log user IDs that have been onboarded and skip re-onboarding if the event is replayed.
• For large team migrations (100+ simultaneous joins), use a queue system to rate-limit onboarding tasks rather than processing all events simultaneously.

Security checklist

Automation use cases

No-code alternatives

Don't want to write code? These platforms can automate the same workflows visually.

Best practices

• Always respond to Slack event deliveries within 3 seconds — use Bolt which handles ack() automatically, or use Flask with background threads.
• Implement idempotency: track which users have been onboarded in a database. Slack can deliver the same event multiple times if your endpoint is slow.
• Cache channel IDs at startup with conversations.list — never fetch them on every onboarding event.
• Use user IDs (U...) as the channel in chat.postMessage to open DMs — do not try to find or open the DM channel ID manually.
• Handle already_in_channel responses gracefully — they are expected when users join channels they were previously in.
• Test the full flow by creating a test user in a dev workspace before deploying to production.
• For enterprise Slack workspaces, check if your app has org-wide install vs. workspace-install and whether team_join events are scoped to the workspace or org level.

Ask AI to help

Copy one of these prompts to get a personalized, working implementation.

Related automations