When I first started looking into how they worked, I assumed there had to be a huge amount of complicated code behind all of it.

But the basic idea is actually pretty simple.

At its core, a Discord bot is just a Python program that connects to Discord, waits for something to happen, and then decides how to respond. Once you understand that basic idea, you can start adding features one at a time and turn a simple bot into something much more interesting.

In this tutorial, we'll start with a very small bot and gradually build it into something more capable. Along the way, you'll learn about Discord commands, events, asynchronous Python, user state, environment variables, and basic deployment.

One quick disclaimer before we start: the mental-wellness feature that we'll be integrating in this bot in this project is not therapy, and the bot is not a therapist or medical professional. It should only provide general supportive suggestions and encourage users to reach out to a trusted person when appropriate.

With that out of the way, let's get coding!

What We'll Cover:

• What We're Building

• What You Need

• Create the Discord Bot

• Give the Bot Permission to Read Messages

• Create the Project

• Create a Virtual Environment

• Install discord.py

• Create Your First Bot

  • Importing Our Libraries

  • Loading the Token

  • Understanding Intents

  • What Isctx?

  • Why Does Everything Sayasyncandawait?

  • Run the Bot

• Build the Storytelling System

  • Let's Make the Story Remember the User

  • Add a Story Choice

  • Add a Casual Chat Command

  • Add a Mental-Wellness Support Feature

  • Add a Help Command

  • Improve Error Handling

• Put Everything Together

• Our Bot Doesn't Actually Remember Anything

  • Create the Database

  • Save a User's Story

  • Get the Story Back

  • Put It Into a Command

• Adding Real AI Chat

  • Install the Hugging Face Library

  • Create the Hugging Face Client

  • Connect the AI Model to the Bot

  • Handle AI Errors

• How Do We Keep the Bot Online?

  • Option 1: Run It on Your Computer

  • Option 2: Host It on a Server

• What "Forever" Actually Means

• Don't Try to "Keep It Awake" With Random Tricks

• Additional Features and Where to Go Next

• Test Everything Locally First

• Deploying the Bot

  • The Start Command

• Remember: Keep Your Secrets Secret

• What You Learned

• Final Thoughts

What We're Building

Our finished bot will have several commands:

!hello
!story
!chat hello!
!support I'm having a stressful day
!help

For example:

User:
!story

Bot:
You wake up inside an abandoned library.

There are three doors in front of you:

1. A red wooden door
2. A metal door covered in strange symbols
3. A staircase leading underground

Which one do you choose?

The user can then continue the story.

For chat:

User:
!chat What's a good way to learn Python?

Bot:
Try building small projects instead of only reading tutorials.
A Discord bot is actually a pretty fun project to start with.

And for mental-wellness support:

User:
!support I'm really stressed about school.

Bot:
That sounds like a lot to deal with. You could try breaking
the work into one small task at a time and taking a short
break between tasks.

I'm a bot, not a therapist, so if you need personal support,
consider talking with someone you trust.

The goal isn't to make a magical robot therapist. It's to build a useful bot while learning how Discord APIs, Python functions, events, asynchronous programming, and basic conversational logic fit together.

What You Need

You only need a few things:

• Python (version 3.8+ is recommended)

• A Discord account

• A Discord server where you have permission to add a bot

• A code editor (I personally prefer VS Code or PyCharm)

• The discord.py library

We'll also use Python's built-in os module for reading environment variables.

If you don't already have Python installed, install a current supported version of Python from the official Python website.

Then check that Python works:

python --version

You should see something similar to:

Python 3.x.x

Create the Discord Bot

Before Python can control Discord, we need to create a Discord application.

Go to the Discord Developer Portal: https://discord.com/developers/applications

This is what the page will look like, you might need to login with your discord email/username and password before you start.

Click on the "New Application" button on the top right and give your bot a name. For this tutorial, let's call ours StoryBot.

The application is basically the home for your bot.

Discord's developer platform provides the tools needed to create and configure applications and bots.

Once you've created the application, open its Bot section and create the bot user. You can add your own icon picture and your own banner if you want to.

You will then go to the Token section and click on "Reset Token" to generate your token. Treat that token like a password. Do NOT put it directly into your Python source code.

Never do this:

bot.run("my-secret-token")

And definitely don't upload a token to GitHub or commit it to source control. Instead, we'll store it in an environment variable, which we'll talk about later.

Give the Bot Permission to Read Messages

Our bot needs to see the messages that contain commands.

Discord uses something called Gateway Intents to control which types of events a bot receives. The discord.py documentation explains that intents must be enabled both in your code and, for privileged intents, in the Discord Developer Portal.

In the Developer Portal, find:

Bot
→ Privileged Gateway Intents

Enable:

Message Content Intent

It should look somewhat like this:

We'll also enable it in Python, which we will talk about later in this article.

Create the Project

Create a folder:

discord-story-bot/

Inside it, we'll eventually have:

discord-story-bot/
│
├── bot.py
├── requirements.txt
└── .env

The three important files are:

• bot.py: our Python program

• requirements.txt: text file that contains the name of the packages our bot needs

• .env: our secret token during local development

Create a Virtual Environment

Open your terminal inside the project folder.

Run:

python -m venv venv

Then activate it.

On Windows:

venv\Scripts\activate

On macOS/Linux:

source venv/bin/activate

A virtual environment gives this project its own little Python bubble.

That means packages installed for this bot won't randomly interfere with packages used by another project.

Install discord.py

Now install the Discord library:

pip install -U discord.py

The official discord.py documentation uses this installation approach for setting up the library.

We'll also install python-dotenv, which makes reading our local .env file easier:

pip install python-dotenv

Then save the dependencies:

pip freeze > requirements.txt

Your requirements.txt should contain the packages needed by the project.

Create Your First Bot

Let's start small.

Open bot.py:

import os

import discord
from discord.ext import commands
from dotenv import load_dotenv


load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)


@bot.event
async def on_ready():
    print(f"Logged in as {bot.user}")


@bot.command()
async def hello(ctx):
    await ctx.send("Hello! I'm online.")


bot.run(TOKEN)

That is already a functional Discord bot.

Let's break it apart piece by piece.

Importing Our Libraries

First:

import os

os lets Python communicate with parts of the operating system.

We'll use it to read environment variables.

Next:

import discord

This imports discord.py.

Then:

from discord.ext import commands

The commands extension makes creating commands much easier.

Instead of manually checking every message for something like !hello, we can write:

@bot.command()
async def hello(ctx):
    await ctx.send("Hello!")

The discord.py command system is built around Python functions decorated as commands.

Finally:

from dotenv import load_dotenv

This lets us load values from our .env file.

Loading the Token

Our bot needs a token to connect our Python program to Discord. Think of the token as a password that allows our program to authenticate as the bot.

We don't want to put this secret directly into our Python code. Instead, we'll store it in an environment variable.

First, install python-dotenv:

pip install python-dotenv

This package lets Python read values from a .env file.

Now create a new file called .env in the same folder as bot.py.

Inside .env, add:

DISCORD_TOKEN=YOUR_BOT_TOKEN_HERE

Replace YOUR_BOT_TOKEN_HERE with the token you copied from the Discord Developer Portal.

Your file should look something like this:

DISCORD_TOKEN=your_actual_token_here

Don't share this token with anyone or upload your .env file to GitHub. Your bot token should be treated like a password.

To make sure Git doesn't accidentally include the .env file in a repository, create a file called .gitignore in your project folder and add:

.env
venv/
__pycache__/

Now let's load the token in Python.

At the top of bot.py, add:

import os
from dotenv import load_dotenv

Then add:

load_dotenv()

This tells Python to look for the .env file and load the variables inside it.

Now we can get our Discord token:

TOKEN = os.getenv("DISCORD_TOKEN")

os.getenv() looks for the environment variable named "DISCORD_TOKEN" and gives us its value.

We can also check that the token was actually found:

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")

If Python can't find the token, the program stops and gives us a clear error message instead of failing later in a confusing way.

Understanding Intents

Remember how we talked about enabling message content readability in python? We are going to do that now.

Add:

intents = discord.Intents.default()
intents.message_content = True

The first line creates a set of Discord's default intents.

The second line tells Discord that our bot needs access to message content.

Now we need to give these intents to our bot when we create it:

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)

The command_prefix="!" means our bot will recognize commands that begin with !.

For example:

!hello

The intents=intents part gives our bot the permissions we configured above.

There are two steps here because Discord needs to know that our bot is allowed to receive message content, while our Python program also needs to tell Discord that it wants to receive it.

Our basic setup should now look like this:

import os
import discord

from dotenv import load_dotenv
from discord.ext import commands

load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")

intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)

Now our bot has its token safely loaded and discord.py knows which intents to request when it connects to Discord.

What Is ctx?

This part can look weird when you're learning Discord bots:

async def hello(ctx):

What is ctx? ctx stands for context. It contains information about the command that was used.

For example, it can tell us:

• Who ran the command

• Which server it came from

• Which channel it came from

• What message triggered it

Then:

await ctx.send("Hello!")

means:

"Send this message back to the place where the command was used."

Why Does Everything Say async and await?

You might notice:

async def hello(ctx):

and:

await ctx.send(...)

Discord bots spend a lot of time waiting.

They wait for:

• Messages

• Discord responses

• API requests

• Timers

• Other events

Python's asynchronous programming features allow the bot to wait for these operations without freezing everything else.

You don't need to become an async-programming expert before building your first bot.

For now, think of await as:

"Pause this task until this operation finishes, while letting the bot handle other things."

Run the Bot

Start it with:

python bot.py

If everything works, your terminal should print something similar to:

Logged in as StoryBot

Now go to your Discord server and type !hello. Your bot should respond.

Congratulations! You've officially made a Discord bot.

Now let's make it interesting.

Build the Storytelling System

First, we're going to create an interactive storytelling command.

At the top of bot.py, add:

import random

Then create some story ingredients:

story_locations = [
    "an abandoned library",
    "a mysterious island",
    "a futuristic city",
    "a hidden underground laboratory",
    "a forest that never appears on maps"
]

story_items = [
    "a glowing key",
    "an ancient notebook",
    "a strange compass",
    "a locked metal box",
    "a mysterious photograph"
]

story_events = [
    "You hear footsteps behind you.",
    "The lights suddenly turn off.",
    "A hidden door opens nearby.",
    "Your phone starts displaying a message from an unknown sender.",
    "You notice that the room has changed."
]

Now create the command:

@bot.command()
async def story(ctx):
    location = random.choice(story_locations)
    item = random.choice(story_items)
    event = random.choice(story_events)

    story_text = (
        f"You wake up in {location}.\n\n"
        f"Next to you is {item}.\n\n"
        f"{event}\n\n"
        "What do you do?"
    )

    await ctx.send(story_text)

Now !story might produce:

You wake up in a futuristic city.

Next to you is an ancient notebook.

A hidden door opens nearby.

What do you do?

Run it again and you might get something completely different.

That's because of:

random.choice(...)

Python randomly picks one item from each list.

It's a simple technique, but suddenly your bot can generate hundreds of different combinations.

Let's Make the Story Remember the User

Random stories are fun, but interactive stories are much better when the bot remembers what happened.

We can create a dictionary:

user_stories = {}

The dictionary will store story information for each user.

For example:

user ID → current story

Now let's modify the story command:

@bot.command()
async def story(ctx):
    user_id = ctx.author.id

    location = random.choice(story_locations)
    item = random.choice(story_items)
    event = random.choice(story_events)

    user_stories[user_id] = {
        "location": location,
        "item": item,
        "event": event
    }

    await ctx.send(
        f"You wake up in {location}.\n\n"
        f"Next to you is {item}.\n\n"
        f"{event}\n\n"
        "What do you do?"
    )

Now each user can have their own active story.

Add a Story Choice

Let's give users choices.

@bot.command()
async def choose(ctx, choice: str):
    user_id = ctx.author.id

    if user_id not in user_stories:
        await ctx.send("You don't have an active story. Try `!story` first.")
        return

    choice = choice.lower()

    if choice == "left":
        response = (
            "You head left and discover a room filled with old maps. "
            "One of them has your name written on it."
        )

    elif choice == "right":
        response = (
            "You head right and find a staircase leading toward "
            "a strange blue light."
        )

    else:
        response = "Try choosing `left` or `right`."

    await ctx.send(response)

Now users can type:

!choose left

or:

!choose right

Notice this:

async def choose(ctx, choice: str):

The choice parameter receives the text after the command.

So:

!choose left

becomes approximately:

choice = "left"

This is one of the reasons command frameworks are so convenient. A command framework is a set of tools that makes it easier to create and manage commands in a program. In our case, discord.py provides the command framework that lets us turn Python functions into Discord commands using decorators like @bot.command().

Instead of manually checking every message to figure out whether someone typed !choose, discord.py handles that work for us. It recognizes the command, takes the user's arguments, and passes them to our function.

So when someone types:

!choose left

discord.py knows that choose is the command, "left" is the argument, and that it should call our choose() function with that information.

Add a Casual Chat Command

Now let's make the bot capable of basic conversation.

We could connect it to a large language model API, but you don't actually need AI to learn how a chat command works. We'll start with a simple keyword-based response system.

First, we'll create a dictionary containing some keywords and possible responses:

chat_responses = {
    "hello": [
        "Hey! What's up?",
        "Hello! How's your day going?",
        "Hi! What are you working on?"
    ],
    "python": [
        "Python is a great language for beginners because its syntax is pretty readable.",
        "If you're learning Python, try building something instead of only watching tutorials."
    ],
    "discord": [
        "Discord bots are a fun way to practice Python because you get instant feedback.",
        "Once you understand commands and events, you can build some surprisingly complex bots."
    ]
}

Think of `chat_responses` as a small collection of things our bot knows how to talk about. Each key, such as `"python"` or `"discord"`, represents a keyword the bot can look for. The value associated with each key is a list of possible responses.

We use a list instead of a single response so the bot doesn't give exactly the same answer every time. Later, we'll randomly choose one of these responses.

Now let's create the actual `!chat` command:

```python
@bot.command()
async def chat(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in chat_responses.items():
        if keyword in text:
            await ctx.send(random.choice(responses))
            return

    await ctx.send(
        "I'm still learning how to respond to that. "
        "Try talking to me about Python or Discord!"
    )

There are a few things happening here, so let's break it down.

First, this part:

@bot.command()
async def chat(ctx, *, message: str):

turns the chat() function into a Discord command. The * is important because it tells discord.py to treat everything after the command as one argument.

For example, if someone types:

!chat I want to learn Python

the entire phrase after !chat becomes the value of message:

message = "I want to learn Python"

Next, we have:

text = message.lower()

This converts the message to lowercase. That means Python, python, and PYTHON will all become python. Without this, our keyword check could miss a match simply because the user capitalized a word differently.

Now we get to the loop:

for keyword, responses in chat_responses.items():

.items() lets us go through both the keyword and its corresponding list of responses. During each loop, keyword contains something like "python", while responses contains the list of responses associated with it.

Then we check:

if keyword in text:

This asks whether the current keyword appears anywhere in the user's message.

If the user writes:

!chat I want to learn Python

the lowercase version becomes:

i want to learn python

Since "python" appears inside that text, the condition is true.

The bot can then choose a random response:

await ctx.send(random.choice(responses))

random.choice() picks one item from the response list, while ctx.send() sends that response back to the Discord channel.

Finally, we have:

return

This stops the function after a matching keyword is found. Without it, the loop would continue checking the other keywords even after the bot had already responded.

But what happens if none of the keywords match?

That's what this part handles:

await ctx.send(
    "I'm still learning how to respond to that. "
    "Try talking to me about Python or Discord!"
)

If the loop finishes without finding a keyword, the bot sends this fallback message instead.

For example:

!chat I like pizza

doesn't contain "hello", "python", or "discord", so the bot doesn't have a specific response to use.

This gives us a simple way for the bot to have conversations without needing an AI model.

Add a Mental-Wellness Support Feature

Now for the feature that needs a little more care.

Instead of calling this a "therapy command" internally, we'll call it:

!support

Quick additional disclaimer before we start...this is just a fun wellness script, not a real therapist!

Create:

support_responses = {
    "stress": [
        "That sounds like a lot to handle. Try breaking the situation into one small task at a time.",
        "When everything feels overwhelming, it can help to pause and focus on what needs attention right now."
    ],

    "school": [
        "School can pile up quickly. Consider choosing one assignment to work on first instead of trying to solve everything at once.",
        "If school stress is getting difficult to manage, talking with a trusted person can make things feel less like something you have to handle alone."
    ],

    "sad": [
        "I'm sorry you're having a difficult moment. Taking a short break, doing something calming, or talking with someone you trust may help.",
        "You don't have to solve everything immediately. Give yourself some time and consider reaching out to someone you trust."
    ]
}

Now create the command:

@bot.command()
async def support(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in support_responses.items():
        if keyword in text:
            response = random.choice(responses)

            await ctx.send(
                f"{response}\n\n"
                "I'm a bot, not a therapist or medical professional. "
                "If you need personal support, consider talking with "
                "someone you trust."
            )
            return

    await ctx.send(
        "It sounds like something is bothering you. "
        "I can offer general wellness suggestions, but I'm not a therapist. "
        "If you need personal support, consider reaching out to someone you trust."
    )

Now someone can type:

!support I'm stressed about school

The bot sees the word:

school

and chooses one of the school-related responses.

This is deliberately simple.

For a real public bot, you'd want much more careful safety handling, testing, moderation, privacy protection, and escalation logic before allowing users to rely on it for sensitive situations.

Add a Help Command

A good bot should explain itself.

@bot.command()
async def commands_help(ctx):
    await ctx.send(
        "**Available commands:**\n"
        "`!hello` - Say hello\n"
        "`!story` - Start a new story\n"
        "`!choose left` - Choose the left path\n"
        "`!choose right` - Choose the right path\n"
        "`!chat <message>` - Have a casual conversation\n"
        "`!support <message>` - Get general wellness support"
    )

There's one small issue.

Discord's default help command is already called help.

So instead of:

async def help(ctx):

we've named ours:

commands_help

If you want the command itself to be called !help, you can write:

@bot.command(name="help")
async def commands_help(ctx):
    ...

That tells Discord:

Use !help for this function even though the Python function has another name.

Improve Error Handling

Bots shouldn't crash just because someone enters an invalid command.

Add:

@bot.event
async def on_command_error(ctx, error):
    if isinstance(error, commands.MissingRequiredArgument):
        await ctx.send(
            "You're missing something. Try `!help` to see how the command works."
        )

    elif isinstance(error, commands.CommandNotFound):
        return

    else:
        print(f"Error: {error}")

Now if someone types:

!chat

without giving the bot a message, it can respond with a useful explanation instead of dumping a confusing error into the conversation.

Put Everything Together

At this point, your bot.py can look like this:

import os
import random

import discord
from discord.ext import commands
from dotenv import load_dotenv


load_dotenv()

TOKEN = os.getenv("DISCORD_TOKEN")

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")


intents = discord.Intents.default()
intents.message_content = True

bot = commands.Bot(
    command_prefix="!",
    intents=intents
)


story_locations = [
    "an abandoned library",
    "a mysterious island",
    "a futuristic city",
    "a hidden underground laboratory",
    "a forest that never appears on maps"
]

story_items = [
    "a glowing key",
    "an ancient notebook",
    "a strange compass",
    "a locked metal box",
    "a mysterious photograph"
]

story_events = [
    "You hear footsteps behind you.",
    "The lights suddenly turn off.",
    "A hidden door opens nearby.",
    "Your phone starts displaying a message from an unknown sender.",
    "You notice that the room has changed."
]


user_stories = {}


chat_responses = {
    "hello": [
        "Hey! What's up?",
        "Hello! How's your day going?",
        "Hi! What are you working on?"
    ],

    "python": [
        "Python is a great language for beginners because its syntax is pretty readable.",
        "If you're learning Python, try building something instead of only watching tutorials."
    ],

    "discord": [
        "Discord bots are a fun way to practice Python because you get instant feedback.",
        "Once you understand commands and events, you can build some surprisingly complex bots."
    ]
}


support_responses = {
    "stress": [
        "That sounds like a lot to handle. Try breaking the situation into one small task at a time.",
        "When everything feels overwhelming, it can help to pause and focus on what needs attention right now."
    ],

    "school": [
        "School can pile up quickly. Consider choosing one assignment to work on first instead of trying to solve everything at once.",
        "If school stress is getting difficult to manage, talking with a trusted person can make things feel less like something you have to handle alone."
    ],

    "sad": [
        "I'm sorry you're having a difficult moment. Taking a short break, doing something calming, or talking with someone you trust may help.",
        "You don't have to solve everything immediately. Give yourself some time and consider reaching out to someone you trust."
    ]
}


@bot.event
async def on_ready():
    print(f"Logged in as {bot.user}")


@bot.command()
async def hello(ctx):
    await ctx.send("Hello! I'm online.")


@bot.command()
async def story(ctx):
    user_id = ctx.author.id

    location = random.choice(story_locations)
    item = random.choice(story_items)
    event = random.choice(story_events)

    user_stories[user_id] = {
        "location": location,
        "item": item,
        "event": event
    }

    await ctx.send(
        f"You wake up in {location}.\n\n"
        f"Next to you is {item}.\n\n"
        f"{event}\n\n"
        "What do you do?"
    )


@bot.command()
async def choose(ctx, choice: str):
    user_id = ctx.author.id

    if user_id not in user_stories:
        await ctx.send(
            "You don't have an active story. Try `!story` first."
        )
        return

    choice = choice.lower()

    if choice == "left":
        response = (
            "You head left and discover a room filled with old maps. "
            "One of them has your name written on it."
        )

    elif choice == "right":
        response = (
            "You head right and find a staircase leading toward "
            "a strange blue light."
        )

    else:
        response = "Try choosing `left` or `right`."

    await ctx.send(response)


@bot.command()
async def chat(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in chat_responses.items():
        if keyword in text:
            await ctx.send(random.choice(responses))
            return

    await ctx.send(
        "I'm still learning how to respond to that. "
        "Try talking to me about Python or Discord!"
    )


@bot.command()
async def support(ctx, *, message: str):
    text = message.lower()

    for keyword, responses in support_responses.items():
        if keyword in text:
            response = random.choice(responses)

            await ctx.send(
                f"{response}\n\n"
                "I'm a bot, not a therapist or medical professional. "
                "If you need personal support, consider talking with "
                "someone you trust."
            )
            return

    await ctx.send(
        "It sounds like something is bothering you. "
        "I can offer general wellness suggestions, but I'm not a therapist. "
        "If you need personal support, consider reaching out to someone you trust."
    )


@bot.command(name="help")
async def commands_help(ctx):
    await ctx.send(
        "**Available commands:**\n"
        "`!hello` - Say hello\n"
        "`!story` - Start a new story\n"
        "`!choose left` - Choose the left path\n"
        "`!choose right` - Choose the right path\n"
        "`!chat <message>` - Have a casual conversation\n"
        "`!support <message>` - Get general wellness support"
    )


@bot.event
async def on_command_error(ctx, error):
    if isinstance(error, commands.MissingRequiredArgument):
        await ctx.send(
            "You're missing something. Try `!help` to see how the command works."
        )

    elif isinstance(error, commands.CommandNotFound):
        return

    else:
        print(f"Error: {error}")


bot.run(TOKEN)

This is enough to create a surprisingly capable beginner Discord project.

But there's an important limitation.

Our Bot Doesn't Actually Remember Anything

There's one small problem with our bot so far: it doesn't actually remember anything after it shuts down.

Right now, we're storing our story information in a Python dictionary:

user_stories = {}

This works while the bot is running. But if you stop the program and start it again, the dictionary starts empty.

To fix this, we need somewhere to permanently store our data. That's where a database comes in.

For this project, we'll use SQLite. SQLite is a lightweight database that stores information in a file on your computer. Python already includes SQLite through the built-in sqlite3 module, so we don't need to install anything extra.

Create the Database

First, add this import near the top of bot.py:

import sqlite3

Then create a connection to a database file:

db = sqlite3.connect("bot.db")
cursor = db.cursor()

The first line creates a database file called bot.db if one doesn't already exist. If the file already exists, SQLite simply opens it.

The second line creates a cursor. You can think of the cursor as the part of our Python program that lets us send instructions to the database.

Now we need to create a table where we can store our users' story information:

cursor.execute("""
    CREATE TABLE IF NOT EXISTS user_stories (
        user_id INTEGER PRIMARY KEY,
        location TEXT,
        item TEXT,
        event TEXT
    )
""")

db.commit()

Let's break this down.

cursor.execute() tells SQLite to run the SQL command inside the parentheses.

The SQL command starts with:

CREATE TABLE IF NOT EXISTS user_stories

This tells SQLite to create a table called user_stories, but only if that table doesn't already exist.

Inside the parentheses, we define the information that each row can contain:

user_id INTEGER PRIMARY KEY,
location TEXT,
item TEXT,
event TEXT

user_id stores the Discord user's ID. We use it as the PRIMARY KEY, which means each user gets their own unique row.

location, item, and event are all pieces of information about the user's current story.

Finally:

db.commit()

saves the changes to the database.

At this point, your project folder should contain a new file called:

bot.db

You don't need to open or edit this file manually. SQLite will manage it for us.

Save a User's Story

Now let's actually put information into our database.

Suppose we have these variables:

user_id = ctx.author.id
location = "an abandoned castle"
item = "a mysterious key"
event = "a locked door"

We can save them using:

cursor.execute(
    """
    INSERT OR REPLACE INTO user_stories
    (user_id, location, item, event)
    VALUES (?, ?, ?, ?)
    """,
    (user_id, location, item, event)
)

db.commit()

The SQL statement tells SQLite to insert the information into the user_stories table.

The ? symbols are placeholders for the actual values. The values are provided separately here:

(user_id, location, item, event)

This is safer than manually inserting values directly into the SQL string.

INSERT OR REPLACE also means that if this user already has a saved story, their old story information can be replaced with the new information.

Get the Story Back

Saving information is only half of the job. We also need to be able to retrieve it.

We can search the database for a user's story like this:

cursor.execute(
    """
    SELECT location, item, event
    FROM user_stories
    WHERE user_id = ?
    """,
    (user_id,)
)

story = cursor.fetchone()

This time, we're using SELECT to ask SQLite for information.

The WHERE part is important:

WHERE user_id = ?

It tells SQLite to find the row belonging to this specific Discord user.

Then:

story = cursor.fetchone()

gets the first matching result.

If the user has a saved story, story will contain their information. If they don't, story will be None.

We can check for that:

if story:
    location, item, event = story

    await ctx.send(
        f"You're currently in {location}. "
        f"You have {item}, and you're facing {event}."
    )
else:
    await ctx.send("I don't have a saved story for you yet!")

Now the bot can retrieve information that was saved earlier, even after the Python program has been restarted.

Put It Into a Command

We can turn this into a simple command that lets users check their saved story:

@bot.command()
async def status(ctx):
    user_id = ctx.author.id

    cursor.execute(
        """
        SELECT location, item, event
        FROM user_stories
        WHERE user_id = ?
        """,
        (user_id,)
    )

    story = cursor.fetchone()

    if story:
        location, item, event = story

        await ctx.send(
            f"You're currently in {location}. "
            f"You have {item}, and you're facing {event}."
        )
    else:
        await ctx.send(
            "You don't have a saved story yet. "
            "Start one with `!story`!"
        )

Now a user can type:

!status

and the bot can look up their story from the database.

This is a big improvement over our original dictionary. A dictionary only remembers information while the Python program is running. SQLite lets us save that information so it can still be there when the bot starts again.

For a larger bot, you could eventually store things like user preferences, story progress, inventory, conversation history, or other data. But for now, this simple database is enough to give our bot some real memory.

Adding Real AI Chat

Before we connect our bot to an AI model, let's quickly talk about Hugging Face.

If you've never used it before, Hugging Face is a platform where developers can find, share, and use machine learning models and datasets. Think of it as a huge community and library for AI tools.

Hugging Face also provides tools that let Python programs communicate with these models without having to build and train an AI model from scratch.

For our bot, we'll use Hugging Face's Inference Providers to send a user's message to a supported language model and receive its response.

We won't be training an AI model ourselves. Instead, we'll use an existing model and connect it to our Discord bot through Python.

Now that we know what Hugging Face is, let's connect it to our bot.

Install the Hugging Face Library

First, install huggingface_hub:

pip install -U huggingface_hub

We already installed python-dotenv, so we can use the same .env file from earlier to keep our Hugging Face token out of the source code.

Add your Hugging Face token to .env:

DISCORD_TOKEN=YOUR_BOT_TOKEN_HERE
HF_TOKEN=YOUR_HUGGING_FACE_TOKEN_HERE

Replace YOUR_HUGGING_FACE_TOKEN_HERE with your actual Hugging Face access token.

Just like your Discord bot token, don't share this token or upload it to GitHub.

Create the Hugging Face Client

Now add this import near the top of bot.py:

from huggingface_hub import InferenceClient

Then load the token:

HF_TOKEN = os.getenv("HF_TOKEN")

if not HF_TOKEN:
    raise RuntimeError("HF_TOKEN is not set.")

The first line gets the token from our environment variables. The if statement checks whether the token actually exists. If it doesn't, Python stops and gives us a useful error instead of letting the program fail later in a confusing way.

Now create the Hugging Face client:

client = InferenceClient(
    api_key=HF_TOKEN
)

The InferenceClient is what our Python program will use to communicate with Hugging Face's inference service.

Connect the AI Model to the Bot

Now we can replace our previous keyword-based !chat command with one that sends the user's message to a language model.

@bot.command()
async def chat(ctx, *, message: str):
    try:
        response = client.chat_completion(
            model="YOUR_SUPPORTED_MODEL_ID",
            messages=[
                {
                    "role": "system",
                    "content": (
                        "You are a friendly Discord bot. "
                        "Keep responses helpful, concise, and conversational."
                    )
                },
                {
                    "role": "user",
                    "content": message
                }
            ],
            max_tokens=200
        )

        answer = response.choices[0].message.content

        await ctx.send(answer)

    except Exception as error:
        print(f"AI error: {error}")
        await ctx.send(
            "I couldn't generate a response right now. "
            "Please try again later."
        )

There's quite a bit happening here, so let's walk through it.

We start with the same command structure we've already used:

@bot.command()
async def chat(ctx, *, message: str):

This creates our !chat command and stores everything the user types after it in message.

For example:

!chat What is Python?

gives us:

message = "What is Python?"

Next, we use:

try:

This tells Python that we're about to run code that could potentially fail. Since we're communicating with an external service, things like an unavailable model, an invalid token, or a temporary connection problem can happen.

Now we call:

response = client.chat_completion(

This sends a chat-completion request to the model through Hugging Face. The messages parameter contains the conversation we want the model to respond to.

The first message has the role "system":

{
    "role": "system",
    "content": (
        "You are a friendly Discord bot. "
        "Keep responses helpful, concise, and conversational."
    )
}

The system message gives the model instructions about how it should respond.

Then we provide the user's actual message:

{
    "role": "user",
    "content": message
}

If the user typed:

!chat What is Python?

then message contains:

What is Python?

So the model receives that as the user's input.

We also have:

max_tokens=200

This limits how much text the model can generate for one response. Keeping responses relatively short works well for Discord because huge blocks of text aren't always very pleasant to read in a chat channel.

You also need to replace:

model="YOUR_SUPPORTED_MODEL_ID"

with the ID of a model currently available through the Hugging Face Inference Providers you are using. Hugging Face's documentation shows that InferenceClient can use a model ID hosted on the Hugging Face Hub for chat completion.

Once the request is complete, we need to get the actual text from the response:

answer = response.choices[0].message.content

The response contains information about the model's output. choices[0] gets the first generated response, and .message.content gives us the actual text.

Then we send it to Discord:

await ctx.send(answer)

So the whole process looks like this:

User types !chat
        ↓
Discord sends the command to our bot
        ↓
Python gets the user's message
        ↓
Hugging Face receives the message
        ↓
The AI model generates a response
        ↓
Python gets the generated text
        ↓
The bot sends it back to Discord

Handle AI Errors

The last part of our command is:

except Exception as error:
    print(f"AI error: {error}")
    await ctx.send(
        "I couldn't generate a response right now. "
        "Please try again later."
    )

If something goes wrong inside the try block, Python jumps to the except block instead of crashing the entire bot.

The error is printed in the terminal so you can investigate what happened:

print(f"AI error: {error}")

Meanwhile, the Discord user gets a simple message:

I couldn't generate a response right now. Please try again later.

This is much better than letting an API error take down the whole bot.

At this point, you have a real AI-powered !chat command. You can type something like:

!chat Tell me an interesting fact about space.

and the model can generate a response instead of choosing from a small list of pre-written messages.

One thing to remember is that this bot is sending user messages to an external AI service. Don't automatically send private or sensitive conversations to an AI provider. If you make this bot available to other people, be clear about what information it processes and avoid storing or sending more data than the bot actually needs.

You can also combine this AI system with the SQLite database from earlier. For example, you could save a limited amount of conversation history and send relevant previous messages along with a new message. That would allow the bot to keep some context between messages instead of treating every message as a completely new conversation.

How Do We Keep the Bot Online?

Here's where the phrase "online forever" needs a little clarification.

There are two different situations.

Option 1: Run It on Your Computer

When you run:

python bot.py

the bot stays online while that program is running.

Close the terminal?

Bot goes offline.

Turn off the computer?

Bot goes offline.

Lose internet?

Bot goes offline.

This is perfect for development but it's not a 24/7 production setup.

Option 2: Host It on a Server

For a bot that should stay online while your computer is off, you need a computer somewhere that stays available.

That computer can be a cloud server.

You upload your project, install the dependencies, add your environment variables, and start:

python bot.py

Now the cloud machine runs the program instead of your laptop.

Services designed for continuously running workloads can be used for this kind of application. For example, Render currently provides a Background Worker service type for continuously running processes that don't need to receive incoming web traffic.

But you should check the provider's current pricing and service limitations before deploying. Free hosting tiers aren't necessarily designed for an always-on Discord bot, and a "free forever" 24/7 setup isn't something you should assume a hosting platform will provide.

What "Forever" Actually Means

There isn't really a magical:

ONLINE_FOREVER = True

setting.

A bot can stay online continuously only as long as the computer or server running it continues operating.

Even a professionally hosted bot can go offline because of:

• Server maintenance

• Deployments

• Bugs

• Network problems

• Provider outages

• Invalid credentials

• API changes

• Billing or account issues

So the realistic goal is to keep the bot running automatically and restart it when something goes wrong.

That is what production hosting is designed to help with.

If your provider supports automatic restarts, enable them.

You can also make your Python code fail clearly when an important environment variable is missing:

if not TOKEN:
    raise RuntimeError("DISCORD_TOKEN is not set.")

A clear error is much easier to debug than a mysterious bot that simply doesn't appear online.

Don't Try to "Keep It Awake" With Random Tricks

You may find tutorials suggesting that you deploy a web server and repeatedly ping it from another service to prevent a free hosting instance from sleeping.

Be careful with that approach.

Hosting providers change their free-tier rules, and attempting to work around those limits can violate their terms.

If you need an actually persistent bot, use a hosting option that explicitly supports the workload.

For example, a background worker is designed for continuously running processes. That's much cleaner than trying to convince a web service that your Discord bot is secretly a website.

Additional Features and Where to Go Next

Now that you have a working Discord bot, there are plenty of directions you can take the project next.

You could turn the storytelling system into a more complete game by adding an inventory, multiple chapters, puzzles, or different endings. You could also replace text-based commands with Discord slash commands and buttons to make the bot easier to interact with.

If you're interested in AI, you could expand the chat system by giving the bot different personalities, adding carefully limited conversation context, or using AI to generate parts of the stories.

You could also add moderation features, daily story prompts, or other commands that fit the kind of Discord community you're building.

These are ideas for extending the project rather than features we'll build step by step in this tutorial. The important thing is that you now have the foundation to experiment with them yourself.

Start with one small feature, figure out how it works, and build from there. You don't need to turn the bot into a massive project all at once.

The more you experiment with the code, the more you'll start seeing how Python, Discord, databases, and AI can work together in a real application.

Test Everything Locally First

Before deploying, test:

!hello
!story
!choose left
!choose right
!chat hello
!chat I want to learn Python
!support I'm stressed
!help

Then test weird inputs:

!choose banana
!chat
!support
!unknowncommand

You want to discover bugs while you're sitting in front of your computer, not three days later when someone tells you:

"Your bot has been broken since Tuesday."

Deploying the Bot

First, make sure your project contains:

discord-story-bot/
│
├── bot.py
├── requirements.txt
├── .gitignore
└── .python-version

A .python-version file can contain something like:

3.13

Using a version file makes your deployment environment more predictable. Render currently supports specifying a Python version through .python-version or an environment variable.

Your requirements.txt should contain your dependencies.

For example:

discord.py
python-dotenv

For deployment, you generally don't need the local .env file.

Instead, add:

DISCORD_TOKEN

as an environment variable in your hosting provider's dashboard.

That way the secret isn't stored inside your repository.

The Start Command

Your deployment service needs to know what to run.

For this project, the start command is:

python bot.py

The important thing is that the process doesn't immediately exit.

A Discord bot stays alive because bot.run(TOKEN) starts the Discord connection and keeps the program running.

If your hosting service supports background workers, that's a natural fit for a bot like this because the bot doesn't need to serve normal HTTP requests. Render specifically describes background workers as continuously running services that don't receive incoming network traffic.

Remember: Keep Your Secrets Secret

This is worth repeating because it causes a lot of beginner projects to get compromised.

Never commit this:

bot.run("YOUR_REAL_TOKEN")

Never upload:

.env

Never paste your actual token into a public GitHub issue.

If a token accidentally becomes public, treat it as compromised and regenerate it.

Environment variables are your friend.

What You Learned

You've now built a Discord bot that demonstrates several real programming concepts.

You learned how to:

• Create a Discord application

• Connect Python to Discord

• Use discord.py

• Configure Gateway Intents

• Create commands

• Use asynchronous functions

• Read command arguments

• Generate random stories

• Store temporary user state

• Create a basic chat system

• Create a mental-wellness support feature

• Handle command errors

• Keep secrets out of source code

• Prepare a project for deployment

• Think about persistent hosting

And underneath all those features, the architecture is still surprisingly simple:

User sends command
        ↓
Discord receives message
        ↓
discord.py receives event
        ↓
Python function runs
        ↓
Bot generates response
        ↓
Discord displays response

You don't need thousands of lines of code to get started.

You need a clear idea, a few Python concepts, and the willingness to keep debugging when something inevitably breaks.

Final Thoughts

The coolest part of this project isn't really the Discord bot. It's what the project teaches you.

And once you understand the pieces, you can reuse the same ideas in countless projects.

A Discord bot can become a game, which could become a web application, which could also become a larger software project.

And suddenly you're not just learning Python syntax anymore. You're learning how software actually gets built, one command at a time.

Happy coding!

You’ll use LangGraph nodes to build a branching flow that processes incoming messages and detects intent like chat, support, or tool usage. It’ll then route them to the right logic based on what the user says.

I know it may sound a bit weird to use LangGraph for a Discord bot, but you’ll soon see that this project is a pretty fun way to visualize how node-based AI workflows actually run.

For now, the workflow is simple: you’ll figure out if the user is just chatting, asking a support question, or requesting that the bot perform an action, and respond based on that.

What you will learn: 👀

• How to use LangGraph to create an AI-driven workflow that powers your bot’s logic.

• How you can integrate Composio to let your bot take real-world actions using external tools.

• How you can use Discord.js and handle different message types like replies, threads, and embeds.

• How you can maintain per-channel context using message history and pass it into AI.

By the end of this article, you’ll have a quite decent and functional Discord bot that you can add to your server. It replies to users based on message context and even has tool-calling support! (And there’s a small challenge for you to implement something yourself.) 😉

Prerequisites

Make sure you have Discord installed on your machine so you can test the bot easily.

This project is designed to demonstrate how you can build a bot powered by LangGraph and Composio. Before proceeding, it is helpful to have a basic understanding of:

• How to work with Node.js

• Rough idea of what LangGraph is and how it works

• How to work with Discord.js

• What AI Agents are

If you’re not confident about any of these, try following along anyway. You might pick things up just fine. And if it ever gets confusing, you can always check out the full source code here.

Table of Contents

• How to Set Up the Environment

  • Initialize the Project

  • Install Dependencies

  • Configure Composio

  • Configure Discord Integration

  • Add Environment Variables

• Build the Application Logic

  • Define Types and Utility Helpers

  • Implement LangGraph Workflow

  • Set Up Discord.js Client

• Wrapping Up

How to Set Up the Environment

In this section, we will get everything set up for building the project.

Initialize the Project

Initialize a Node.js application with the following command:

💁 Here I'm using Bun, but you can choose any package manager of your choice.

mkdir discord-bot-langgraph && cd discord-bot-langgraph \
&& bun init -y

Now, that our Node.js application is ready, let's install some dependencies.

Install Dependencies

We'll be using the following main packages and some other helper packages:

• discord.js: Interacts with the Discord API

• composio: Adds tools integration support to the bot

• openai: Enables AI-powered responses

• langchain: Manages LLM workflows

• zod: Validates and parses data safely

bun add discord.js openai @langchain/core @langchain/langgraph \
langchain composio-core dotenv zod uuid

Configure Composio

💁 You’ll use Composio to add integrations to your application. You can choose the integration of your choice, but here I'm using Google sheets.

First, before moving forward, you need to get access to a Composio API key.

Go ahead and create an account on Composio, get your API key, and paste it in the .env file in the root of the project:

COMPOSIO_API_KEY=<your_composio_api_key>

Authenticate yourself with the following command:

composio login

Once that’s done, run the composio whoami command, and if you see something like the below, you’re successfully logged in.

You're almost there: now you just need to set up integrations. Here, I’ll use Google sheets, but again you can set up any integration you like.

Run the following command to set up the Google Sheets integration:

composio add googlesheets

You should see an output similar to this:

Head over to the URL that’s shown, and you should be authenticated like so:

That's it. You’ve successfully added the Google Sheets integration and can access all its tools in your application.

Once finished, run the composio integrations command to verify if it worked. You should see a list of all your integrations:

Configure Discord Integration

This is a bit off topic for this tutorial, but basically, you’ll create an application/bot on Discord and add it to your server.

You can find a guide on how to create and add a bot to your server in the Discord.js documentation.

And yes, it’s free if you’re wondering whether any step here requires a pro account or anything. 😉

Make sure you populate these three environment variables:

DISCORD_BOT_TOKEN=<YOUR_DISCORD_BOT_TOKEN>
DISCORD_BOT_GUILD_ID=<YOUR_DISCORD_BOT_GUILD_ID>
DISCORD_BOT_CHANNEL_ID=<YOUR_DISCORD_BOT_CHANNEL_ID>

Add Environment Variables

You’ll require a few other environment variables, including the OpenAI API key, for the bot to work.

Your final .env file should look something like this:

OPENAI_API_KEY=<YOUR_OPENAI_API_KEY>

COMPOSIO_API_KEY=<YOUR_COMPOSIO_API_KEY>

DISCORD_BOT_TOKEN=<YOUR_DISCORD_BOT_TOKEN>
DISCORD_BOT_GUILD_ID=<YOUR_DISCORD_BOT_GUILD_ID>
DISCORD_BOT_CHANNEL_ID=<YOUR_DISCORD_BOT_CHANNEL_ID>

Build the Application Logic

Now that you’ve laid all the groundwork, you can finally start coding the project.

Define Types and Utility Helpers

Let’s start by writing some helper functions and defining the types of data you’ll be working with.

It's important in any application, especially ones like the one we're building – which is prone to errors due to multiple API calls – that we set up decent logging so we know when and how things go wrong.

Create a new file named logger.ts inside the utils directory and add the following lines of code:

// 👇 discord-bot-langgraph/utils/logger.ts

export const DEBUG = "DEBUG";
export const INFO = "INFO";
export const WARN = "WARN";
export const ERROR = "ERROR";

export type LogLevel = typeof DEBUG | typeof INFO | typeof WARN | typeof ERROR;

// eslint-disable-next-line  @typescript-eslint/no-explicit-any
export function log(level: LogLevel, message: string, ...data: any[]) {
  const timestamp = new Date().toLocaleString();
  const prefix = `[${timestamp}] [${level}]`;

  switch (level) {
    case ERROR:
      console.error(prefix, message, ...data);
      break;
    case WARN:
      console.warn(prefix, message, ...data);
      break;
    default:
      console.log(prefix, message, ...data);
  }
}

This is already looking great. Why not write a small environment variables validator? Run this during the initial program startup, and if something goes wrong, the application will exit with clear logs so users know if any environment variables are missing.

Create a new file named env-validator.ts in the utils directory and add the following lines of code:

// 👇 discord-bot-langgraph/utils/env-validator.ts

import { log, ERROR } from "./logger.js";

export const OPENAI_API_KEY = "OPENAI_API_KEY";

export const DISCORD_BOT_TOKEN = "DISCORD_BOT_TOKEN";
export const DISCORD_BOT_GUILD_ID = "DISCORD_BOT_GUILD_ID";
export const DISCORD_BOT_CLIENT_ID = "DISCORD_BOT_CLIENT_ID";

export const COMPOSIO_API_KEY = "COMPOSIO_API_KEY";

export const validateEnvVars = (requiredEnvVars: string[]): void => {
  const missingVars: string[] = [];

  for (const envVar of requiredEnvVars) {
    if (!process.env[envVar]) {
      missingVars.push(envVar);
    }
  }

  if (missingVars.length > 0) {
    log(
      ERROR,
      "missing required environment variables. please create a .env file and add the following:",
    );
    missingVars.forEach((envVar) => console.error(`- ${envVar}`));
    process.exit(1);
  }
};

Now, let's also define the type of data you'll be working with:

Create a new file named types.ts inside the types directory and add the following lines of code:

// 👇 discord-bot-langgraph/types/types.ts

export const QUESTION = "QUESTION";
export const HELP = "HELP";
export const SUPPORT = "SUPPORT";
export const OTHER = "OTHER";
export const TOOL_CALL_REQUEST = "TOOL_CALL_REQUEST";

export type FinalAction =
  | { type: "REPLY"; content: string }
  | { type: "REPLY_IN_THREAD"; content: string }
  | {
      type: "CREATE_EMBED";
      title: string;
      description: string;
      roleToPing?: string;
    };

export type MessageChoice =
  | typeof SUPPORT
  | typeof OTHER
  | typeof TOOL_CALL_REQUEST;

export type SupportTicketType = typeof QUESTION | typeof HELP;

export type Message = {
  author: string;
  content: string;
};

export type SupportTicketQuestion = {
  description: string;
  answer: string;
};

export type SupportTicket = {
  type?: SupportTicketType;
  question?: SupportTicketQuestion;
};

export type ToolCallRequestAction = {
  // actionLog is not intended to be shown to the end-user.
  // This is solely for logging purpose.
  actionLog: string;
  status: "success" | "failed" | "acknowledged";
};

The types are pretty self-explanatory, but here’s a quick overview.

Message holds the user's input and author. Each message can be marked as support, a tool call request, or just other, like spam or small talk.

Support messages are further labeled as either help or a question using SupportTicketType.

The graph returns a FinalAction, which can be a direct reply, a reply in a thread, or an embed. If it's CREATE_EMBED and has roleToPing set, it denotes support help, so we can ping the mod.

For tool-based responses, ToolCallRequestAction stores the status and an internal log used for debugging.

Now, you need one last helper function to use in your nodes to extract the response from the LLM. Create a new file named helpers.ts and add the following code:

// 👇 discord-bot-langgraph/utils/helpers.ts

import type { AIMessage } from "@langchain/core/messages";

export function extractStringFromAIMessage(
  message: AIMessage,
  fallback: string = "No valid response generated by the LLM.",
): string {
  if (typeof message.content === "string") {
    return message.content;
  }

  if (Array.isArray(message.content)) {
    const textContent = message.content
      .map((item) => (typeof item === "string" ? item : ""))
      .join(" ");
    return textContent.trim() || fallback;
  }

  return fallback;
}

You're all set for now with these helper functions in place. Now, you can start coding the logic.

Implement LangGraph Workflow

Now that you have the types defined, structure your graph and connect it with some edges.

Create a new file named graph.ts inside the src directory and add the following lines of code:

// 👇 discord-bot-langgraph/src/graph.ts

import { Annotation, END, START, StateGraph } from "@langchain/langgraph";
import {
  type FinalAction,
  type ToolCallRequestAction,
  type Message,
  type MessageChoice,
  type SupportTicket,
} from "../types/types.js";
import {
  processToolCall,
  processMessage,
  processOther,
  processSupport,
  processSupportHelp,
  processSupportQuestion,
} from "./nodes.js";
import { processMessageEdges, processSupportEdges } from "./edges.js";

const state = Annotation.Root({
  message: Annotation<Message>(),
  previousMessages: Annotation<Message[]>(),
  messageChoice: Annotation<MessageChoice>(),
  supportTicket: Annotation<SupportTicket>(),
  toolCallRequest: Annotation<ToolCallRequestAction>(),
  finalAction: Annotation<FinalAction>(),
});

export type State = typeof state.State;
export type Update = typeof state.Update;

export function initializeGraph() {
  const workflow = new StateGraph(state);

  workflow
    .addNode("process-message", processMessage)
    .addNode("process-support", processSupport)
    .addNode("process-other", processOther)

    .addNode("process-support-question", processSupportQuestion)
    .addNode("process-support-help", processSupportHelp)
    .addNode("process-tool-call", processToolCall)

    // Edges setup starts here....
    .addEdge(START, "process-message")

    .addConditionalEdges("process-message", processMessageEdges)
    .addConditionalEdges("process-support", processSupportEdges)

    .addEdge("process-other", END)
    .addEdge("process-support-question", END)
    .addEdge("process-support-help", END)
    .addEdge("process-tool-call", END);

  const graph = workflow.compile();

  // To get the graph in png
  // getGraph() is deprecated though
  // Bun.write("graph/graph.png", await graph.getGraph().drawMermaidPng());

  return graph;
}

The initializeGraph function, as the name suggests, returns the graph you can use to execute the workflow.

The process-message node is the starting point of the graph. It takes in the user’s message, processes it, and routes it to the appropriate next node: process-support, process-tool-call, or process-other.

The process-support node further classifies the support message and decides whether it should go to process-support-help or process-support-question.

The process-tool-call node handles messages when the user tries to trigger some kind of tool or action.

The process-other node handles everything that doesn’t fall into the support or tool call categories. These are general or fallback responses.

To help you visualize how things will shape up, here’s how the graph looks with all the different nodes (yet to work on!):

To wire everything together, you need to define edges between nodes, including conditional edges that dynamically decide the next step based on the state.

Create a new file named edges.ts inside the src directory and add the following lines of code:

// 👇 discord-bot-langgraph/src/edges.ts

import { END } from "@langchain/langgraph";
import { type State } from "./graph.js";
import { QUESTION, OTHER, SUPPORT, TOOL_CALL_REQUEST } from "../types/types.js";
import { log, WARN } from "../utils/logger.js";

export const processMessageEdges = (
  state: State,
): "process-support" | "process-other" | "process-tool-call" | "__end__" => {
  if (!state.messageChoice) {
    log(WARN, "state.messageChoice is undefined. Returning...");
    return END;
  }

  switch (state.messageChoice) {
    case SUPPORT:
      return "process-support";
    case TOOL_CALL_REQUEST:
      return "process-tool-call";
    case OTHER:
      return "process-other";
    default:
      log(WARN, "unknown message choice. Returning...");
      return END;
  }
};

export const processSupportEdges = (
  state: State,
): "process-support-question" | "process-support-help" | "__end__" => {
  if (!state.supportTicket?.type) {
    log(WARN, "state.supportTicket.type is undefined. Returning...");
    return END;
  }

  return state.supportTicket.type === QUESTION
    ? "process-support-question"
    : "process-support-help";
};

These are the edges that connect different nodes in your application. They direct the flow in your graph.

Things are really shaping up – so let’s finish the core logic by implementing all the nodes for your application.

Create a new file named nodes.ts inside the src directory and add the following lines of code:

// 👇 discord-bot-langgraph/src/nodes.ts

import { type State, type Update } from "./graph.js";
import { ChatOpenAI } from "@langchain/openai";
import { z } from "zod";
import {
  HELP,
  TOOL_CALL_REQUEST,
  OTHER,
  QUESTION,
  SUPPORT,
} from "../types/types.js";
import { extractStringFromAIMessage } from "../utils/helpers.js";
import { OpenAIToolSet } from "composio-core";
import type { ChatCompletionMessageToolCall } from "openai/resources/chat/completions.mjs";
import { v4 as uuidv4 } from "uuid";
import { DEBUG, ERROR, INFO, log, WARN } from "../utils/logger.js";
import {
  SystemMessage,
  HumanMessage,
  ToolMessage,
  BaseMessage,
} from "@langchain/core/messages";

// feel free to use any model. Here I'm going with gpt-4o-mini
const model = "gpt-4o-mini";

const toolset = new OpenAIToolSet();
const llm = new ChatOpenAI({
  model,
  apiKey: process.env.OPENAI_API_KEY,
  temperature: 0,
});

export const processMessage = async (state: State): Promise<Update> => {
  log(DEBUG, "message in process message:", state.message);

  const llm = new ChatOpenAI({
    model,
    apiKey: process.env.OPENAI_API_KEY,
    temperature: 0,
  });

  const structuredLlm = llm.withStructuredOutput(
    z.object({
      type: z.enum([SUPPORT, OTHER, TOOL_CALL_REQUEST]).describe(`
Categorize the user's message:
- ${SUPPORT}: Technical support, help with problems, or questions about AI.
- ${TOOL_CALL_REQUEST}: User asks the bot to perform tool action (e.g., "send an email", "summarize chat", "summarize google sheets").
- ${OTHER}: General conversation, spam, or off-topic messages.
`),
    }),
  );

  const res = await structuredLlm.invoke([
    [
      "system",
      `You are an expert message analyzer AI. You need to categorize the message into
one of these categories:

- ${SUPPORT}: If the message asks for technical support, help with a problem, or questions about AIs and LLMs.
- ${TOOL_CALL_REQUEST}: If the message is a direct command or request for the bot to perform an action using external tools/services. Examples: "Summarize a document or Google Sheet", "Summarize the last hour of chat", "Send an email to devteam about this bug", "Create a Trello card for this feature request". Prioritize this if the user is asking the bot to *do* something beyond just answering.
- ${OTHER}: For general chit-chat, spam, off-topic messages, or anything not fitting ${SUPPORT} or ${TOOL_CALL_REQUEST}.
`,
    ],
    ["human", state.message.content],
  ]);

  return {
    messageChoice: res.type,
  };
};

export const processSupport = async (state: State): Promise<Update> => {
  log(DEBUG, "message in support:", state.message);

  const llm = new ChatOpenAI({
    model,
    apiKey: process.env.OPENAI_API_KEY,
    temperature: 0,
  });

  const structuredLlm = llm.withStructuredOutput(
    z.object({
      type: z.enum([QUESTION, HELP]).describe(`
Type of support needed:
- ${QUESTION}: User asks a specific question seeking information or an answer.
- ${HELP}: User needs broader assistance, guidance, or reports an issue requiring intervention/troubleshooting.
`),
    }),
  );

  const res = await structuredLlm.invoke([
    [
      "system",
      `
You are a support ticket analyzer. Given a support message, categorize it as ${QUESTION} or ${HELP}.
- ${QUESTION}: For specific questions.
- ${HELP}: For requests for assistance, troubleshooting, or problem reports.
`,
    ],
    ["human", state.message.content],
  ]);

  return {
    supportTicket: {
      ...state.supportTicket,
      type: res.type,
    },
  };
};

export const processSupportHelp = async (state: State): Promise<Update> => {
  log(DEBUG, "message in support help:", state.message);

  return {
    supportTicket: {
      ...state.supportTicket,
    },
    finalAction: {
      type: "CREATE_EMBED",
      title: "🚨 Help Needed!",
      description: `A new request for help has been raised by **@${state.message.author}**.\n\n**Query:**\n> ${state.message.content}`,
      roleToPing: process.env.DISCORD_SUPPORT_MOD_ID,
    },
  };
};

export const processSupportQuestion = async (state: State): Promise<Update> => {
  log(DEBUG, "message in support question category:", state.message);

  const llm = new ChatOpenAI({
    model,
    apiKey: process.env.OPENAI_API_KEY,
    temperature: 0,
  });

  const systemPrompt = `
You are a helpful AI assistant specializing in AI, and LLMs. Answer
the user's question concisely and accurately based on general knowledge in
these areas. If the question is outside this scope (e.g., personal advice,
non-technical topics), politely state you cannot answer. User's question:
`;

  const res = await llm.invoke([
    ["system", systemPrompt],
    ["human", state.message.content],
  ]);

  const llmResponse = extractStringFromAIMessage(res);
  return {
    supportTicket: {
      ...state.supportTicket,
      question: {
        description: state.message.content,
        answer: llmResponse,
      },
    },
    finalAction: {
      type: "REPLY",
      content: llmResponse,
    },
  };
};

export const processOther = async (state: State): Promise<Update> => {
  log(DEBUG, "message in other category:", state.message);

  const response =
    "This seems to be a general message. I'm here to help with technical support or perform specific actions if you ask. How can I assist you with those?";

  return {
    finalAction: {
      type: "REPLY_IN_THREAD",
      content: response,
    },
  };
};

There’s not much to explain for these nodes. Each node in the flow functions as a message classifier. It spins up a Chat LLM instance and uses structured output to ensure the model returns a specific label from a predefined set like QUESTION or HELP for support messages. The system prompt clearly defines what each label means, and your user message is passed in for classification.

You’re almost there. But there’s one piece missing. Can you spot it?

The process-tool-call node that’s supposed to handle the workflow when the user asks to use a tool. This is a big piece of the workflow.

It’s a bit longer, so I’ll explain it separately.

Modify the above nodes.ts file to add the missing node:

// 👇 discord-bot-langgraph/src/nodes.ts

// Rest of the code...
export const processToolCall = async (state: State): Promise<Update> => {
  log(DEBUG, "message in tool call request category:", state.message);

  const structuredOutputType = z.object({
    service: z
      .string()
      .describe("The target service (e.g., 'email', 'discord')."),
    task: z
      .string()
      .describe(
        "A concise description of the task (e.g., 'send email to X', 'summarize recent chat', 'create task Y').",
      ),
    details: z
      .string()
      .optional()
      .describe(
        "Any specific details or parameters extracted from the message relevant to the task.",
      ),
  });

  const structuredLlm = llm.withStructuredOutput(structuredOutputType);

  let parsedActionDetails: z.infer<typeof structuredOutputType> = {
    service: "unknown",
    task: "perform a requested action",
  };

  try {
    const res = await structuredLlm.invoke([
      [
        "system",
        `Parse the user's request to identify an action. Extract the target service, a description of the task, and any relevant details or parameters.
      Examples:
      - "Remind me to check emails at 5 PM": service: calendar/reminder, task: set reminder, details: check emails at 5 PM
      - "Send a summary of this conversation to #general channel": service: discord, task: send summary to channel, details: channel #general
      - "Create a bug report for 'login fails on mobile'": service: project_manager, task: create bug report, details: title 'login fails on mobile'`,
      ],
      ["human", state.message.content],
    ]);

    parsedActionDetails = res;
    log(INFO, "initial parsing action details:", parsedActionDetails);
  } catch (error) {
    log(ERROR, "initial parsing error:", error);
    return {
      toolCallRequest: {
        actionLog: `Failed to parse user request: ${state.message.content}`,
        status: "failed",
      },
      finalAction: {
        type: "REPLY_IN_THREAD",
        content:
          "I'm sorry, I had trouble understanding that action. Could you please rephrase it?",
      },
    };
  }

  try {
    log(INFO, "fetching composio tools");
    const tools = await toolset.getTools({
      apps: ["GOOGLESHEETS"],
    });

    log(INFO, `fetched ${tools.length} tools. Errors if > 128 for OpenAI:`);

    if (tools.length === 0) {
      log(WARN, "no tools fetched from Composio. skipping...");
      return {
        toolCallRequest: {
          actionLog: `Service: ${parsedActionDetails.service}, Task: ${parsedActionDetails.task}. No composio tools found`,
          status: "failed",
        },
        finalAction: {
          type: "REPLY_IN_THREAD",
          content: "Couldn't find any tools to perform your action.",
        },
      };
    }

    log(DEBUG, "starting iterative tool execution loop");

    const conversationHistory: BaseMessage[] = [
      new SystemMessage(
        "You are a helpful assistant that performs tool calls. Your task is to understand the user's request and use the available tools to fulfill the request completely. You can use multiple tools in sequence to accomplish complex tasks. Always provide a brief, conversational summary of what you accomplished after using tools.",
      ),
      new HumanMessage(state.message.content),
    ];

    let totalToolsUsed = 0;
    let finalResponse: string | null = null;

    const maxIterations = 5;
    let iteration = 0;

    while (iteration < maxIterations) {
      iteration++;
      log(
        DEBUG,
        `Iteration ${iteration}: calling LLM with ${tools.length} tools`,
      );

      const llmResponse = await llm.invoke(conversationHistory, {
        tools: tools,
      });

      log(DEBUG, `Iteration ${iteration} LLM response:`, llmResponse);

      const toolCalls = llmResponse.tool_calls;

      if ((!toolCalls || toolCalls.length === 0) && llmResponse.content) {
        finalResponse =
          typeof llmResponse.content === "string"
            ? llmResponse.content
            : JSON.stringify(llmResponse.content);
        log(
          INFO,
          `Final response received after ${iteration} iterations:`,
          finalResponse,
        );
        break;
      }

      if (toolCalls && toolCalls.length > 0) {
        log(
          INFO,
          `Iteration ${iteration}: executing ${toolCalls.length} tool(s)`,
        );
        totalToolsUsed += toolCalls.length;

        conversationHistory.push(llmResponse);

        for (const toolCall of toolCalls) {
          log(
            INFO,
            `Executing tool: ${toolCall.name} with args:`,
            toolCall.args,
          );

          const composioCompatibleToolCall: ChatCompletionMessageToolCall = {
            id: toolCall.id || uuidv4(),
            type: "function",
            function: {
              name: toolCall.name,
              arguments: JSON.stringify(toolCall.args),
            },
          };

          let toolOutputContent: string;
          try {
            const executionResult = await toolset.executeToolCall(
              composioCompatibleToolCall,
            );
            log(
              INFO,
              `Tool ${toolCall.name} execution result:`,
              executionResult,
            );
            toolOutputContent = JSON.stringify(executionResult);
          } catch (toolError) {
            log(ERROR, `Tool ${toolCall.name} execution error:`, toolError);
            const errorMessage =
              toolError instanceof Error
                ? toolError.message
                : String(toolError);

            toolOutputContent = `Error: ${errorMessage}`;
          }

          conversationHistory.push(
            new ToolMessage({
              content: toolOutputContent,
              tool_call_id: toolCall.id || uuidv4(),
            }),
          );
        }

        continue;
      }

      log(
        WARN,
        `Iteration ${iteration}: LLM provided no tool calls or content`,
      );
      break;
    }

    let userFriendlyResponse: string;

    if (totalToolsUsed > 0) {
      log(DEBUG, "Generating user-friendly summary using LLM");

      try {
        const summaryResponse = await llm.invoke([
          new SystemMessage(
            "You are tasked with creating a brief, friendly summary for a Discord user about what actions were just completed. Keep it conversational, under 2-3 sentences, and focus on what was accomplished rather than technical details. Start with phrases like 'Done!', 'Successfully completed', 'All set!', etc.",
          ),
          new HumanMessage(
            `The user requested: "${state.message.content}"

I used ${totalToolsUsed} tools across ${iteration} iterations to complete their request. ${finalResponse ? `My final response was: ${finalResponse}` : "The task was completed successfully."}

Generate a brief, friendly summary of what was accomplished.`,
          ),
        ]);

        userFriendlyResponse =
          typeof summaryResponse.content === "string"
            ? summaryResponse.content
            : `Done! I've completed your request using ${totalToolsUsed} action${totalToolsUsed > 1 ? "s" : ""}.`;

        log(INFO, "Generated user-friendly summary:", userFriendlyResponse);
      } catch (summaryError) {
        log(ERROR, "Failed to generate summary:", summaryError);
        userFriendlyResponse = `All set! I've completed your request using ${totalToolsUsed} action${totalToolsUsed > 1 ? "s" : ""}.`;
      }
    } else {
      userFriendlyResponse =
        finalResponse ||
        `I understood your request about '${parsedActionDetails.task}' but couldn't find the right tools to complete it.`;
    }

    const actionLog = `Service: ${parsedActionDetails.service}, Task: ${parsedActionDetails.task}. Used ${totalToolsUsed} tools across ${iteration} iterations.`;

    return {
      toolCallRequest: {
        actionLog,
        status: totalToolsUsed > 0 ? "success" : "acknowledged",
      },
      finalAction: {
        type: "REPLY_IN_THREAD",
        content: userFriendlyResponse,
      },
    };
  } catch (error) {
    log(ERROR, "processing tool call with Composio:", error);
    const errorMessage = error instanceof Error ? error.message : String(error);

    return {
      toolCallRequest: {
        actionLog: `Error during tool call (Service: ${parsedActionDetails.service}, Task: ${parsedActionDetails.task}). Error: ${errorMessage}`,
        status: "failed",
      },
      finalAction: {
        type: "REPLY_IN_THREAD",
        content: "Sorry, I encountered an error while processing your request.",
      },
    };
  }
};

The part up until the first try-catch block is the same. Up until then, you're figuring out the tool the user is trying to call. Now comes the juicy part: actually handling tool calls.

At this point, you need to fetch the tools from Composio. Here, I’m just passing in Google Sheets as the option for demo purposes, but you could use literally anything once you authenticate yourself as shown above.

After fetching the tools, you enter a loop where the LLM can use them. It reviews the conversation history and decides which tools to call. You execute these calls, feed the results back, and repeat for up to 5 iterations or until the LLM gives a final answer.

This loop runs up to 5 times as a safeguard so the LLM doesn’t get stuck in an endless back-and-forth.

If tools were used, you ask the LLM to write a friendly summary for the user instead of dumping the raw JSON response. If no tools worked or none matched, just let the user know you couldn’t perform the action.

Now with that, you’re done with the difficult part (I mean, it was pretty easy though, right?). From here on, you just need to set up and work with the Discord API using Discord.js.

Set Up Discord.js Client

In this application, you’re using slash commands. To use slash commands in Discord, you need to register them first. You can do this manually, but why not automate it as well? 😉

Create a new file named slash-deploy.ts inside the utils directory and add the following lines of code:

// 👇 discord-bot-langgraph/utils/slash-deploy.ts

import { REST, Routes } from "discord.js";
import dotenv from "dotenv";
import { log, INFO, ERROR } from "./logger.js";
import {
  DISCORD_BOT_TOKEN,
  DISCORD_BOT_GUILD_ID,
  OPENAI_API_KEY,
  DISCORD_BOT_CLIENT_ID,
  validateEnvVars,
} from "./env-validator.js";

dotenv.config();

const requiredEnvVars = [
  DISCORD_BOT_TOKEN,
  DISCORD_BOT_GUILD_ID,
  DISCORD_BOT_CLIENT_ID,
  OPENAI_API_KEY,
];
validateEnvVars(requiredEnvVars);

const commands = [
  {
    name: "ask",
    description: "Ask the AI assistant a question or give it a command.",
    options: [
      {
        name: "prompt",
        type: 3,
        description: "Your question or command for the bot",
        required: true,
      },
    ],
  },
];

const rest = new REST({ version: "10" }).setToken(
  process.env.DISCORD_BOT_TOKEN!,
);

(async () => {
  try {
    log(INFO, "deploying slash(/) commands");
    await rest.put(
      Routes.applicationGuildCommands(
        process.env.DISCORD_BOT_CLIENT_ID!,
        process.env.DISCORD_BOT_GUILD_ID!,
      ),
      {
        body: commands,
      },
    );

    log(INFO, "slash(/) commands deployed");
  } catch (error) {
    log(ERROR, "deploying slash(/) commands:", error);
  }
})();

See your validateEnvVars function in action? Here, you’re specifying the environment variables that must be set before running the program. If any are missing and you try to run the program, you’ll get an error.

The way you deploy the slash commands to Discord is using the REST API provided by discord.js, specifically by calling rest.put with your command data and target guild.

Now, simply run the commands:deploy bun script and you should have /ask registered as a slash command in your Discord.

At this point, you should see the /ask slash command available in your server. All that’s left is to create the index.ts file, which will be the entry point to your Discord bot.

Create a new file named index.ts inside the src directory and add the following lines of code:

// 👇 discord-bot-langgraph/src/index.ts

import dotenv from "dotenv";
import {
  Client,
  Events,
  GatewayIntentBits,
  EmbedBuilder,
  type Interaction,
} from "discord.js";
import { initializeGraph } from "./graph.js";
import { type Message as ChatMessage } from "../types/types.js";
import { ERROR, INFO, log } from "../utils/logger.js";
import {
  DISCORD_BOT_TOKEN,
  DISCORD_BOT_GUILD_ID,
  OPENAI_API_KEY,
  validateEnvVars,
  DISCORD_BOT_CLIENT_ID,
  COMPOSIO_API_KEY,
} from "../utils/env-validator.js";

dotenv.config();

const requiredEnvVars = [
  DISCORD_BOT_CLIENT_ID,
  DISCORD_BOT_TOKEN,
  DISCORD_BOT_GUILD_ID,

  OPENAI_API_KEY,

  COMPOSIO_API_KEY,
];
validateEnvVars(requiredEnvVars);

const graph = initializeGraph();

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,
  ],
});

// use a map to store history per channel to make it work properly with all the
// channels and not for one specific channel.
const channelHistories = new Map<string, ChatMessage[]>();

client.on(Events.ClientReady, async (readyClient) => {
  log(INFO, `logged in as ${readyClient.user.tag}. ready to process commands!`);
});

client.on(Events.InteractionCreate, async (interaction: Interaction) => {
  if (!interaction.isChatInputCommand()) return;
  if (interaction.commandName !== "ask") return;

  const userPrompt = interaction.options.getString("prompt", true);
  const user = interaction.user;
  const channelId = interaction.channelId;

  if (!channelHistories.has(channelId)) channelHistories.set(channelId, []);

  const messageHistory = channelHistories.get(channelId)!;

  const currentUserMessage: ChatMessage = {
    author: user.username,
    content: userPrompt,
  };

  const graphInput = {
    message: currentUserMessage,
    previousMessages: [...messageHistory],
  };

  messageHistory.push(currentUserMessage);
  if (messageHistory.length > 20) messageHistory.shift();

  try {
    await interaction.reply({
      content: "Hmm... processing your request! 🐀",
    });

    const finalState = await graph.invoke(graphInput);

    if (!finalState.finalAction) {
      log(ERROR, "no final action found");
      await interaction.editReply({
        content: "I'm sorry, I couldn't process your request.",
      });
      return;
    }

    const userPing = `<@${user.id}>`;
    const action = finalState.finalAction;

    const quotedPrompt = `🗣️ "${userPrompt}"`;

    switch (action.type) {
      case "REPLY":
        await interaction.editReply({
          content: `${userPing}\n\n${quotedPrompt}\n\n${action.content}`,
        });
        break;

      case "REPLY_IN_THREAD":
        if (!interaction.channel || !("threads" in interaction.channel)) {
          await interaction.editReply({
            content: "Cannot create a thread in this channel",
          });
          return;
        }

        try {
          const thread = await interaction.channel.threads.create({
            name: `Action: ${userPrompt.substring(0, 50)}...`,
            autoArchiveDuration: 60,
          });

          await thread.send(
            `${userPing}\n\n${quotedPrompt}\n\n${action.content}`,
          );
          await interaction.editReply({
            content: `I've created a thread for you: ${thread.url}`,
          });
        } catch (threadError) {
          log(ERROR, "failed to create or reply in thread:", threadError);
          await interaction.editReply({
            content: `${userPing}\n\n${quotedPrompt}\n\nI tried to create a thread but failed. Here is your response:\n\n${action.content}`,
          });
        }
        break;

      case "CREATE_EMBED": {
        const embed = new EmbedBuilder()
          .setColor(0xffa500)
          .setTitle(action.title)
          .setDescription(action.description)
          .setTimestamp()
          .setFooter({ text: "Support System" });

        const rolePing = action.roleToPing ? `<@${action.roleToPing}>` : "";

        await interaction.editReply({
          content: `${userPing} ${rolePing}`,
          embeds: [embed],
        });
        break;
      }
    }
  } catch (error) {
    log(ERROR, "generating AI response or processing graph:", error);
    const errorMessage =
      "sorry, I encountered an error while processing your request.";
    if (interaction.replied || interaction.deferred) {
      await interaction.followUp({ content: errorMessage, ephemeral: true });
    } else {
      await interaction.reply({ content: errorMessage, ephemeral: true });
    }
  }
});

const token = process.env.DISCORD_BOT_TOKEN!;
client.login(token);

At the core of our bot is the Client object from discord.js. This represents your bot and handles everything from connecting to Discord’s API to listening for events like user messages or interactions.

What’s with that intent? Discord uses intents as a way for bots to declare what kind of data they want access to. In our case:

• Guilds lets the bot connect to servers

• GuildMessages allows it to see messages

• MessageContent gives access to the actual content of messages

These are quite standard, and there are many more based on different use cases. You can always check them all out here.

You also keep a Map to store per-channel message history so the bot can respond with context across multiple channels:

const channelHistories = new Map<string, ChatMessage[]>();

Discord.js provides access to a few events that you can listen to. When you work with slash commands, it registers an Events.InteractionCreate, which is what you’re listening to.

With every /ask command, you take the user's prompt and any previous messages. If channelHistories does not have a key with that specific channelId, meaning it's being used for the first time, you initialize it with an empty array and feed them into the AI state.

const finalState = await graph.invoke({
  message: currentUserMessage,
  previousMessages: [...messageHistory],
});

Depending on what the graph finalAction.type returns, you either:

• reply directly,

• create a thread and respond there,

• or send an embed (for support-type replies).

If a thread can’t be created, you fall back to replying in the main channel. Message history is capped at 20 to keep things lightweight.

Note that we’re not really using previousMessages much at the moment in the application, but I’ve prepared everything you need to handle querying previous conversations. You could easily create a new LangGraph node that queries or reasons over history if the bot needs to reference past conversations. (Take this as your challenge!)

This project should give you a basic idea of how you can use LangGraph + Composio to build a somewhat useful bot that can already handle decent stuff. There’s a lot more you could improve. I’ll leave that up to you. ✌️

Here’s a quick demo of what we’ve built so far:

Wrapping Up

By now you should have a good idea of how LangGraph works and also how to power the bot with integrations using Composio.

This is just a fraction of what you can do. Try adding more features and more integration support to the bot to fit your workflow. This can come in really handy.

If you got lost somewhere while coding along, you can find the source code here.

So, that is it for this article. Thank you so much for reading! See you next time. 🫡

Love to build cool stuff like this? I regularly build such stuff every few weeks. Feel free to reach out to me here:

• GitHub: github.com/shricodev

• Portfolio: techwithshrijal.com

• LinkedIn: linkedin.com/in/iamshrijal

And I’m not an exception to this. I wanted to create more content, and had an idea based on something I’ve observed. I subscribe to a few technology newsletters, and I read lots of updates every day about the tech ecosystem. But I’ve noticed that many of my peers often don’t seem to be aware of this news. So, I decided to post my top three news stories (especially about AI) on my Twitter/X account every day.

I did this for a couple of weeks, but after that I couldn’t find the time to keep it going. So, I did some research into how I could automate the process, and I found a solution. In this guide, I’ll explain the process so you can use it, too.

By the end of this tutorial, you’ll have created your own AI bot that:

• Fetches data from an API or crawls a webpage

• Processes the data using AI

• Posts the results on Twitter/X

And the great thing: this entire process is automated.

Table of Contents

• Prerequisites

• How to Build the Bot

  • Step 1: Generate the Twitter API Key

  • Step 2: Generate Access Token and Secret

  • Step 3: Generate an API Key in Google Gemini

• Node.js Project Setup

  • Step 1: Fetch Data from the API

  • Step 2: Upload the Data as a File to Gemini API

  • Step 3: Prompt Gemini to Get the Latest AI News

  • Step 4: Post Using the Twitter/X API

  • Step 5: Delete the File Uploaded in the Gemini API

  • The Result

• Conclusion

Prerequisites

Before we begin creating a bot, you’ll need to have the following setup and tools ready to go:

• NodeJS - A simple NodeJS app to code the bot

You’ll also need some API keys, secrets, and tokens. So, you’ll need to have the following accounts created:

• Twitter Developer – To generate the Twitter/X API keys, secrets, and tokens

• Google AI Studio – To generate the Gemini API key

How to Build the Bot

There are a number of steps I’ll walk you through to build your bot.

We’ll start by generating an API Key and Secret so we can use the Twitter/X API. Then we’ll generate an access token and access token secret with “Read and Write” permissions that’ll be able to post in your account. After that we’ll generate an API Key in Google Gemini (we’ll be using the Gemini API to process the data).

With all that taken care of, we’ll start working on the Node.js app. The app will be able to fetch data from an API, process the data using AI, and then post that data in the form of tweets on Twitter/X.

Finally, we’ll automate the entire process and schedule it to run daily.

Step 1: Generate the Twitter API Key

1. Navigate to Twitter Developer Website.

2. Click on the “Developer Portal” in the top right:

   

3. Signup using your account.

4. You’ll be asked to fill out a form asking how will you use the Twitter API, and a few basic details. It may take up to 24 hours to get approved. But, it’s approved instantly for me.

   

5. After login, Navigate to "Projects and Apps" and under “Overview” click on "Create App":

   

6. Enter a name for your app and click “Next” to proceed with creating your app. At the end, you’ll be shown your API Key and Secret. Don’t copy that now.

7. Click on the project you created from the left side drawer and click on the "Edit" option in “User authentication settings” section.

   

8. Select “Read and Write” in App Permissions section, “Web App, Automated App or Bot” in Type of App section, and enter your website URL (it can be any URL including http://localhost) in the “Callback URI” and “Website URL”. Then hit “Save”.

9. Go to “Keys and tokens” tab.

10. Click on “Regenerate” button in “API Key and Secret” section.

11. Copy and save the API Key and Secret somewhere securely.

Step 2: Generate Access Token and Secret

1. Go to “Keys and tokens” tab.

2. Click on “Generate” or “Regenerate” button in “Access Token and Secret” section.

3. Copy and save the Access Token and Secret somewhere securely.

   

Step 3: Generate an API Key in Google Gemini

1. Navigate to Google AI Studio.

2. Login to your account.

3. Click on “Get API Key” button at the top right.

4. Click on “Create API Key” button.

   

5. Copy and save the API Key somewhere securely.

Alright, we are done with creating the necessary API Keys and Secrets for our project. Let’s put on our coding shoes.

Node.js Project Setup

There are 5 major steps for this part of the project. They are:

1. Fetch data from the API

2. Upload the data as a file to Gemini API

3. Prompt Gemini with the uploaded file to get the latest AI news

4. Post news to Twitter/X using their API

5. Delete the file uploaded in Gemini API

These are just the snippets of code that can be assembled together to run this project.

Step 1: Fetch Data from the API

In my case, I’ll be using techmeme.com to get the latest news. But this site does not offer an API. So, I’ll be downloading the HTML of this site.

In the User-Agent header, we pass the value that mimics a browser user agent to avoid potential blocks.

Step 2: Upload the Data as a File to Gemini API

Now we need to store this HTML in a separate file. We cannot directly pass the HTML code in the prompt to the Gemini API, as it’ll result in an error. This is because Gemini accepts only a limited number of tokens in this API. The HTML code of any website will always result in huge number of tokens. So, we’ll create a separate file.

Upload the file to the Gemini API. Refer to the file id in the prompt to Gemini.

Step 3: Prompt Gemini to Get the Latest AI News

Let’s write a prompt to Gemini asking it to generate top news by referring to the HTML file provided. We’ll ask it to provide a headline, short description, URL, and three relevant hashtags for each tweet. We’ll also give some example data of how it should look. We’ll ask it to generate a structured response by providing the format of the JSON that we want the output to be.

You can use whatever model you want to, but I’ll be using the gemini-2.5-pro-exp-03-25 model for this use case. I’m using this model because we need a thinking model that thinks and picks the correct top news – not just one that predicts the next token/word. The Gemini 2.5 Pro model best qualifies for this.

Step 4: Post Using the Twitter/X API

Here’s the core of our app. We need to post all the tweets we received from Gemini. We’ll be posting the tweet as a thread. This means that the first tweet will be the root tweet and subsequent tweets will be in the comments of the prior tweet. This makes it a thread.

To do this, we’ll take the id of each tweet after it’s posted and pass it on to the next tweet as a reference. One additional thing to note here is, after each successful tweet, we’ll give a pause of 5 seconds before posting the next tweet. There are few reasons for doing it this way.

1. When any script runs, it usually runs at a much higher speed (usually in milliseconds). So, the second tweet may get posted before the first tweet was posted (maybe due to some poor internet connection). Also, I believe Twitter implements some queue system which may quickly process the second tweet before your first. So it’s always better to leave a small gap – if not 5 seconds then at least 1 second

2. Twitter may have implemented some rate limiting mechanism. So if there are multiple request received from a same IP within a short time frame, they may block the IP and consider your account as spam.

3. Since we’re using a Free tier API, we are limited to 1500 tweets per month. If you’ve paid for this API, you won’t have to worry about this (since you’ll have a higher limit and the rate limiting mechanism –refer to point #2 – might not be applicable). All of this depends on their pricing, so just refer to that and make your call accordingly.

I’m using the free tier, and since it’s a hobby project, having a 5 seconds wait time makes sense. I have not faced any issues so far with this.

Step 5: Delete the File Uploaded in the Gemini API

After posting all the tweets, it’s time to clean up the system. The only thing we need to do as a clean up is delete the uploaded file. It’s always a best practice to remove an unused file that’s no longer needed. And since we’ve already posted the tweets, we no longer need that file. So, we’ll be deleting it in this step.

That’s it. We’re all done. You just need to copy these blocks of code into an index.js file and install some dependencies into the project and you should be good to go.

To make this even more simple, I have created a repo and made it public. Here’s the Github repo URL. You just need to clone the repo, install the dependencies, and run the post command

git clone https://github.com/arunachalam-b/existential-crisis-alert-bot.git
cd existential-crisis-alert-bot
npm i

Create a .env file and update your API keys and secrets in that file:

GEMINI_API_KEY=
TWITTER_API_KEY=
TWITTER_API_SECRET=
TWITTER_ACCESS_TOKEN=
TWITTER_ACCESS_TOKEN_SECRET=

Run the following command to post the latest AI news to your account:

npm run post

The Result

Here’s a sample output of that command:

You can modify the code/prompt to fetch data from a different API and post the top results in your Twitter account.

Conclusion

I hope you now understand how you can automate a slightly complex process using AI and some APIs. Just note that this example is not completely automated. You still have to manually run the command everyday to post the tweets.

But you can automate that process as well. Just drop me a message if you wish to know about that. That topic itself deserves to be a separate tutorial. Also, I would request that you give a star for my project if you enjoyed this tutorial.

Meanwhile, you can follow my Twitter/X account to receive the top AI news everyday. If you wish to learn more about automation, subscribe to my email newsletter (https://5minslearn.gogosoon.com/) and follow me on social media.