How to Automate Discord Welcome Messages using the API

Understanding the Discord API

Setting Up Discord API Authentication

Bot tokens are static credentials that do not expire until reset. You must also enable the GUILD_MEMBERS privileged intent in two places: the Developer Portal toggle AND your code's intent bitmask. Mismatching these causes Gateway close code 4014 — the bot connects but receives no member events.

1. 1Go to https://discord.com/developers/applications and click New Application.
2. 2Open the Bot tab. Click Reset Token — copy it immediately (shown once).
3. 3Under Privileged Gateway Intents, toggle on Server Members Intent.
4. 4Open OAuth2 > URL Generator. Select scopes: bot and applications.commands.
5. 5Under Bot Permissions, check: Send Messages, Embed Links, View Channels.
6. 6Copy the generated URL and invite the bot to your test server.
7. 7Create or identify your welcome channel and copy its ID (right-click channel > Copy Channel ID).
8. 8Store DISCORD_BOT_TOKEN and DISCORD_WELCOME_CHANNEL_ID in environment variables.

1import os
2import discord
3
4# discord.py v2.7.1 requires Python 3.8+
5# Install: pip install discord.py
6
7BOT_TOKEN = os.environ["DISCORD_BOT_TOKEN"]
8WELCOME_CHANNEL_ID = int(os.environ["DISCORD_WELCOME_CHANNEL_ID"])
9
10# Enable GUILD_MEMBERS intent in code — must match Developer Portal setting
11intents = discord.Intents.default()
12intents.members = True  # Enables GUILD_MEMBER_ADD events
13
14client = discord.Client(intents=intents)
15
16@client.event
17async def on_ready():
18    print(f"Bot connected as {client.user}")
19
20client.run(BOT_TOKEN)

Key endpoints

1{"content":"<@123456789>","embeds":[{"title":"Welcome to the Server!","description":"We're glad you're here, <@123456789>! Read the rules in #rules and introduce yourself in #introductions.","color":5814783,"thumbnail":{"url":"https://cdn.discordapp.com/avatars/123456789/avatar_hash.png"},"footer":{"text":"Member #42"}}]}

1{"id":"998877665544","type":0,"content":"<@123456789>","channel_id":"111222333444","author":{"id":"bot_id","username":"WelcomeBot","bot":true},"embeds":[{"title":"Welcome to the Server!","description":"We're glad you're here!","color":5814783}],"timestamp":"2026-05-07T10:00:00.000Z"}

1[{"user":{"id":"123456789","username":"johndoe","avatar":"abc123"},"roles":["role_id"],"joined_at":"2026-05-07T10:00:00.000Z","deaf":false,"mute":false}]

1{"id":"555555555555","name":"My Server","approximate_member_count":1247,"approximate_presence_count":423}

Step-by-step automation

1# Verify GUILD_MEMBER_ADD arrives by checking bot flags
2curl -s -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
3  "https://discord.com/api/v10/users/@me" | python3 -m json.tool

1# Send a welcome embed directly
2curl -X POST \
3  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
4  -H "Content-Type: application/json" \
5  -d "{
6    \"content\": \"<@$USER_ID>\",
7    \"embeds\": [{
8      \"title\": \"Welcome to the server!\",
9      \"description\": \"We're happy you're here, <@$USER_ID>! Check out #rules and introduce yourself.\",
10      \"color\": 5814783,
11      \"thumbnail\": {\"url\": \"$AVATAR_URL\"},
12      \"footer\": {\"text\": \"Member #1247\"}
13    }]
14  }" \
15  "https://discord.com/api/v10/channels/$WELCOME_CHANNEL_ID/messages"

1# This step is triggered by a Gateway event — no cURL equivalent
2# For testing, manually send a welcome message:
3curl -X POST \
4  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
5  -H "Content-Type: application/json" \
6  -d '{"content":"<@USER_ID> Welcome!","embeds":[{"title":"Welcome!","color":5765632}]}' \
7  "https://discord.com/api/v10/channels/$WELCOME_CHANNEL_ID/messages"

1# Check rate limit headers after posting
2curl -v -X POST \
3  -H "Authorization: Bot $DISCORD_BOT_TOKEN" \
4  -H "Content-Type: application/json" \
5  -d '{"content":"Test"}' \
6  "https://discord.com/api/v10/channels/$WELCOME_CHANNEL_ID/messages" \
7  2>&1 | grep -i 'x-ratelimit'

Complete working code

A complete discord.py bot that listens for GUILD_MEMBER_ADD events, builds a formatted welcome embed with the user's avatar and member count, and posts it to a designated welcome channel with rate-limit-safe queuing. Runs continuously as a process.

1import os, asyncio, logging
2from collections import deque
3import discord
4
5logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
6
7BOT_TOKEN = os.environ["DISCORD_BOT_TOKEN"]
8WELCOME_CHANNEL_ID = int(os.environ["DISCORD_WELCOME_CHANNEL_ID"])
9
10intents = discord.Intents.default()
11intents.members = True  # Required for GUILD_MEMBER_ADD
12
13client = discord.Client(intents=intents)
14welcome_queue = deque()
15
16def build_embed(member: discord.Member) -> discord.Embed:
17    embed = discord.Embed(
18        title=f"Welcome to {member.guild.name}!",
19        description=(
20            f"{member.mention}, we're glad you joined!\n\n"
21            f"Read the rules and get started."
22        ),
23        color=discord.Color.green()
24    )
25    embed.set_thumbnail(url=member.display_avatar.url)
26    embed.set_footer(text=f"Member #{member.guild.member_count}")
27    embed.timestamp = discord.utils.utcnow()
28    return embed
29
30async def queue_processor():
31    await client.wait_until_ready()
32    channel = client.get_channel(WELCOME_CHANNEL_ID)
33    if channel is None:
34        logging.error(f"Welcome channel {WELCOME_CHANNEL_ID} not found")
35        return
36    logging.info(f"Welcome queue processor started, posting to #{channel.name}")
37    while not client.is_closed():
38        if welcome_queue:
39            member = welcome_queue.popleft()
40            try:
41                await channel.send(content=member.mention, embed=build_embed(member))
42                logging.info(f"Welcomed {member.name} (guild: {member.guild.name})")
43            except discord.HTTPException as e:
44                logging.error(f"Failed to welcome {member.name}: {e}")
45        await asyncio.sleep(1.0)  # Max 1 welcome/second — stays under rate limit
46
47@client.event
48async def on_ready():
49    logging.info(f"Connected as {client.user}")
50    client.loop.create_task(queue_processor())
51
52@client.event
53async def on_member_join(member: discord.Member):
54    logging.info(f"{member.name} joined — queued welcome")
55    welcome_queue.append(member)
56
57client.run(BOT_TOKEN)
58

Error handling

Rate Limits for Discord API

1import asyncio
2from collections import deque
3
4class WelcomeQueue:
5    def __init__(self, rate=1.0):
6        self.queue = deque()
7        self.rate = rate  # messages per second
8
9    async def add(self, member):
10        self.queue.append(member)
11
12    async def process(self, channel, send_func):
13        while True:
14            if self.queue:
15                member = self.queue.popleft()
16                try:
17                    await send_func(channel, member)
18                except Exception as e:
19                    print(f'Error: {e}')
20            await asyncio.sleep(1.0 / self.rate)

• Process welcome messages through a queue at 1/second to stay well under the 5/5s per-channel limit.
• Cache the welcome channel object at startup — calling client.get_channel() on every event is free (in-memory cache), but fetching from the API on every join is wasteful.
• Monitor join rate: if joins exceed 60/minute for 3+ minutes, switch to a batched welcome ('Welcome to our 20 newest members: @user1, @user2...') to reduce message volume.
• Store the welcome channel ID in config, not hardcoded — makes it easy to switch channels without redeploying.
• Test with a rate limit simulator: join the server from 10 alt accounts in quick succession to verify your queue handles the load correctly.

Security checklist

Automation use cases

No-code alternatives

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

Best practices

• Enable GUILD_MEMBERS privileged intent in both the Developer Portal AND your code — mismatch causes silent failure or close code 4014.
• Always check that the welcome channel exists (not null) before trying to send — channel IDs can become invalid if the channel is deleted.
• Queue welcome messages and process at 1/second to handle join raids without hitting the 5 messages/5 seconds per-channel limit.
• Include the user's mention (not just username) in the content field outside the embed — this triggers the mobile push notification that welcome messages in embeds alone do not send.
• Cache the welcome channel object at startup using client.get_channel() rather than fetching it from the API on every join event.
• Use member.display_avatar.url (discord.py) or member.user.displayAvatarURL() (discord.js) for the thumbnail — these handle the default avatar fallback when the user has no custom avatar.
• Test by joining your test server from a second account — the actual join event is the only reliable way to verify the setup works end-to-end.

Ask AI to help

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

Related automations

Explore related guides

Guides from other topics that help with this issue