The Discord API provides you with an easy tool to create and use your own bots and tools.

In this tutorial, you'll learn how you can create a basic music bot and add it to your server. The bot will be able to play, skip, and stop the music, and will also support queuing functionality.

Table of Contents

1. Prerequisites
2. How to Set Up a Discord Bot
   – How to add the bot to your server
   – How to create your project
   – Discord.js basics
3. Discord Bot Version 0.13
   – How to create the Discord player
   – How to add slash commands
   – How to implement interactions
   – How to play songs
   – How to skip songs
   – How to stop songs
   – Complete source code for index.js
4. Discord Bot Version 0.12
   – How to read messages
   – How to add songs
   – How to play songs
   – How to skip songs
   – How to stop songs
   – Complete source code for index.js
5. Conclusion

Prerequisites

Before we get started creating the bot, make sure that you have installed all the tools you'll need:

• Node
• NPM
• FFMPEG

After you've installed these, you can continue by setting up your discord bot.

How to Set Up a Discord Bot

First, you need to create a new application on the discord development portal.

You can do so by visiting the portal and clicking on New Application.

Create a new Discord application

After that, you need to give your application a name and click the Create button.

Give your bot whatever name you like - I've chosen "music-bot"

After that, select the bot tab and click on Add Bot.

Add your bot under the "Bot" tab

Now your bot is created and you can continue with inviting it to your server.

How to add the bot to your server

After creating your bot, you can invite it using the OAuth2 URL Generator.

For that, you need to navigate to the OAuth2 page and select bot in the scope tap.

Selecting "bot" on the 0Auth2 Generator page

After that, you need to select the needed permissions to play music and read messages.

Select the permissions you'll need - "read messages/view channels", "send messages", "manage messages", "add reactions", "use slash commands", "connect", and "speak.

Then you can copy your generated URL and paste it into your browser.

Copy the URL

After pasting it, add it to your server by selecting the server and clicking the authorize button.

How to create your project

Now you can start creating your project using the terminal.

First, create a directory and move into it. You can do so by using these two commands:

mkdir musicbot && cd musicbot

After that, create your project modules using the npm init command. After entering the command, you will be asked some questions – just answer them and continue.

Then you just need to create the two files you will work in.

touch index.js && touch config.json

Now, open your project in your text editor. I personally use VS Code and can open it with the following command:

code .

Discord.js basics

Now you need to install some dependencies before we can get started.

npm install discord.js@^12.5.3 ffmpeg fluent-ffmpeg @discordjs/opus ytdl-core --save

After the installation finishes, you can continue with writing your config.json file. Here, save the token of your bot and the prefix it should listen for.

{
"prefix": "!",
"token": "your-token"
}

To get your token, you need to visit the discord developer portal again and copy it from the bot section.

Get your bot token by clicking "Copy" and save it somewhere safe

Those are the only things you need to do in your config.json file. So now it's time to start writing your JavaScript code.

The article includes two versions: one for the new discord.js v13, which uses slash commands combined with the discord-player library to implement the music functionality, and one for discord.js v12.5.3, which implements the functionality without a library.

The older version is better for learning purposes, and the newer version works with the current discord.js and is a lot easier to implement – so choose which you prefer.

Discord Bot Version 0.13

Now you just need to install some more dependencies before we can get started.

npm install discord.js discord-player @discordjs/opus

After installing the dependencies, import them in your dependencies.

const { Client, GuildMember, Intents } = require("discord.js");
const { Player, QueryType } = require("discord-player");
const config = require("./config.json");

After that, create your client and log in using your token.

const client = new Client({
    intents: [Intents.FLAGS.GUILD_VOICE_STATES, Intents.FLAGS.GUILD_MESSAGES, Intents.FLAGS.GUILDS]
});
client.login(config.token);

Now add some basic listeners that console.log when they get executed.

client.once('ready', () => {
 console.log('Ready!');
});

client.on("error", console.error);
client.on("warn", console.warn);

After that, you can start your bot using the node command and the bot should be online on Discord and print “Ready!” in the console.

node index.js

How to create the Discord player

Now that you've created the client for the discord bot, you can continue by initializing your player. This will allow you to play and manage music in your Discord channel.

const player = new Player(client);

You can also add some error handlers that will be called if an error occurs.

player.on("error", (queue, error) => {
    console.log(`[${queue.guild.name}] Error emitted from the queue: ${error.message}`);
});
player.on("connectionError", (queue, error) => {
    console.log(`[${queue.guild.name}] Error emitted from the connection: ${error.message}`);
});

The last thing you need to do is add listeners for the different player events like a song starting or being added.

player.on("trackStart", (queue, track) => {
    queue.metadata.send(`🎶 | Started playing: **${track.title}** in **${queue.connection.channel.name}**!`);
});

player.on("trackAdd", (queue, track) => {
    queue.metadata.send(`🎶 | Track **${track.title}** queued!`);
});

player.on("botDisconnect", (queue) => {
    queue.metadata.send("❌ | I was manually disconnected from the voice channel, clearing queue!");
});

player.on("channelEmpty", (queue) => {
    queue.metadata.send("❌ | Nobody is in the voice channel, leaving...");
});

player.on("queueEnd", (queue) => {
    queue.metadata.send("✅ | Queue finished!");
});

In most cases, you just send a message into the Discord text channel using the send() function.

How to add slash commands

After you've set up the player successfully, you can continue by adding your Slash commands to your client. This step lets Discord know which commands the bot can execute.

client.on("messageCreate", async (message) => {
        if (message.author.bot || !message.guild) return;
    if (!client.application?.owner) await client.application?.fetch();
});

You can do this by implementing a simple !deploy command that saves your commands in the guild.commands variable of a message.

A slash command has a name, a description, and an optional options field that contains the command’s parameters. For example, the play command takes a song query as an argument.

client.on("messageCreate", async (message) => {
        ...

        if (message.content === "!deploy" && message.author.id === client.application?.owner?.id) {
        await message.guild.commands.set([
            {
                name: "play",
                description: "Plays a song from youtube",
                options: [
                    {
                        name: "query",
                        type: "STRING",
                        description: "The song you want to play",
                        required: true
                    }
                ]
            },
            {
                name: "skip",
                description: "Skip to the current song"
            },
            {
                name: "queue",
                description: "See the queue"
            },
            {
                name: "stop",
                description: "Stop the player"
            },
        ]);

        await message.reply("Deployed!");
    }
});

After entering !deploy in your Discord text chat, the slash commands will be added to your application. When typing / into the chat you should see something similar to this:

Example of using the slash commands

How to implement interactions

Once the interactions (slash commands) are defined, now you'll need to implement them.

All slash commands trigger the interactionCreate event and can be implemented inside the async function below. Before executing any functionality, run a few conditionals to check if the user is allowed to perform the given functionality.

client.on("interactionCreate", async (interaction) => {
    if (!interaction.isCommand() || !interaction.guildId) return;

    if (!(interaction.member instanceof GuildMember) || !interaction.member.voice.channel) {
        return void interaction.reply({ content: "You are not in a voice channel!", ephemeral: true });
    }

    if (interaction.guild.me.voice.channelId && interaction.member.voice.channelId !== interaction.guild.me.voice.channelId) {
        return void interaction.reply({ content: "You are not in my voice channel!", ephemeral: true });
    }
});

After that, check which command is being executed by matching the commandName with the name of the commands you defined above.

client.on("interactionCreate", async (interaction) => {
    ...

        if (interaction.commandName === "play") {
            // TODO: Implement play command
        }
});

You can then add the implementation inside of the if statement.

How to play songs

The play command requires you to search for the provided song and add the result to the current queue of songs.

Let’s start by retrieving the user-provided query using the options.get() function. After that you can use the player.search() function to search for the desired song.

if (interaction.commandName === "play") {
    await interaction.deferReply();

    const query = interaction.options.get("query").value;
    const searchResult = await player
        .search(query, {
            requestedBy: interaction.user,
            searchEngine: QueryType.AUTO
        })
        .catch(() => {});
    if (!searchResult || !searchResult.tracks.length) return void interaction.followUp({ content: "No results were found!" });
}

Now that you have the song, you can create a queue for the songs (if there is already a queue, the createQueue function will return the existing one).

Once the queue is created, you can try joining the user’s voice channel. If that is successful, add the song to the current queue using the addTracks function.

if (interaction.commandName === "play") {
    ...

        const queue = await player.createQueue(interaction.guild, {
        metadata: interaction.channel
    });

    try {
        if (!queue.connection) await queue.connect(interaction.member.voice.channel);
    } catch {
        void player.deleteQueue(interaction.guildId);
        return void interaction.followUp({ content: "Could not join your voice channel!" });
    }

    await interaction.followUp({ content: `⏱ | Loading your ${searchResult.playlist ? "playlist" : "track"}...` });
    searchResult.playlist ? queue.addTracks(searchResult.tracks) : queue.addTrack(searchResult.tracks[0]);
    if (!queue.playing) await queue.play();
}

Lastly, if the queue isn’t already playing, let’s start it using the play() function.

How to skip songs

Skipping is quite easy – you can do it by calling the skip() function on the queue.

if (interaction.commandName === "skip") {
    await interaction.deferReply();
    const queue = player.getQueue(interaction.guildId);
    if (!queue || !queue.playing) return void interaction.followUp({ content: "❌ | No music is being played!" });
    const currentTrack = queue.current;
    const success = queue.skip();
    return void interaction.followUp({
        content: success ? `✅ | Skipped **${currentTrack}**!` : "❌ | Something went wrong!"
    });
}

If the action is successful, you can write a message to the Discord text channel using interaction.followUp().

How to stop songs

The stop functionality will remove all the songs from the queue and the bot will leave the voice channel. You can do this by destroying the current queue which automatically makes the bot leave the voice channel (unless you configure it otherwise in the player configuration).

else if (interaction.commandName === "stop") {
        await interaction.deferReply();
        const queue = player.getQueue(interaction.guildId);
        if (!queue || !queue.playing) return void interaction.followUp({ content: "❌ | No music is being played!" });
        queue.destroy();
        return void interaction.followUp({ content: "🛑 | Stopped the player!" });
    }

Complete source code for the index.js:

Here you can get the complete source code for the music bot:

const { Client, GuildMember, Intents } = require("discord.js");
const { Player, QueryType } = require("discord-player");
const config = require("./config.json");

const client = new Client({
    intents: [Intents.FLAGS.GUILD_VOICE_STATES, Intents.FLAGS.GUILD_MESSAGES, Intents.FLAGS.GUILDS]
});

client.on("ready", () => {
    console.log("Bot is online!");
    client.user.setActivity({
        name: "🎶 | Music Time",
        type: "LISTENING"
    });
});
client.on("error", console.error);
client.on("warn", console.warn);

const player = new Player(client);

player.on("error", (queue, error) => {
    console.log(`[${queue.guild.name}] Error emitted from the queue: ${error.message}`);
});
player.on("connectionError", (queue, error) => {
    console.log(`[${queue.guild.name}] Error emitted from the connection: ${error.message}`);
});

player.on("trackStart", (queue, track) => {
    queue.metadata.send(`🎶 | Started playing: **${track.title}** in **${queue.connection.channel.name}**!`);
});

player.on("trackAdd", (queue, track) => {
    queue.metadata.send(`🎶 | Track **${track.title}** queued!`);
});

player.on("botDisconnect", (queue) => {
    queue.metadata.send("❌ | I was manually disconnected from the voice channel, clearing queue!");
});

player.on("channelEmpty", (queue) => {
    queue.metadata.send("❌ | Nobody is in the voice channel, leaving...");
});

player.on("queueEnd", (queue) => {
    queue.metadata.send("✅ | Queue finished!");
});

client.on("messageCreate", async (message) => {
    if (message.author.bot || !message.guild) return;
    if (!client.application?.owner) await client.application?.fetch();

    if (message.content === "!deploy" && message.author.id === client.application?.owner?.id) {
        await message.guild.commands.set([
            {
                name: "play",
                description: "Plays a song from youtube",
                options: [
                    {
                        name: "query",
                        type: "STRING",
                        description: "The song you want to play",
                        required: true
                    }
                ]
            },
            {
                name: "skip",
                description: "Skip to the current song"
            },
            {
                name: "stop",
                description: "Stop the player"
            },
        ]);

        await message.reply("Deployed!");
    }
});

client.on("interactionCreate", async (interaction) => {
    if (!interaction.isCommand() || !interaction.guildId) return;

    if (!(interaction.member instanceof GuildMember) || !interaction.member.voice.channel) {
        return void interaction.reply({ content: "You are not in a voice channel!", ephemeral: true });
    }

    if (interaction.guild.me.voice.channelId && interaction.member.voice.channelId !== interaction.guild.me.voice.channelId) {
        return void interaction.reply({ content: "You are not in my voice channel!", ephemeral: true });
    }

    if (interaction.commandName === "play") {
        await interaction.deferReply();

        const query = interaction.options.get("query").value;
        const searchResult = await player
            .search(query, {
                requestedBy: interaction.user,
                searchEngine: QueryType.AUTO
            })
            .catch(() => {});
        if (!searchResult || !searchResult.tracks.length) return void interaction.followUp({ content: "No results were found!" });

        const queue = await player.createQueue(interaction.guild, {
            metadata: interaction.channel
        });

        try {
            if (!queue.connection) await queue.connect(interaction.member.voice.channel);
        } catch {
            void player.deleteQueue(interaction.guildId);
            return void interaction.followUp({ content: "Could not join your voice channel!" });
        }

        await interaction.followUp({ content: `⏱ | Loading your ${searchResult.playlist ? "playlist" : "track"}...` });
        searchResult.playlist ? queue.addTracks(searchResult.tracks) : queue.addTrack(searchResult.tracks[0]);
        if (!queue.playing) await queue.play();
    } else if (interaction.commandName === "skip") {
        await interaction.deferReply();
        const queue = player.getQueue(interaction.guildId);
        if (!queue || !queue.playing) return void interaction.followUp({ content: "❌ | No music is being played!" });
        const currentTrack = queue.current;
        const success = queue.skip();
        return void interaction.followUp({
            content: success ? `✅ | Skipped **${currentTrack}**!` : "❌ | Something went wrong!"
        });
    } else if (interaction.commandName === "stop") {
        await interaction.deferReply();
        const queue = player.getQueue(interaction.guildId);
        if (!queue || !queue.playing) return void interaction.followUp({ content: "❌ | No music is being played!" });
        queue.destroy();
        return void interaction.followUp({ content: "🛑 | Stopped the player!" });
    } else {
        interaction.reply({
            content: "Unknown command!",
            ephemeral: true
        });
    }
});

client.login(config.token);

Discord Bot Version 0.12

Now you'll just need to install some dependencies before we can get started.

npm install discord.js ffmpeg fluent-ffmpeg @discordjs/opus ytdl-core --save

After installing the dependencies, import them in your dependencies.

const Discord = require('discord.js');
const {
    prefix,
    token,
} = require('./config.json');
const ytdl = require('ytdl-core');

After that, create your client and login using your token.

const client = new Discord.Client();
client.login(token);

Now let’s add some basic listeners that console.log when they get executed.

client.once('ready', () => {
 console.log('Ready!');
});
client.once('reconnecting', () => {
 console.log('Reconnecting!');
});
client.once('disconnect', () => {
 console.log('Disconnect!');
});

After that, you can start your bot using the node command and it should be online on Discord and print “Ready!” in the console.

node index.js

How to read messages

Now that your bot is on your server and able to go online, you can start reading chat messages and responding to them.

To read messages, you only need to write one simple function:

client.on('message', async message => {

}

Here, you're creating a listener for the message event, getting the message, and saving it into a message object if it's triggered.

Now you need to check if the message is from your own bot and ignore it if it is.

if (message.author.bot) return;

In this line, you're checking if the author of the message is your bot and returning if it is.

After that, check if the message starts with the prefix you defined earlier and return if it doesn’t.

if (!message.content.startsWith(prefix)) return;

After that, you can check which command you need to execute. You can do so using some simple if statements:

const serverQueue = queue.get(message.guild.id);

if (message.content.startsWith(`${prefix}play`)) {
    execute(message, serverQueue);
    return;
} else if (message.content.startsWith(`${prefix}skip`)) {
    skip(message, serverQueue);
    return;
} else if (message.content.startsWith(`${prefix}stop`)) {
    stop(message, serverQueue);
    return;
} else {
    message.channel.send("You need to enter a valid command!");
}

In this code block, you're checking which command to execute and calling the command. If the input command isn’t valid, you're writing an error message into the chat using the send() function.

Now that you know which command you need to execute, you can start implementing these commands.

How to add songs

Let’s start by adding the play command. For that, you'll need a song and a guild (a guild represents an isolated collection of users and channels and is often referred to as a server). You'll also need the ytdl library you installed earlier.

First, create a map with the name of the queue where you save all the songs you type in the chat.

const queue = new Map();

After that, create an async function called execute and check if the user is in a voice chat and if the bot has the right permissions. If not, write an error message and return.

async function execute(message, serverQueue) {
  const args = message.content.split(" ");

  const voiceChannel = message.member.voice.channel;
  if (!voiceChannel)
    return message.channel.send(
      "You need to be in a voice channel to play music!"
    );
  const permissions = voiceChannel.permissionsFor(message.client.user);
  if (!permissions.has("CONNECT") || !permissions.has("SPEAK")) {
    return message.channel.send(
      "I need the permissions to join and speak in your voice channel!"
    );
  }
}

Now you can continue with getting the song info and saving it into a song object. For that, use your ytdl library which gets the song information from the YouTube link.

const songInfo = await ytdl.getInfo(args[1]);
const song = {
 title: songInfo.title,
 url: songInfo.video_url,
};

This will get the information of the song using the ytdl library you installed earlier. Then, save the information you need into a song object.

After saving the song info, you just need to create a contract you can add to your queue.

To do so, first check if your serverQueue is already defined which means that music is already playing. If so, add the song to your existing serverQueue and send a success message. If not, create it and try to join the voice channel and start playing music.

if (!serverQueue) {

}else {
 serverQueue.songs.push(song);
 console.log(serverQueue.songs);
 return message.channel.send(`${song.title} has been added to the queue!`);
}

Here, check if the serverQueueis empty and add the song to it if it’s not. Now you just need to create your contract if the serverQueue is null.

// Creating the contract for our queue
const queueContruct = {
 textChannel: message.channel,
 voiceChannel: voiceChannel,
 connection: null,
 songs: [],
 volume: 5,
 playing: true,
};
// Setting the queue using our contract
queue.set(message.guild.id, queueContruct);
// Pushing the song to our songs array
queueContruct.songs.push(song);

try {
 // Here we try to join the voicechat and save our connection into our object.
 var connection = await voiceChannel.join();
 queueContruct.connection = connection;
 // Calling the play function to start a song
 play(message.guild, queueContruct.songs[0]);
} catch (err) {
 // Printing the error message if the bot fails to join the voicechat
 console.log(err);
 queue.delete(message.guild.id);
 return message.channel.send(err);
}

In this code block, you created a contract and added your song to the songs array. After that, you tried to join the voice chat of the user and called your play() function you'll implement after that.

How to play songs

Now that you can add our songs to your queue and create a contract if there isn’t one yet, you can implement the play functionality.

First, create a function called play which takes two parameters (the guild and the song you want to play) and checks if the song is empty. If so, just leave the voice channel and delete the queue.

function play(guild, song) {
  const serverQueue = queue.get(guild.id);
  if (!song) {
    serverQueue.voiceChannel.leave();
    queue.delete(guild.id);
    return;
  }
}

After that, start playing your song using the play() function of the connection and passing the URL of your song.

const dispatcher = serverQueue.connection
    .play(ytdl(song.url))
    .on("finish", () => {
        serverQueue.songs.shift();
        play(guild, serverQueue.songs[0]);
    })
    .on("error", error => console.error(error));
dispatcher.setVolumeLogarithmic(serverQueue.volume / 5);
serverQueue.textChannel.send(`Start playing: **${song.title}**`);

Here, you created a stream and passed it the URL of our song. You also added two listeners that handle the end and error events.

Note: This is a recursive function which means that it calls itself over and over again. We're using recursion so it plays the next song when the song is finished.

Now you're ready to play a song by just typing the !play URL in the chat.

How to skip songs

Now you can implement the skipping functionality. For that, you just need to end the dispatcher you created in your play() function so it starts the next song.

function skip(message, serverQueue) {
  if (!message.member.voice.channel)
    return message.channel.send(
      "You have to be in a voice channel to stop the music!"
    );
  if (!serverQueue)
    return message.channel.send("There is no song that I could skip!");
  serverQueue.connection.dispatcher.end();
}

Here, you're checking if the user that typed the command is in a voice channel and if there is a song to skip.

How to stop songs

The stop() function is almost the same as skip(), except that you clear the songs array which will make your bot delete the queue and leave the voice chat.

function stop(message, serverQueue) {
  if (!message.member.voice.channel)
    return message.channel.send(
      "You have to be in a voice channel to stop the music!"
    );
  serverQueue.songs = [];
  serverQueue.connection.dispatcher.end();
}

Complete source code for the index.js:

Here you can get the complete source code for the music bot:

const Discord = require("discord.js");
const { prefix, token } = require("./config.json");
const ytdl = require("ytdl-core");

const client = new Discord.Client();

const queue = new Map();

client.once("ready", () => {
  console.log("Ready!");
});

client.once("reconnecting", () => {
  console.log("Reconnecting!");
});

client.once("disconnect", () => {
  console.log("Disconnect!");
});

client.on("message", async message => {
  if (message.author.bot) return;
  if (!message.content.startsWith(prefix)) return;

  const serverQueue = queue.get(message.guild.id);

  if (message.content.startsWith(`${prefix}play`)) {
    execute(message, serverQueue);
    return;
  } else if (message.content.startsWith(`${prefix}skip`)) {
    skip(message, serverQueue);
    return;
  } else if (message.content.startsWith(`${prefix}stop`)) {
    stop(message, serverQueue);
    return;
  } else {
    message.channel.send("You need to enter a valid command!");
  }
});

async function execute(message, serverQueue) {
  const args = message.content.split(" ");

  const voiceChannel = message.member.voice.channel;
  if (!voiceChannel)
    return message.channel.send(
      "You need to be in a voice channel to play music!"
    );
  const permissions = voiceChannel.permissionsFor(message.client.user);
  if (!permissions.has("CONNECT") || !permissions.has("SPEAK")) {
    return message.channel.send(
      "I need the permissions to join and speak in your voice channel!"
    );
  }

  const songInfo = await ytdl.getInfo(args[1]);
  const song = {
    title: songInfo.title,
    url: songInfo.video_url
  };

  if (!serverQueue) {
    const queueContruct = {
      textChannel: message.channel,
      voiceChannel: voiceChannel,
      connection: null,
      songs: [],
      volume: 5,
      playing: true
    };

    queue.set(message.guild.id, queueContruct);

    queueContruct.songs.push(song);

    try {
      var connection = await voiceChannel.join();
      queueContruct.connection = connection;
      play(message.guild, queueContruct.songs[0]);
    } catch (err) {
      console.log(err);
      queue.delete(message.guild.id);
      return message.channel.send(err);
    }
  } else {
    serverQueue.songs.push(song);
    return message.channel.send(`${song.title} has been added to the queue!`);
  }
}

function skip(message, serverQueue) {
  if (!message.member.voice.channel)
    return message.channel.send(
      "You have to be in a voice channel to stop the music!"
    );
  if (!serverQueue)
    return message.channel.send("There is no song that I could skip!");
  serverQueue.connection.dispatcher.end();
}

function stop(message, serverQueue) {
  if (!message.member.voice.channel)
    return message.channel.send(
      "You have to be in a voice channel to stop the music!"
    );
  serverQueue.songs = [];
  serverQueue.connection.dispatcher.end();
}

function play(guild, song) {
  const serverQueue = queue.get(guild.id);
  if (!song) {
    serverQueue.voiceChannel.leave();
    queue.delete(guild.id);
    return;
  }

  const dispatcher = serverQueue.connection
    .play(ytdl(song.url))
    .on("finish", () => {
      serverQueue.songs.shift();
      play(guild, serverQueue.songs[0]);
    })
    .on("error", error => console.error(error));
  dispatcher.setVolumeLogarithmic(serverQueue.volume / 5);
  serverQueue.textChannel.send(`Start playing: **${song.title}**`);
}

client.login(token);

Conclusion

You made it all the way until the end! Hope that this article helped you understand the Discord API and how you can use it to create a simple bot.

If you want to see an example of a more advanced discord bot, you can visit my GitHub repository.

If you have found this useful, please consider recommending and sharing it with other fellow developers.

If you have any questions or feedback, let me know and I'd be happy to help.

The python-telegram-bot v20 release introduced major structural changes. According to the documentation,

“All networking and I/O-related logic now works via coroutine functions (i.e. _async def ..._ functions). In particular, all methods of the _telegram.Bot_ class that make requests to the Bot API are now coroutine functions and need to be await-ed.” — python-telegram-bot v20 change logs

The process of transitioning from python-telegram-bot version 13 to version 20 turned out to be more complex than I had originally anticipated. Converting synchronous def functions to async def and adding await to new coroutines was fairly easy. But the main difficulty was finding detailed documentation on how to build and deploy python-telegram-bot v20 webhooks in a production setting.

This article explains why and how I migrated from:

1. python-telegram-bot v13 → v20
2. Flask → FastAPI
3. Gunicorn → Gunicorn + Uvicorn

Why Upgrade from v13 to v20?

v13.x and older are no longer supported by the python-telegram-bot dev team. If Telegram API introduces any new features, they will only be available on v20 and above.

Why Use a Webhook and Not Polling?

Most examples provided by the python-telegram-bot dev team use Application.run_polling. But webhooks are generally recommended over polling for most Telegram bot use cases, because polling requires your bot to constantly make requests to Telegram’s servers, which can consume significant resources. On the other hand, webhooks offer extended functionality, update faster, and scale better.

The Challenge of using Flask with python-telegram-bot v20

Using a WGSI like Flask with python-telegram-bot v20 is awkward.

Flask, a WSGI (Web Server Gateway Interface), is synchronous and can handle only one request at a time. But you can still run async functions in Flask using asyncio.run(), as in the custom webhook bot example provided by the python-telegram-bot dev team.

asyncio.run() starts an event loop and executes the given coroutine until it completes. If there are any asynchronous tasks running before or after the request is handled, those tasks will be executed in a separate event loop.

# Code snippet from https://docs.python-telegram-bot.org/en/v20.6/examples.customwebhookbot.html

webserver = uvicorn.Server(
    config=uvicorn.Config(
        app=WsgiToAsgi(flask_app),
        port=PORT,
        use_colors=False,
        host="127.0.0.1",
    )
)

async with application:
  await application.start()
  await webserver.serve() # start bot's webserver
  await application.stop()

However, this implementation is slightly awkward because Flask is intrinsically incompatible with async globals.

Examples in the documentation are not suitable for production environments.

Using asyncio.run() as an entry point in production is usually not recommended. The asyncio.run() function is designed for development and testing purposes, and it may not provide the same level of robustness and reliability as production servers like Gunicorn or UWSGI.

These production servers offer many additional features, such as logging, monitoring, and health checks, which are essential for ensuring the stability and security of a production application.

If you want to deploy your bot in production, it’s much cleaner to use an ASGI (Asynchronous Server Gateway Interface) with an ASGI web server implementation.

How to Do It — Migration and Deployment

From Flask (WSGI) to FastAPI (AGSI)

Migrating a Flask application to an ASGI is straightforward. I chose FastAPI because I found a comprehensive migration tutorial here. The syntaxes of both frameworks are quite similar, which means you won’t have to make too many code changes.

# From python-telegram-bot v20
application = (
    Application.builder()
    .updater(None)
    .token(<your-bot-token>) # replace <your-bot-token>
    .read_timeout(7)
    .get_updates_read_timeout(42)
    .build()
)

# From FastAPI
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with application:
        await application.start()
        yield
        await application.stop()

Quart appears to be a feasible alternative, but it does not offer support for deployments using Uvicorn, which is the webserver implementation I was adapting from the script provided by the python-telegram-bot team.

A working example

The following code shows a minimal example that uses FastAPI to build a python-telegram-bot v20 webhook. This bot will respond with “starting…” when it receives the /start command.

# main.py

from contextlib import asynccontextmanager
from http import HTTPStatus
from telegram import Update
from telegram.ext import Application, CommandHandler
from telegram.ext._contexttypes import ContextTypes
from fastapi import FastAPI, Request, Response

# Initialize python telegram bot
ptb = (
    Application.builder()
    .updater(None)
    .token(<your-bot-token>) # replace <your-bot-token>
    .read_timeout(7)
    .get_updates_read_timeout(42)
    .build()
)

@asynccontextmanager
async def lifespan(_: FastAPI):
    await ptb.bot.setWebhook(<your-webhook-url>) # replace <your-webhook-url>
    async with ptb:
        await ptb.start()
        yield
        await ptb.stop()

# Initialize FastAPI app (similar to Flask)
app = FastAPI(lifespan=lifespan)

@app.post("/")
async def process_update(request: Request):
    req = await request.json()
    update = Update.de_json(req, ptb.bot)
    await ptb.process_update(update)
    return Response(status_code=HTTPStatus.OK)

# Example handler
async def start(update, _: ContextTypes.DEFAULT_TYPE):
    """Send a message when the command /start is issued."""
    await update.message.reply_text("starting...")

ptb.add_handler(CommandHandler("start", start))

To start the bot, pip install all required dependencies and run the start command: gunicorn main:app -k uvicorn.workers.UvicornWorker.

This code snippet is adapted from a real Telegram bot in production. Check out the source code for @cron_telebot here to see how it is implemented. Feel free to adapt the script to suit your use case.

Conclusion

In this article, we learnt how to build and deploy a python-telegram-bot v20 webhook.

Hope this tutorial helped you. If you enjoyed this article, please follow me on Medium to show your support.

Thank you for reading!

By popular demand, we built a Discord bot that helps people track their progress in the challenge.

Today I am going to show you how to build your own 100 Days of Code bot.

Note that discord.js has released version 14, which includes breaking changes. For compatibility with this tutorial, you will want to ensure you are using discord.js 13 - you can install this with npm install discord.js@13. If you have any questions, feel free to join my discord server.

Create a Discord Bot Application

Your first step is to set up a Discord bot application. Head over to the Discord Developer Portal, sign in if needed, and select "Applications" from the sidebar.

Screenshot of the Developer Portal. If this is your first bot, you will not have any applications here.

Click the "New Application" button. Give it a name, and set it as a "Personal" application. You will now be taken to the application's settings. Here you can change the name, or give it an avatar.

Select "Bot" from the side bar, then click the "Add Bot" button. This will create a Discord Bot account for your application.

Screenshot of the Bot settings page. If you did not set an avatar, you will see a default based on your bot's name.

This is the screen where you will get the bot token. It is very important to keep this token secret, as the token allows your code to connect to your bot. Keep it safe and do not share it with anyone.

Now you need to add the bot to a server to interact with it. Click the "OAuth2" option on the sidebar, then select "URL Generator".

Under "Scopes", select bot and application.commands. The bot scope allows your bot account to join the server, and the application.commands scope allows you to update the slash commands (more on this later).

When you select bot, a new section for "Bot Permissions" will appear. Select the following permissions:

• Send Messages
• Embed Links
• Read Messages/View Channels

Screenshot of the OAuth screen with the required settings.

Copy the generated URL, and paste it into your browser. This will take you through Discord's process to add your new bot to a server.

Note that you must have the Manage Server permission in the server you want to add the bot to. If you do not have this permission, you can create a server to test your bot in.

Now you are ready to write some code!

Set Up Your Project

You will first need to set up the infrastructure and tooling for your project.

Ensure that you have Node.js version 16 and npm installed. Note that the packages you will use do not support earlier versions of Node.

Prepare the package.json

Create a directory, or folder, for your project. Open your terminal pointing to that new folder. Run the command npm init to set up your package.json file. For this tutorial, the default values are sufficient, but feel free to edit them as you wish.

You should end up with a package.json similar to this:

{
  "name": "100doc-tutorial",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

Now you need to make a couple of changes to get ready for the TypeScript implementation.

First, replace the main value of index.js with ./prod/index.js – you will be setting your TypeScript to compile to a prod directory.

Then remove the test script and add the following two scripts:

"build": "tsc",
"start": "node -r dotenv/config ./prod/index.js"

The build script will compile your TypeScript into JavaScript so Node can run it, and the start script will run the index.js entrypoint file.

Adding the -r dotenv/config here will dynamically import and run the config method in the dotenv package, which loads your environment variables from the .env file.

Speaking of packages, your next step is to install dependencies. Using npm install, install these dependencies:

• discord.js – this is the library that will handle connecting to the gateway and managing the Discord API calls.
• @discordjs/builders – the discord.js package for constructing application commands
• @discordjs/rest – a custom API client for interacting with the Discord REST API.
• discord-api-types – Type definitions and handlers for the Discord REST API.
• dotenv – a package that loads .env values into the Node process.
• mongoose – A wrapper for the MongoDB connection which offers tools for structuring your data.

Finally, install the development dependencies with npm install --save-dev. Development dependencies are packages that are required for working on your project in a development environment, but not required for running the codebase in production.

• typescript – This is the package for the TypeScript language, which includes everything needed to write code in TypeScript and compile it into JavaScript.
• @types/node – TypeScript relies on type definitions to understand the code you write. This package defines the types for the Node.js runtime environment, such as the process.env object.

With these packages installed, you should now have a package.json similar to this:

{
  "name": "100doc-tutorial",
  "version": "1.0.0",
  "description": "",
  "main": "./prod/index.js",
  "scripts": {
    "build": "tsc",
    "start": "node -r dotenv/config ./prod/index.js"
  },
  "author": "",
  "license": "ISC",
  "dependencies": {
    "@discordjs/builders": "^0.11.0",
    "@discordjs/rest": "^0.2.0-canary.0",
    "discord.js": "^13.6.0",
    "dotenv": "^14.2.0",
    "mongoose": "^6.1.7"
  },
  "devDependencies": {
    "@types/node": "^17.0.10",
    "typescript": "^4.5.4"
  }
}

Prepare TypeScript

TypeScript's compiler offers a number of different settings to maximise your control over the resulting JavaScript.

You can typically modify the compiler settings through a tsconfig.json file at the root of your project. You can generate the default boilerplate for this file with npx tsc --init, use an existing one if you set one up in another project, or even write one from scratch.

Because the compiler settings can significantly change the behaviour of TypeScript, it is best to use the same settings when following this tutorial. Here are the settings you should use:

{
  "compilerOptions": {
    "target": "ES6",
    "module": "CommonJS",
    "rootDir": "./src",
    "outDir": "./prod",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true
  }
}

The most important settings here are the rootDir and outDir settings. These tell the compiler that all of your code will be in the src directory, and the resulting JavaScript should go in the prod directory.

If you would like to test your settings, create a src directory and place an index.ts file inside. Write some code (such as a console.log statement) and run npm run build in your terminal. You should see a prod directory get created, with an index.js containing your compiled code.

Additional Setup Notes

If you are using git as a version control, you want to avoid pushing secrets and unnecessary code to your repository. Create a .gitignore file in your root project directory, and add the following content:

/node_modules/
/prod/
.env

The .gitignore file tells git not to track files/folders that match the patterns you enter. Ignoring the node_modules folder keeps your repository from becoming bloated.

Pushing the compiled JavaScript is also unnecessary, as your project is typically compiled in production before runtime. .env files contain secret values, such as API keys and tokens, so they should not be committed to a repository.

Create the Discord Bot

Your next step is to prepare the initial bot connection. If you did not do so earlier, create a src directory and an index.ts file within.

Start with an anonymous immediately-invoked function expression (IIFE) to allow for top-level await use:

(async () => {

})();

Within this function you are going to instantiate your Discord bot. At the top of the file, import the Client class with import { Client } from "discord.js";. The Client class represents your Discord bot's session.

Inside your function, construct a new Client instance and assign it to a BOT variable with const BOT = new Client();. Now the BOT variable will represent your bot.

To connect your bot to the Discord gateway and begin receiving events, you will need to use the .login() method on your bot instance. The .login() method takes a single argument, which is the token for the bot application you created earlier.

Many of the methods in discord.js are asynchronous, so you will need to use await here. Add the line await BOT.login(process.env.BOT_TOKEN); to your IIFE.

Your index.ts file should now look like this:

import { Client } from "discord.js";

(async () => {
  const BOT = new Client();

  await BOT.login(process.env.BOT_TOKEN);
})();

If you try to run npm run build, you will see an error: An argument for 'options' was not provided.

In discord.js 13, you are required to specify Gateway Intents when you instantiate your bot. Gateway Intents tell Discord what events your bot should receive.

In your src folder, create a config folder - then in config, create an IntentOptions.ts file.

Within that new file, add the line export const IntentOptions = ["GUILDS"]. This will tell Discord your bot should receive the Guild events.

Then, back in your index.ts file, add an argument to your new Client() call: new Client({intents: IntentOptions}). You'll need to import it at the top of your file with import { IntentOptions } from "./config/IntentOptions;.

It seems you still have an error: Type 'string' is not assignable to type 'number |${bigint}| IntentsString | Readonly<BitField<IntentsString, number>> | RecursiveReadonlyArray<number |${bigint}| IntentsString | Readonly<...>>'.

TypeScript is inferring your IntentOptions array as a string, but the Client constructor is expecting more specific types.

Head back to your config/IntentOptions.ts file and add another import: import { IntentsString } from "discord.js". Then update your variable with the new type definition: export const IntentOptions: IntentsString[] = ["GUILDS"];.

Now npm run build should be successful. If you have added your new bot to a Discord server, running npm start will show your bot come online in that server. However, the bot is not going to respond to anything yet, because you have not started listening to events.

Gateway Events in Discord

Gateway "events" are generated when an action happens on Discord, and are typically sent to clients (including your bot) as JSON payloads. You can listen to those events with the .on() method, allowing you to write logic for your bot to follow when specific events occur.

The first event to listen to is the "ready" event. This event fires when your bot has connected to the gateway and is ready to process events. Above your .login() call, add BOT.on("ready", () => console.log("Connected to Discord!"));.

For your changes to take effect, use npm run build again to compile the new code. Now if you try npm run start, you should see "Connected to Discord!" print in your terminal.

Connect to the Database

You'll be using the mongoose package to connect to a MongoDB instance. If you prefer, you can run MongoDB locally, or you can use the MongoDB Atlas free tier for a cloud-based solution.

If you do not have a MongoDB Atlas account, freeCodeCamp has a great tutorial on setting one up.

Grab your connection string for your database and add it to your .env file as MONGO_URI="", with the connection string going between the quotes. For the database name, use oneHundredDays.

Create a directory called database to hold the files that contain your database logic. Within that directory, create a file called connectDatabase.ts. You will be writing your logic to initiate the database connection here.

Start with an exported function declaration:

export const connectDatabase = async () => {

}

mongoose offers a connect method for connecting to the database. Import it with import { connect } from "mongoose"; at the top of your file.

Then use the method inside your function with await connect(process.env.MONGO_URI);. Add a console.log statement after that so you can identify that your bot has connected to the database.

Your connectDatabase.ts file should now look something like this:

import { connect } from "mongoose";

export const connectDatabase = async () => {
    await connect(process.env.MONGO_URI);
    console.log("Database Connected!")
}

Now, within your index.ts file, import this function with import { connectDatabase } from "./database/connectDatabase" and add await connectDatabase() to your IIFE, just before the .login() method. Go ahead and run npm run build again.

A compiler error, indicating that: Argument of type string or undefined is not assignable to parameter of type string.

Oh no – an error!

Environment Variable Validation

The problem with environment variables is that they can all be undefined. This often happens if you make a typo in your environment variable name, or mix the name up with another name (a mistake I made when writing this tutorial, using TOKEN instead of BOT_TOKEN in some places).

TypeScript is warning you that the connect method takes a string, and that an undefined value will break things. You can fix this, but first you will want to write a function to handle validating your environment variables.

Within your src directory, create a utils directory to contain your utility functions. Add a validateEnv.ts file there.

Create a function in the file called validateEnv. This function will be synchronous and does not need the async keyword. Within that function, add conditions to check for your two environment variables. If either one is missing, return false. Otherwise, return true.

Your code might look something like this:

export const validateEnv = () => {
  if (!process.env.BOT_TOKEN) {
    console.warn("Missing Discord bot token.");
    return false;
  }

  if (!process.env.MONGO_URI) {
    console.warn("Missing MongoDB connection.");
    return false;
  }
  return true;
};

Head back to your index.ts file and import this validation function with import { validateEnv } from "./utils/validateEnv". Then at the beginning of your IIFE, use an if statement to return early if the function returns false. Your index.ts should look like:

import { Client } from "discord.js";
import { connectDatabase } from "./database/connectDatabase";
import { validateEnv } from "./utils/validateEnv";

(async () => {
  if (!validateEnv()) return;

  const BOT = new Client();

  BOT.on("ready", () => console.log("Connected to Discord!"));

  await connectDatabase();

  await BOT.login(process.env.BOT_TOKEN);
})();

If you try npm run build again, you will see the same error message as before. This is because while we know the environment variable exists, TypeScript still cannot infer it. The validation function is set up to exit the process if the environment variable is missing, so we are going to tell TypeScript that it is definitely a string.

Back in your connectDatabase.ts file, within the connect function use process.env.MONGO_URI as string to coerce the type into string. The error should go away, and you can now run npm run build and npm start.

You should see the messages you wrote for both the Discord and MongoDB connections print in your terminal.

The "interaction" Event

While you are making great progress on your bot, it still does not do anything. In order to receive commands, you will need to create another event listener.

Discord rolled out slash commands, featuring a new UI and a new gateway event. The interactionCreate event is triggered when someone uses a slash command with your bot. This is the event you will want to listen to. Because the logic is a bit more complicated than the ready event, you will want to create a separate file.

Within your src directory, create an events directory, and an onInteraction.ts file in there. Start by defining an exported function onInteraction. This should be an asynchronous function, with a single parameter called interaction.

export const onInteraction = async (interaction) => {

};

To provide a type definition for your parameter, import the Interaction type from discord.js.

import { Interaction } from "discord.js";

export const onInteraction = async (interaction: Interaction) => {

};

The interaction event actually triggers on any command interaction, which includes things like button clicks and select menus, as well as the slash commands we want.

Because you will only be writing slash commands for this bot, you can filter out any other interaction type and help TypeScript understand the data you are working with.

In your new function, add a condition to check interaction.isCommand(). You will be writing logic within this block later.

import { Interaction } from "discord.js";

export const onInteraction = async (interaction: Interaction) => {
  if (interaction.isCommand()) {
  }
};

Now, back in your index.ts file, you can mount another listener. Next to your .on("ready") listener, add a BOT.on("interactionCreate") listener. For this event, the callback takes an interaction argument which you can pass to your new onInteraction function.

  BOT.on(
    "interactionCreate",
    async (interaction) => await onInteraction(interaction)
  );

Great! You can run npm run build to confirm that TypeScript doesn't throw any errors, but without actual commands to use you can't quite test this code yet.

Prepare for Commands

I maintain a few Discord bots, and one thing I've discovered that helps keep code maintainable and readable is making the components modular.

Define an Interface

You will first need to define a common structure for your commands. Create an interfaces folder in src. Then inside interfaces create a file called Command.ts.

Now you are going to create an interface. In TypeScript, an interface is often used to define the structure of an object, and is one of many tools available for declaring a variable's type.

In your Command.ts file, create an exported interface called Command:

export interface Command {

}

Your interface will have two properties – data, which will hold the command data to send to Discord, and run, which will hold the callback function and command logic.

For the data property, import SlashCommandBuilder and SlashCommandSubcommandsOnlyBuilder from @discordjs/builders. Define the data property as either one of those two types.

For the run property, import the CommandInteraction type from discord.js. Define run as a function which takes a CommandInteraction typed parameter and returns a void Promise.

import {
  SlashCommandBuilder,
  SlashCommandSubcommandsOnlyBuilder,
} from "@discordjs/builders";
import { CommandInteraction } from "discord.js";

export interface CommandInt {
  data: SlashCommandBuilder | SlashCommandSubcommandsOnlyBuilder;
  run: (interaction: CommandInteraction) => Promise<void>;
}

Create a Command List

Next you need a place to store all of your commands. Create a folder called commands in the src directory, and add a file called _CommandList.ts. The underscore here will keep this file at the top of the list.

The _CommandList.ts file will need two lines. First, import your Command interface, then declare a CommandList array. The array will be empty for now, but give it a Command[] type so TypeScript knows it will eventually hold your command objects. The file should look like:

import { Command } from "../interfaces/Command";

export const CommandList: Command[] = [];

The purpose of this file is to create an array of your bot's commands which you will iterate over in the interaction event listener. There are ways to automate this, but they tend to be unnecessarily complex for smaller bots.

Check for Commands

Back in your onInteraction.ts file, you should start working on the logic for finding and running a command.

In your interaction.isCommand() condition block, loop through the CommandList array (remember to import it!) with a for...of loop.

for (const Command of CommandList) {

}

The interaction payload received from Discord includes a commandName property, which you can use to find the command that a user has selected. To check this, compare interaction.commandName with the Command.data.name property.

if (interaction.commandName === Command.data.name) {

}

Now, if you have found the command the user has chosen, you need to run the logic for that command. This is achieved with a Command.run(interaction) call – passing the interaction payload into the command.

Your final file should look like this:

import { Interaction } from "discord.js";
import { CommandList } from "../commands/_CommandList";

export const onInteraction = async (interaction: Interaction) => {
  if (interaction.isCommand()) {
    for (const Command of CommandList) {
      if (interaction.commandName === Command.data.name) {
        await Command.run(interaction);
        break;
      }
    }
  }
};

Database Model

There's one more step before you are ready to start writing commands. This bot will track your community members' 100 Days of Code progress. And you need to store that progress in the database.

mongoose helps structure your MongoDB records to prevent you from passing malformed or incomplete data into your database.

Start by creating a models folder in your database directory. In that models folder, create a CamperModel.ts file. This will be your structure for the user objects.

You first need to import the necessary values from the mongoose library. Add import { Document, model, Schema } from "mongoose"; at the top of the file.

Because you are using TypeScript, you need to create a type definition for your database objects. Create another interface, like you did for your commands, named CamperInt.

export interface CamperInt extends Document {

}

Your database model will have four properties. Add these to your interface:

• discordId: string; – Every user object in Discord has a unique identifier, called a Snowflake, which is used to distinguish them from other users. Unlike a username or discriminator (the four digit number after the username), the id value cannot be changed. This makes it the ideal value for linking your stored data to a Discord user.
• round: number; – This will represent the "round" the user is on in the challenge. When someone completes 100 days of the challenge, they may choose to undertake the challenge again. When they do, they often refer to it as "round 2", for example.
• day: number; – This represents the day the user is on in the challenge.
• timestamp: number; – You will use this value to track when the user last submitted a 100 Days of Code post.

Great! Now you need to define the Schema for your database entries. mongoose uses a Schema object to define the shape of the documents that go in to your database collection. The Schema import has a constructor, which you will assign to a variable.

export const Camper = new Schema();

This constructor takes an object as its argument, and that object defines the database keys and types. Go ahead and pass in an object similar to what your interface looks like.

export const Camper = new Schema({
    discordId: String,
    round: Number,
    day: Number,
    timestamp: Number,
})

Next you need to create the model. In mongoose, the model object serves to create, read, and update your documents in the MongoDB database. Add export default model(); at the bottom of your file.

The model function takes a few parameters. The first is a string, and is the name to use for the documents in your database. For this collection, use "camper". The second argument is the schema to use for the data – use your Camper schema there.

By default, mongoose will use the plural version of your model name for the collection. In our case, that would be "campers". If you want to change that, you can pass in a third argument of { collection: "name" } to set the collection to name.

If you were using JavaScript, this would be enough to get your database model set up. However, because you are using TypeScript, you should take advantage of the type safety. model() by default returns a Document type of any.

To resolve this, you can pass a generic type into the model function. Generic types serve as variables for type definitions, in a sense. You need to set the generic type for your model to use your interface. Add the generic type by changing model to model<CamperInt>.

Just one more step here. Your CamperInt interface only defines the properties you set in the MongoDB document, but doesn't include the standard properties.

Change your export interface CamperInt to export interface CamperInt extends Document. This tells TypeScript that your type definition is an extension of the existing Document type definition – you are essentially adding properties to that structure.

Your final file should look like this:

import { Document, model, Schema } from "mongoose";

export interface CamperInt {
  discordId: string;
  round: number;
  day: number;
  timestamp: number;
}

export const Camper = new Schema({
  discordId: String,
  round: Number,
  day: Number,
  timestamp: Number,
});

export default model<CamperInt>("camper", Camper);

As a safety check, use npm run build again. You should not see any errors in the terminal.

Write Bot Commands

You are finally ready to start writing some commands! As this is a 100 Days of Code bot, you should start with the command for creating a 100 Days of Code update.

100 Command

Within your commands folder, create a oneHundred.ts file. This will hold your 100 Days of Code command. Import your command interface with import { Command } from "../interfaces/Command;.

Now declare an exported variable oneHundred and give it the Command type:

import { Command } from "../interfaces/Command";

export const oneHundred: Command = {

};

First, create the data property. You will be using the @discordjs/builders package to build a slash command.

Start by importing the SlashCommandBuilder() from the @discordjs/builders package. Then, construct a new instance in the data property with new SlashCommandBuilder(). You're going to chain some methods here to pass the information you want into the builder.

The .setName() method allows you to set the name of your slash command. Set the name to "100". The setDescription() option allows you to display a description of the command in Discord's UI. Set the description to "Check in for the 100 Days of Code challenge.".

Slash commands can also accept option values. These are used to take arguments from the user, and come in various types. For this command, you'll want a string option with the addStringOption() method. Option methods take a callback function, with an option parameter.

You can then chain methods on the option parameter to configure the information for the argument. Use the .setName() method to give the option a name of "message", and the .setDescription() method to give it a description of "The message to go in your 100 Days of Code update.". Finally, use the .setRequired() method to set the option to be required.

Here's what you should have now:

import { SlashCommandBuilder } from "@discordjs/builders";
import { Command } from "../interfaces/Command";

export const oneHundred: Command = {
  data: new SlashCommandBuilder()
    .setName("100")
    .setDescription("Check in for the 100 Days of Code challenge.")
    .addStringOption((option) =>
      option
        .setName("message")
        .setDescription("The message to go in your 100 Days of Code update.")
        .setRequired(true)
    ),
};

If you are coding in an IDE with Intellisense enabled, you may have noticed that this will throw a type error on the data property. This is because the SlashCommandBuilder actually returns an Omit type! An Omit type is used to tell TypeScript that the type is almost the same as another type, but with specific properties removed.

Head over to your interfaces/Command.ts file to update the type. Replace the SlashCommandBuilder type with Omit<SlashCommandBuilder, "addSubcommandGroup" | "addSubcommand">. This will tell TypeScript that data should be a SlashCommandBuilder, but without those two specific properties.

import {
  SlashCommandBuilder,
  SlashCommandSubcommandsOnlyBuilder,
} from "@discordjs/builders";
import { CommandInteraction } from "discord.js";

export interface Command {
  data:
    | Omit<SlashCommandBuilder, "addSubcommandGroup" | "addSubcommand">
    | SlashCommandSubcommandsOnlyBuilder;
  run: (interaction: CommandInteraction) => Promise<void>;
}

Great! Now that your type error is resolved, head back over to your oneHundred.ts command file – it is time to write the command logic.

All of your bot's logic for responding to the command will go in the run property. As you did in your interface, start by creating an async function which takes an interaction argument. Then, let the first line of your function be await interaction.deferReply();.

Discord expects a bot to respond to a command within three seconds. Because this command may take longer to process, using the .deferReply() method sends an acknowledgement response that gives you a full 15 minutes to send the actual response.

Next, you need to extract some data from the command. First, destructure the user object out of the interaction payload with const { user } = interaction;. The user object represents the Discord user that called the command.

Then get the message option you sent with const text = interaction.options.getString("message", true);. With this line, you are accessing the options property of the interaction. The .getString() method specifically grabs a string option (remember that you created the option in data), and "message" is the name of the option. The true argument indicates that this is a required option, so TypeScript won't consider it nullable.

Your file should look like this:

import { SlashCommandBuilder } from "@discordjs/builders";
import { Command } from "../interfaces/Command";

export const oneHundred: Command = {
  data: new SlashCommandBuilder()
    .setName("100")
    .setDescription("Check in for the 100 Days of Code challenge.")
    .addStringOption((option) =>
      option
        .setName("message")
        .setDescription("The message to go in your 100 Days of Code update.")
        .setRequired(true)
    ),
  run: async (interaction) => {
    await interaction.deferReply();
    const { user } = interaction;
    const text = interaction.options.getString("message", true);
  },
};

The next step in this command would be to fetch data from your database. Because many of your commands will need to do this, you should create a module for it.

Handling the Database Logic

Create a src/modules directory, and add a getCamperData.ts file within. Create an exported async function named getCamperData, and give it a string parameter named id. Then, within the function, you can query the database.

Import your CamperModel from the database directory, and use the findOne() method to query by the camper's id: const camperData = await CamperModel.findOne({ discordId: id });.

import CamperModel from "../database/models/CamperModel";

export const getCamperData = async (id: string) => {
  const camperData = await CamperModel.findOne({ id });
};

We still have one more step here. If the camper has not used the bot before, they won't have an existing database record. findOne() would return null in this case – so you can add a fallback value.

import CamperModel from "../database/models/CamperModel";

export const getCamperData = async (id: string) => {
  const camperData =
    (await CamperModel.findOne({ discordId: id })) ||
    (await CamperModel.create({
      discordId: id,
      round: 1,
      day: 0,
      date: Date.now(),
    }));
};

Finally, you need to return your data. Add return camperData at the end of the function. For extra type safety, define the return type of your function as Promise<CamperData>.

import CamperModel, { CamperInt } from "../database/models/CamperModel";

export const getCamperData = async (id: string): Promise<CamperInt> => {
  const camperData =
    (await CamperModel.findOne({ discordId: id })) ||
    (await CamperModel.create({
      discordId: id,
      round: 1,
      day: 0,
      date: Date.now(),
    }));
  return camperData;
};

You now have a way to get camper data from the database, but you need a way to update it as well. Create another file in your /src/modules directory called updateCamperData.ts. This will handle the logic to increment a camper's progress.

Start with an exported async function called updateCamperData. It should take a Camper parameter, which would be the data you fetch from MongoDB.

import { CamperInt } from "../database/models/CamperModel";

export const updateCamperData = async (Camper: CamperInt) => {

};

The only time you will update data is within the /100 command – where you'll want to increment the camper's day count, check if they have started a new round, and update the timestamp.

First, increment the day count with Camper.day++;. With the way the 100 Days of Code challenge works, if a camper has passed day 100 then they have started a new "round". You'll need a condition to check if Camper.day > 100, and if so, reset the day to 1 and increment the round.

After that condition, update the timestamp with Camper.timestamp = Date.now(); and save the data with await Camper.save();. Finally, return the modified data object so you can use it in the command.

Your final file should look like:

import { CamperInt } from "../database/models/CamperModel";

export const updateCamperData = async (Camper: CamperInt) => {
  Camper.day++;
  if (Camper.day > 100) {
    Camper.day = 1;
    Camper.round++;
  }
  Camper.timestamp = Date.now();
  await Camper.save();
  return Camper;
};

100 Command Continued

Now that your database logic is ready, return to your oneHundred.ts file. As a reminder, that file should look like this:

import { SlashCommandBuilder } from "@discordjs/builders";
import { Command } from "../interfaces/Command";

export const oneHundred: Command = {
  data: new SlashCommandBuilder()
    .setName("100")
    .setDescription("Check in for the 100 Days of Code challenge.")
    .addStringOption((option) =>
      option
        .setName("message")
        .setDescription("The message to go in your 100 Days of Code update.")
        .setRequired(true)
    ),
  run: async (interaction) => {
    await interaction.deferReply();
    const { user } = interaction;
    const text = interaction.options.getString("message", true);
  },
};

Import your two new modules at the top of the file. Then, after your logic that extracts the values from the interaction object, fetch the camper's data from the database with const targetCamper = await getCamperData(user.id);. Update the data with const updatedCamper = await updateCamperData(targetCamper);.

import { SlashCommandBuilder } from "@discordjs/builders";
import { Command } from "../interfaces/Command";
import { getCamperData } from "../modules/getCamperData";
import { updateCamperData } from "../modules/updateCamperData";

export const oneHundred: Command = {
  data: new SlashCommandBuilder()
    .setName("100")
    .setDescription("Check in for the 100 Days of Code challenge.")
    .addStringOption((option) =>
      option
        .setName("message")
        .setDescription("The message to go in your 100 Days of Code update.")
        .setRequired(true)
    ),
  run: async (interaction) => {
    await interaction.deferReply();
    const { user } = interaction;
    const text = interaction.options.getString("message", true);

    const targetCamper = await getCamperData(user.id);
    const updatedCamper = await updateCamperData(targetCamper);
  },
};

Now you need to construct the response to send back to the camper when they use the command.

For this, you'll be using Discord's message embed feature. Start by importing the MessageEmbed constructor from discord.js, and creating a new embed with const oneHundredEmbed = new MessageEmbed();. The MessageEmbed class has a few methods to use for building the content of the embed.

Use the .setTitle() method to set the title of the embed to "100 Days of Code".

Use the .setDescription() method to set the description of the embed to the message the camper provided in the command (remember that you extracted this to the text variable earlier). The author of the embed can be set, and will display at the top of the embed.

Use the .setAuthor() method to pass an object with a name property set to user.tag (which will display the camper's username and discriminator, like nhcarrigan#0001), and an iconURL property set to user.displayAvatarUrl() (which will attach the camper's avatar to the embed).

Embeds also accept fields, which are smaller blocks of text that have their own title and description. The .addField() method takes two or three arguments, the first being the field title, the second being the field description, and the third being an optional boolean to set the field as inline.

Use the .addField() method to add two fields. The first should have the title set to "Round" and the description set to updatedCamper.round.toString(). The second should have the title set to "Day" and the description set to updatedCamper.day.toString(). Both fields should be inline.

For the last part of your embed, use the .setFooter() method to add small footer text. Pass an object with a text property set to "Day completed: " + new Date(updatedCamer.timestamp).toLocaleDateString() to show the time the camper reported their progress.

Finally, you need to send this new embed back to the camper. Because you have already sent a response with the interaction.deferReply() call, you cannot send another response. Instead, you need to edit the one you sent.

Use await interaction.editReply() to edit the response. The .editReply() method takes an object with various properties – in this case, you are sending an embed. Pass an object with an embeds property set to [oneHundredEmbed].

Note that this is an array containing your embed. Discord messages can contain up to 10 embeds, and the API expects an array of embed objects to match.

Your final command file should look like this:

import { SlashCommandBuilder } from "@discordjs/builders";
import { MessageEmbed } from "discord.js";
import { Command } from "../interfaces/Command";
import { getCamperData } from "../modules/getCamperData";
import { updateCamperData } from "../modules/updateCamperData";

export const oneHundred: Command = {
  data: new SlashCommandBuilder()
    .setName("100")
    .setDescription("Check in for the 100 Days of Code challenge.")
    .addStringOption((option) =>
      option
        .setName("message")
        .setDescription("The message to go in your 100 Days of Code update.")
        .setRequired(true)
    ),
  run: async (interaction) => {
    await interaction.deferReply();
    const { user } = interaction;
    const text = interaction.options.getString("message", true);

    const targetCamper = await getCamperData(user.id);
    const updatedCamper = await updateCamperData(targetCamper);

    const oneHundredEmbed = new MessageEmbed();
    oneHundredEmbed.setTitle("100 Days of Code");
    oneHundredEmbed.setDescription(text);
    oneHundredEmbed.setAuthor({
      name: user.tag,
      iconURL: user.displayAvatarURL(),
    });
    oneHundredEmbed.addField("Round", updatedCamper.round.toString(), true);
    oneHundredEmbed.addField("Day", updatedCamper.day.toString(), true);
    oneHundredEmbed.setFooter({
      text:
        "Day completed: " +
        new Date(updatedCamper.timestamp).toLocaleDateString(),
    });

    await interaction.editReply({ embeds: [oneHundredEmbed] });
  },
};

Registering Commands

If you run npm run build and npm start, everything starts up – but you have no way to actually use your new command. This is because Discord requires that commands be registered so they are made available in the application UI. There are a few steps we'll need to take to do this.

First, head over to your _CommandList.ts file and import your oneHundred command. Add this to your CommandList array so it's available elsewhere.

import { Command } from "../interfaces/Command";
import { oneHundred } from "./oneHundred";

export const CommandList: Command[] = [oneHundred];

Now it is time to add the logic to send the command information to Discord. In your src/events directory, add an onReady.ts file. We'll be using this with the "ready" event.

Create an exported async function named onReady, and give it a single parameter called BOT. Import the Client type from discord.js and set the BOT typedef to Client.

import { Client } from "discord.js";

export const onReady = async (BOT: Client) => {};

Now import the REST module from @discordjs/rest. This will allow you to instantiate an API client, which you'll use to send the commands. Construct a new instance with const rest = new REST();.

There are a couple of things you'll need to configure with your REST client. First, pass an object into the REST() constructor with a version property set to "9". This tells the client to use version 9 of Discord's API, which is currently the latest version.

Then, chain a .setToken() call on the constructor to set the API token to process.env.BOT_TOKEN – you'll have to coerce this to a string.

import { REST } from "@discordjs/rest";
import { Client } from "discord.js";

export const onReady = async (BOT: Client) => {
  const rest = new REST({ version: "9" }).setToken(
    process.env.BOT_TOKEN as string
  );
};

The API expects command data to be sent in a specific JSON format, but thankfully the slash command builder we are using has a method just for that. Import your CommandList, then create a new array and map your command data.

const commandData = CommandList.map((command) => command.data.toJSON());

Before you send the commands to Discord, it's important to note that there are two types of commands. "Global Commands" are available everywhere your bot is used, but take about an hour to update. "Guild Commands" are available only in a single server, but update immediately. Because this bot is designed to run in a single server, we're going to use guild commands.

You'll need to get the ID of the server you are using the bot in. To do this, make sure you have enabled developer mode in your Discord application, then right click on your server icon and select "Copy ID". In your .env file, add a GUILD_ID variable and assign it the ID you copied. It should look something like GUILD_ID="778130114772598785".

Back in your onReady.ts file, start your API call with await rest.put(). Sending a PUT request will update any existing commands, where a POST will attempt to create new commands and error if commands share a name. Import Routes from discord-api-types/v9, and within the rest.put() call pass a Routes.applicationGuildCommands() call. This will be used to construct the API endpoint to send the commands to.

The applicationGuildCommands() call will take two arguments.

The first is the application ID to associate the commands with. You can get this from the BOT.user.id value – but user is potentially undefined, so you'll need to optionally chain it. Use BOT.user?.id || "missing id" to add a fallback value that will error out – this will allow us to know if the bot's ID is missing.

The second argument is the server ID, which you set up as process.env.GUILD_ID (remember to coerce the type!).

The .put() call needs a second argument as well, which is the data you want to send. Pass this as { body: commandData } to match the expected format.

Finally, add a console.log("Discord ready!") at the end of the file to indicate your bot is online.

import { REST } from "@discordjs/rest";
import { Routes } from "discord-api-types/v9";
import { Client } from "discord.js";
import { CommandList } from "../commands/_CommandList";

export const onReady = async (BOT: Client) => {
  const rest = new REST({ version: "9" }).setToken(
    process.env.BOT_TOKEN as string
  );

  const commandData = CommandList.map((command) => command.data.toJSON());

  await rest.put(
    Routes.applicationGuildCommands(
      BOT.user?.id || "missing id",
      process.env.GUILD_ID as string
    ),
    { body: commandData }
  );

  console.log("Discord ready!");
};

Switch to your index.ts file and locate your "ready" event listener. Replace the console.log call with your new onReady function – remember to import it, and make the callback asynchronous.

import { Client } from "discord.js";
import { IntentOptions } from "./config/IntentOptions";
import { connectDatabase } from "./database/connectDatabase";
import { onInteraction } from "./events/onInteraction";
import { onReady } from "./events/onReady";
import { validateEnv } from "./utils/validateEnv";

(async () => {
  if (!validateEnv()) return;
  const BOT = new Client({ intents: IntentOptions });

  BOT.on("ready", async () => await onReady(BOT));

  BOT.on(
    "interactionCreate",
    async (interaction) => await onInteraction(interaction)
  );

  await connectDatabase();

  await BOT.login(process.env.BOT_TOKEN);
})();

Now run npm run build and npm start, and head to your server in Discord. If you type / you should see your new /100 command show up. Try using the command and checking the response.

If you see this response, then you've successfully created your first command!

Congratulations! You have your first successful command. With all of the infrastructure you've built, adding additional commands will be much smoother. Let's go ahead and do that now.

Edit Command

What happens if a camper makes a typo in their /100 message? Because the bot sends the response, the camper cannot edit it (Discord does not allow you to edit messages you did not send). You should create a command that will allow a camper to do this.

Create an edit.ts file in your src/commands directory. Like you did with the /100 command, import your SlashCommandBuilder and Command interface, and export an edit object with the Command type.

Use the SlashCommandBuilder to prepare the data property. Give the command the name edit and the description Edit a previous 100 days of code post., then add two string options. The first string option should have a name embed-id and a description of ID of the message to edit., and the second should have a name of message and a description of The message to go in your 100 Days of Code update.. Both options should be required.

Your code should look like this:

import { SlashCommandBuilder } from "@discordjs/builders";
import { Command } from "../interfaces/Command";

export const edit: Command = {
    data: new SlashCommandBuilder()
    .setName("edit")
    .setDescription("Edit a previous 100 days of code post.")
    .addStringOption((option) =>
      option
        .setName("embed-id")
        .setDescription("ID of the message to edit.")
        .setRequired(true)
    )
    .addStringOption((option) =>
      option
        .setName("message")
        .setDescription("The message to go in your 100 Days of Code update.")
        .setRequired(true)
    ),
}

Create your run property with an async function and an interaction parameter. Destructure the channel and user from the interaction, and grab the embed-id and message options. Don't forget to defer the response!

    run: async (interaction) => {
        await interaction.deferReply();
        const { channel, user } = interaction;
        const targetId = interaction.options.getString("embed-id", true);
        const text = interaction.options.getString("message", true);
    }

The channel property is nullable (in cases where an interaction is sent via a DM, for example), so you'll want to check that it exists. If it does not, respond with a message that the command is missing parameters.

    if (!channel) {
      await interaction.editReply({
        content: "Missing channel parameter.",
      });
      return;
    }

Now that you know the channel exists, you can fetch the message that the camper wants to edit based on the ID they provided. Use channel.messages.fetch() to do this, passing in the targetId as the argument.

Because it is possible that the target message does not exist, you need to account for that in your code. Add a condition that checks for this, and if the message is not found respond with an explanation.

    const targetMessage = await channel.messages.fetch(targetId);

    if (!targetMessage) {
      await interaction.editReply({
        content:
          "That does not appear to be a valid message ID. Be sure that you are using this command in the same channel as the message.",
      });
      return;
    }

The last thing you need to check is that the message the camper is editing actually belongs to them. You can access the embed with the .embeds property – much like how you sent it, the property is returned as an array of embed objects.

Grab the first embed from the array, and then check that the embed author matches the user's tag. If not, let them know they cannot edit this post.

    const targetEmbed = targetMessage.embeds[0];

    if (targetEmbed.author?.name !== user.tag) {
        await interaction.editReply({
            content: "This does not appear to be your 100 Days of Code post. You cannot edit it."
        })
    }

Now that you have confirmed everything is correct, you can use .setDescription() on the embed to update the text. Then, edit the message with the new embed, and respond to the interaction with a confirmation.

Your full code should look like this:

import { SlashCommandBuilder } from "@discordjs/builders";
import { Command } from "../interfaces/Command";

export const edit: Command = {
  data: new SlashCommandBuilder()
    .setName("edit")
    .setDescription("Edit a previous 100 days of code post.")
    .addStringOption((option) =>
      option
        .setName("embed-id")
        .setDescription("ID of the message to edit.")
        .setRequired(true)
    )
    .addStringOption((option) =>
      option
        .setName("message")
        .setDescription("The message to go in your 100 Days of Code update.")
        .setRequired(true)
    ),
  run: async (interaction) => {
    await interaction.deferReply();
    const { channel, user } = interaction;
    const targetId = interaction.options.getString("embed-id", true);
    const text = interaction.options.getString("message", true);

    if (!channel) {
      await interaction.editReply({
        content: "Missing channel parameter.",
      });
      return;
    }

    const targetMessage = await channel.messages.fetch(targetId);

    if (!targetMessage) {
      await interaction.editReply({
        content:
          "That does not appear to be a valid message ID. Be sure that you are using this command in the same channel as the message.",
      });
      return;
    }

    const targetEmbed = targetMessage.embeds[0];

    if (targetEmbed.author?.name !== user.tag) {
      await interaction.editReply({
        content:
          "This does not appear to be your 100 Days of Code post. You cannot edit it.",
      });
    }

    targetEmbed.setDescription(text);
    await targetMessage.edit({ embeds: [targetEmbed] });
    await interaction.editReply({ content: "Updated!" });
  },
};

Add your new edit command to your CommandList array, then build and run your bot and you should see the new command. Try editing the embed you sent earlier.

You should see your embed update, and a confirmation from the bot!

View Command

Campers should have a way to view their current progress, so we'll need to create a command to do so. By now, you should be comfortable with the command structure – we encourage you to follow these instructions but attempt to write the code without looking at the final result.

Create a view.ts file in your commands directory, and set up your command variable. Create the data property with a command that has the name view and the description Shows your latest 100 days of code check in. This command does not need any options.

Set up your async function in the run property, and defer the interaction response. Extract the user object from the interaction. Use your getCamperData module to fetch the camper's data from the database. Then, check if the data's day property has a non-zero value. If it does not, let the camper know that they have not started the 100 Days of Code challenge, and can do so with the /100 command.

Create an embed with a title set to My 100DoC Progress. Set the description to Here is my 100 Days of Code progress. I last reported an update on: and add the camper's timestamp. Add a Round and Day field, and set the author for the embed. Then send the embed in the interaction response.

Remember to add your new command to the CommandList, then try building and starting your bot. You should see the command available, and be able to get a response from it.

If you did not get the response, here is what your code should look like.

import { SlashCommandBuilder } from "@discordjs/builders";
import { MessageEmbed } from "discord.js";
import { Command } from "../interfaces/Command";
import { getCamperData } from "../modules/getCamperData";

export const view: Command = {
  data: new SlashCommandBuilder()
    .setName("view")
    .setDescription("Shows your latest 100 Days of Code check in."),
  run: async (interaction) => {
    await interaction.deferReply();
    const { user } = interaction;
    const targetCamper = await getCamperData(user.id);

    if (!targetCamper.day) {
      await interaction.editReply({
        content:
          "It looks like you have not started the 100 Days of Code challenge yet. Use `/100` and add your message to report your first day!",
      });
      return;
    }

    const camperEmbed = new MessageEmbed();
    camperEmbed.setTitle("My 100DoC Progress");
    camperEmbed.setDescription(
      `Here is my 100 Days of Code progress. I last reported an update on ${new Date(
        targetCamper.timestamp
      ).toLocaleDateString()}.`
    );
    camperEmbed.addField("Round", targetCamper.round.toString(), true);
    camperEmbed.addField("Day", targetCamper.day.toString(), true);
    camperEmbed.setAuthor({
      name: user.tag,
      iconURL: user.displayAvatarURL(),
    });

    await interaction.editReply({ embeds: [camperEmbed] });
  },
};

Help Command

The last thing you need to build is a help command, which will explain how campers can interact with the bot.

Create your help.ts file in the command directory, and create your data property. Give the command the name help and the description Provides information on using this bot.

Set up your run property with the async function, and remember to defer the reply. Create an embed, and use the description and fields to provide the information you would like to share with your campers. Send the embed in the interaction response.

Load your new help command into the CommandList, and build + start your bot to test it. You should see a response with the embed you created.

Your embed might look different, depending on what information you chose to share. Here's the code that we used for the above embed:

import { SlashCommandBuilder } from "@discordjs/builders";
import { MessageEmbed } from "discord.js";
import { Command } from "../interfaces/Command";

export const help: Command = {
  data: new SlashCommandBuilder()
    .setName("help")
    .setDescription("Provides information on using this bot."),
  run: async (interaction) => {
    await interaction.deferReply();
    const helpEmbed = new MessageEmbed();
    helpEmbed.setTitle("100 Days of Code Bot!");
    helpEmbed.setDescription(
      "This discord bot is designed to help you track and share your 100 Days of Code progress."
    );
    helpEmbed.addField(
      "Create today's update",
      "Use the `/100` command to create your update for today. The `message` will be displayed in your embed."
    );
    helpEmbed.addField(
      "Edit today's update",
      "Do you see a typo in your embed? Right click it and copy the ID (you may need developer mode on for this), and use the `/edit` command to update that embed with a new message."
    );
    helpEmbed.addField(
      "Show your progress",
      "To see your current progress in the challenge, and the day you last checked in, use `/view`."
    );
    helpEmbed.setFooter({ text: `Version ${process.env.npm_package_version}` });
    await interaction.editReply({ embeds: [helpEmbed] });
    return;
  },
};

Conclusion

Congratulations! You have successfully built a Discord bot for the 100 Days of Code challenge.

If you are interested in exploring further, you can view the source code for the live bot that inspired this tutorial, which includes custom error logging, external error reporting, and a documentation site.

Most jobs have repetitive tasks that you can automate, which frees up some of your valuable time. This makes automation a key skill to acquire.

A small group of skilled automation engineers and domain experts may be able to automate many of the most tedious tasks of entire teams.

In this article, we'll explore the basics of workflow automation using Python – a powerful and easy to learn programming language. We will use Python to write an easy and helpful little automation script that will clean up a given folder and put each file into its according folder.

Our goal won't be to write perfect code or create ideal architectures in the beginning.
We also won't build anything "illegal". Instead we'll look at how to create a script that automatically cleans up a given folder and all of its files.

Table of contents

1. Areas of Automation and Where to Start
   • Simple Automation
   • Public API Automation
   • API Reverse Engineering
2. Ethical Considerations of Automation
3. Creating a Directory Clean-Up Script
4. A Complete Guide to Bot Creation and Automating Your Everyday Work

Areas of Automation and Where to Start

Let's start with defining what kind of automations there are.

The art of automation applies to most sectors. For starters, it helps with tasks like extracting email addresses from a bunch of documents so you can do an email blast. Or more complex approaches like optimizing workflows and processes inside of large corporations.

Of course, going from small personal scripts to large automation infrastructure that replaces actual people involves a process of learning and improving. So let's see where you can start your journey.

Simple Automations

Simple automations allow for a quick and straightforward entry point. This can cover small independent processes like project clean-ups and re-structuring of files inside of directories, or parts of a workflow like automatically resizing already saved files.

Public API Automations

Public API automations are the most common form of automation since we can access most functionality using HTTP requests to APIs nowadays. For example, if you want to automate the watering of your self-made smart garden at home.

To do that, you want to check the weather of the current day to see whether you need to water or if there is rain incoming.

API Reverse Engineering

API reverse engineering-based automation is more common in actual bots and the "Bot Imposter" section of the chart in the "Ethical Considerations" section below.

By reverse-engineering an API, we understand the user flow of applications. One example could be the login into an online browser game.

By understanding the login and authentication process, we can duplicate that behaviour with our own script. Then we can create our own interface to work with the application even though they don't provide it themselves.

Whatever approach you're aiming at, always consider whether it's legal or not.

You don't want to get yourself into trouble, do you? ?

Ethical Considerations

Some guy on GitHub once contacted me and told me this:

“Likes and engagement are digital currency and you are devaluing them.”

This stuck with me and made me question the tool I've built for exactly that purpose.

The fact that these interactions and the engagement can be automated and “faked” more and more leads to a distorted and broken social media system.

People who produce valuable and good content are invisible to other users and advertisement companies if they don’t use bots and other engagement systems.

A friend of mine came up with the following association with Dante’s “Nine Circles of Hell” where with each step closer to becoming a social influencer you get less and less aware of how broken this whole system actually is.

I want to share this with you here since I think it's an extremely accurate representation of what I witnessed while actively working with Influencers with InstaPy.

Level 1: Limbo - If you don’t bot at all
Level 2: Flirtation - When you manually like and follow as many people as you can to get them to follow you back / like your posts
Level 3: Conspiracy - when you join a Telegram group to like and comment on 10 photos so the next 10 people will like and comment on your photo
Level 4: Infidelity - When you use a low-cost Virtual Assistant to like and follow on your behalf
Level 5: Lust - When you use a bot to give likes, and don’t receive any likes back in return (but you don’t pay for it - for example, a Chrome extension)
Level 6: Promiscuity - When you use a bot to Give 50+ likes to Get 50+ likes, but you don’t pay for it - for example, a Chrome extension
Level 7: Avarice or Extreme Greed - When you use a bot to Like / Follow / Comment on between 200–700 photos, ignoring the chance of getting banned
Level 8: Prostitution - When you pay an unknown 3rd party service to engage in automated reciprocal likes / follows for you, but they use your account to like / follow back
Level 9: Fraud / Heresy - When you buy followers and likes and try to sell yourself to brands as an influencer

The level of botting on social media is so prevalent that if you don’t bot, you will be stuck in Level 1, Limbo, with no follower growth and low engagement relative to your peers.

In economic theory, this is known as a prisoner's dilemma and zero-sum game. If I don’t bot and you bot, you win. If you don’t bot and I bot, I win. If no one bots, everyone wins. But since there is no incentive for everyone not to bot, everyone bots, so no one wins.

Be aware of this and never forget the implications this whole tooling has on social media.

Source: SignalSciences.com

We want to avoid dealing with ethical implications and still work on an automation project here. This is why we will create a simple directory clean-up script that helps you organise your messy folders.

Creating a Directory Clean-Up Script

We now want to look at a quite simple script. It automatically cleans up a given directory by moving those files into according folders based on the file extension.

So all we want to do is this:

Setting up the Argument Parser

Since we are working with operating system functionality like moving files, we need to import the os library. In addition to that, we want to give the user some control over what folder is cleaned up. We will use the argparse library for this.

import os
import argparse

After importing the two libraries, let's first set up the argument parser. Make sure to give a description and a help text to each added argument to give valuable help to the user when they type --help.

Our argument will be named --path. The double dashes in front of the name tell the library that this is an optional argument. By default we want to use the current directory, so set the default value to be ".".

parser = argparse.ArgumentParser(
    description="Clean up directory and put files into according folders."
)

parser.add_argument(
    "--path",
    type=str,
    default=".",
    help="Directory path of the to be cleaned directory",
)

# parse the arguments given by the user and extract the path
args = parser.parse_args()
path = args.path

print(f"Cleaning up directory {path}")

This already finishes the argument parsing section – it's quite simple and readable, right?

Let's execute our script and check for errors.

python directory_clean.py --path ./test 

=> Cleaning up directory ./test

Once executed, we can see the directory name being printed to the console, perfect.
Let's now use the os library to get the files of the given path.

Getting a list of files from the folder

By using the os.listdir(path) method and providing it a valid path, we get a list of all the files and folders inside of that directory.

After listing all elements in the folder, we want to differentiate between files and folders since we don't want to clean up the folders, only the files.

In this case, we use a Python list comprehension to iterate through all the elements and put them into the new lists if they meet the given requirement of being a file or folder.

# get all files from given directory
dir_content = os.listdir(path)

# create a relative path from the path to the file and the document name
path_dir_content = [os.path.join(path, doc) for doc in dir_content]

# filter our directory content into a documents and folders list
docs = [doc for doc in path_dir_content if os.path.isfile(doc)]
folders = [folder for folder in path_dir_content if os.path.isdir(folder)]

# counter to keep track of amount of moved files 
# and list of already created folders to avoid multiple creations
moved = 0
created_folders = []

print(f"Cleaning up {len(docs)} of {len(dir_content)} elements.")

As always, let's make sure that our users get feedback. So add a print statement that gives the user an indication about how many files will be moved.

python directory_clean.py --path ./test 

=> Cleaning up directory ./test
=> Cleaning up 60 of 60 elements.

After re-executing the python script, we can now see that the /test folder I created contains 60 files that will be moved.

Creating a folder for every file extension

The next and more important step now is to create the folder for each of the file extensions. We want to do this by going through all of our filtered files and if they have an extension for which there is no folder already, create one.

The os library helps us with more nice functionality like the splitting of the filetype and path of a given document, extracting the path itself and name of the document.

# go through all files and move them into according folders
for doc in docs:
    # separte name from file extension
    full_doc_path, filetype = os.path.splitext(doc)
    doc_path = os.path.dirname(full_doc_path)
    doc_name = os.path.basename(full_doc_path)

    print(filetype)
    print(full_doc_path)
    print(doc_path)
    print(doc_name)

    break

The break statement at the end of the code above makes sure that our terminal does not get spammed if our directory contains dozens of files.

Once we've set this up, let's execute our script to see an output similar to this:

python directory_clean.py --path ./test 

=> ...
=> .pdf
=> ./test/test17
=> ./test
=> test17

We can now see that the implementation above splits off the filetype and then extracts the parts from the full path.

Since we have the filetype now, we can check if a folder with the name of this type already exists.

Before we do that, we want to make sure to skip a few files. If we use the current directory "." as the path, we need to avoid moving the python script itself. A simple if condition takes care of that.

In addition to that, we don't want to move Hidden Files, so let's also include all files that start with a dot. The .DS_Store file on macOS is an example of a hidden file.

    # skip this file when it is in the directory
    if doc_name == "directory_clean" or doc_name.startswith('.'):
        continue

    # get the subfolder name and create folder if not exist
    subfolder_path = os.path.join(path, filetype[1:].lower())

    if subfolder_path not in folders:
        # create the folder

Once we've taken care of the python script and hidden files, we can now move on to creating the folders on the system.

In addition to our check, if the folder already was there when we read the content of the directory, in the beginning, we need a way to track the folders we've already created. That was the reason we declared the created_folders = [] list. It will serve as the memory to track the names of folders.

To create a new folder, the os library provides a method called os.mkdir(folder_path) that takes a path and creates a folder with the given name there.

This method may throw an exception, telling us that the folder already exists. So let's also make sure to catch that error.

if subfolder_path not in folders and subfolder_path not in created_folders:
        try:
            os.mkdir(subfolder_path)
            created_folders.append(subfolder_path)
            print(f"Folder {subfolder_path} created.")
        except FileExistsError as err:
            print(f"Folder already exists at {subfolder_path}... {err}")

After setting up the folder creation, let's re-execute our script.

python directory_clean.py --path ./test 

=> ...
=> Folder ./test/pdf created.

On the first run of execution, we can see a list of logs telling us that the folders with the given types of file extensions have been created.

Moving each file into the right subfolder

The last step now is to actually move the files into their new parent folders.

An important thing to understand when working with os operations is that sometimes operations can not be undone. This is, for example, the case with deletion. So it makes sense to first only log out the behavior our script would achieve if we execute it.

This is why the os.rename(...) method has been commented here.

# get the new folder path and move the file
    new_doc_path = os.path.join(subfolder_path, doc_name) + filetype
    # os.rename(doc, new_doc_path)
    moved += 1

    print(f"Moved file {doc} to {new_doc_path}")

After executing our script and seeing the correct logging, we can now remove the comment hash before our os.rename() method and give it a final go.

# get the new folder path and move the file
    new_doc_path = os.path.join(subfolder_path, doc_name) + filetype
    os.rename(doc, new_doc_path)
    moved += 1

    print(f"Moved file {doc} to {new_doc_path}")

print(f"Renamed {moved} of {len(docs)} files.")

python directory_clean.py --path ./test 

=> ...
=> Moved file ./test/test17.pdf to ./test/pdf/test17.pdf
=> ...
=> Renamed 60 of 60 files.

This final execution will now move all the files into their appropriate folders and our directory will be nicely cleaned up without the need for manual actions.

In the next step, we could now use the script we created above and, for example, schedule it to execute every Monday to clean up our Downloads folder for more structure.

That is exactly what we are creating as a follow-up inside of our Bot Creation and Workflow Automation Udemy course.

A Complete Guide to Bot Creation and Automating Your Everyday Work

Felix and I built an online video course to teach you how to create your own bots based on what we've learned building InstaPy and his Travian-Bot. In fact, he was even forced to take down since it was too effective.

Join right in and start learning.

If you have any questions or feedback, feel free to reach out to us on Twitter or directly in the discussion section of the course ?

Teamwork in Slack happens in channels — a single place for messaging, tools and files — helping everyone save time and collaborate.

One of the awesome features of Slack is Slack Apps, integrations and Slack Bots.

A Slack bot is a type of Slack App designed to interact with users via conversation. Your bot can send DMs, it can be mentioned by users, it can post messages or upload files, and it can be invited to channels. Cool right?

If you use Slack already, you should be familiar with some creative Slack bots like Standupbot, Birthdaybot and more.

In this article, I'll walk you through building your first Slack bot from start to finish with Node.js and SlackBots.js

PS: This article was published on my blog first.

SlackBot Description

We're going to build a simple Slackbot that displays random inspiring techie quotes and jokes for developers/designers.

I built a chrome extension that displays random inspiring techie quotes for developers/designers on your new tab (you can download it here). We'll be using the quotes JSON from this extension as our quotes API and the Chuck Norris Jokes API for the jokes.

When a user mentions our bot and adds inspire me, the bot returns a random quote from inspireNuggets. When the user types random joke, it returns a random joke from the Chuck Norris API. And when the user types help, it returns the instruction guide.

@inspirenuggets inspire me

@inspirenuggets random joke

@inspirenuggets help

This article is not really about what we'll be building - it's just to show you the concept behind Slack bots and how to build yours. After you go through it, you can think about something else and build a different bot, as there're many possibilities.

You can clone or fork the final project here.

Pretty interesting right? Let's get started.

Prerequisites

We'll build this bot with Node.js and SlackBots.js. You don't need to know how to write Node.js, since I'll walk you through it. Still, knowing it is an advantage. You should also have

• Basic JavaScript knowledge

• ES6 JavaScript

• Slack workspace

• Some experience with Slack

• Some version control skills

Setup environment

Let's set up and install Node.js and Npm first.

• Download node here. If you have it installed already, skip this step. If you prefer to use a package manager to install, read this for all operating systems.

• Check if you have Node installed

node -v

• Node.js comes with Npm, so you don't have to install that again.

npm -v

Now that we have Node.js setup, let's initialize our project.

Create your project directory (I called mine Slackbot) and initialize git:

git init

Next, create an index.js file:

touch index.js

And initialize Npm:

npm init

Simply answer all questions that come afterwards. If you're having issues, here's my own package.json:

{
  "name": "slackbot",
  "version": "1.0.0",
  "description": "A simple Slackbot that displays random inspiring techie quotes for developers/designers.",
  "main": "index.js",
  "scripts": {
    "start": "index.js"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/BolajiAyodeji/slackbot.git"
  },
  "author": "Bolaji Ayodeji",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/BolajiAyodeji/slackbot/issues"
  },
  "homepage": "https://github.com/BolajiAyodeji/slackbot#readme"
}

Install Dependencies

Now let's install and setup all the libraries we need.

SlackBots.js

SlackBots.js is a Node.js library for easy operation with the Slack API.

npm install slackbots

In index.js:

const SlackBot = require('slackbots');

Axios

Axios is a promise-based HTTP client for the browser and node.js. If you know Fetch or AJAX, this is just a library that does the same thing with way cooler features. You can see them here.

npm install axios

In index.js:

const axios = require('axios')

Nodemon

To run a script in Node.js, you have to run node index.js. Whenever you make changes to this file, you have to rerun node index.js. This sucks when you're making so many changes like we'll be doing. That's why we need nodemon, a tool that helps develop node.js based applications by automatically restarting the node application when file changes in the directory are detected.

npm install -g nodemon

In package.json, locate the scripts section and add a new start script:

"scripts": {
    "start": "node index.js"
  }

If you run npm start, the file will run but won't restart on change. To fix this, use the nodemon we installed instead of node like so:

"scripts": {
    "start": "nodemon index.js"
  }

Dotenv

I won't explain this in-depth. In a few days, I'll publish an article around environmental variables, but for now just know that we use this to hide secret keys and tokens like the Slack Access Token we would be using. This way you don't have to push your secret keys to GitHub.

There are several ways to do this, but I prefer using dotenv. Dotenv is a zero-dependency module that loads environment variables from a .env file into process.env.

npm install dotenv

In index.js:

const dotenv = require('dotenv')

dotenv.config()

After all installation, your package.json should look like this:

{
  "name": "inspireNuggetsSlackBot",
  "version": "1.0.0",
  "description": "A simple Slackbot that displays random inspiring techie quotes and jokes for developers/designers.",
  "main": "index.js",
  "scripts": {
    "start": "nodemon index.js"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/BolajiAyodeji/inspireNuggetsSlackBot.git"
  },
  "author": "Bolaji Ayodeji",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/BolajiAyodeji/inspireNuggetsSlackBot/issues"
  },
  "homepage": "https://github.com/BolajiAyodeji/inspireNuggetsSlackBot#readme",
  "devDependencies": {
    "dotenv": "^8.0.0"
  },
  "dependencies": {
    "axios": "^0.19.0",
    "slackbots": "^1.2.0"
  }
}

Create your Slack workspace

Now that we have that all set up, we need a Slack workspace to run our bot in development. Creating a workspace is pretty easy, read this to learn more.

Register your Slack Bot

Now that you have a workspace, you should have a Slack URL with your workspace name. Mine is mekafindteam.slack.com.

Now you'll need to create a Slack App. Create one here.

Enter your App name and ensure you're in the workspace you created if you're in multiple workspaces.

Now you'll see the settings > Basic Information page. Click the first tab Add features and functionality:

Since we're building a bot, select the Bots field.

Now you'll see the Bot user page:

Click the Add a Bot User button.

Your display name will automatically be filled in from your already chosen App name. You can update it, but I'll advise you use the same name everywhere with the same alphabet case to avoid errors.

Now, toggle the Always Show My Bot as Online switch to always show your bot as Online. Remember this bot is just like a user in your workspace. Afterwards, click the Add Bot User button.

Save all changes now:

Next, return to the Basic Information page and select the Install your app to your workspace tab.

Click the Install App to Workspace:

Click allow and wait to be redirected back to the Basic Information page.

Note the Manage distribution tab: this section is needed when you want to make your Bot available for installation by others. For now we're just building in development and I won't be covering distribution in this article. In my next article, I'll show you how to deploy your Slack bot and make it available as an App to other workspaces.

If you check your Slack workspace now, you should see the App installed in the Apps section.

For now, it's offline - once we start building the bot, we'll turn this on.

Customize your Slack bot

Now we've created our bot, let's do some customization.

Still, on the Basic Information page, scroll down to the Display Information section:

This is basic stuff: just upload a logo, change your background color, and add a short description.

Your icon should be 512x512px or bigger and your background color should be in HEX. Read more on the App guidelines here.

Here's what mine looks like after customization:

Slack bot OAuth Tokens

Now that we have our Slack bot setup, let's grab out token keys.

In the navigation bar, locate the Features section and click the OAuth & Permission tab:

You'll see two Access Tokens:

• OAuth Access Token

• Bot User OAuth Access Token

Copy the Bot User OAuth Access Token.

This will change every time you re-install this app or when you install it in another workspace. The token should start with xoxb-.

Keeping credentials secure is important whether you're developing open source libraries and tools, internal integrations for your workspace, or Slack apps for distribution to workspaces across the world. - Slack

This is why we have installed Dotenv - we'll set that up in the next section.

Building the bot

Now let's build our bot :).

First, let's keep our Access Token somewhere.

Create a .env file and add this:

BOT_TOKEN=YOUR_SLACK_ACCESS_TOKEN_HERE

Now let's start our SlackBot.js:

const bot = new SlackBot({
    token: `${process.env.BOT_TOKEN}`,
    name: 'inspirenuggets'
})

We've just created a bot variable that initializes a new SlackBot instance which has two values, our token and app name.

I used the ES6 template string syntax to bring in our token key from our .env file. dotenv has this covered for us.

Make sure you use the same name you used while creating your Slack app, or else you'll have authentication errors.

Now start the app:

npm start

nodemon should be running now and our Slack app should be online too.

Start handler

Our Bot does nothing now even though it's running. Let's return a message.

bot.on('start', () => {
    const params = {
        icon_emoji: ':robot_face:'
    }

    bot.postMessageToChannel(
        'random',
        'Get inspired while working with @inspirenuggets',
        params
    );
})

The bot.on handler sends the welcome message. We passed two parameters, the 'start' and a function which holds a params variable which also holds the slack emoji. Slack emoji have codes, and you can find them here. I used :robot_face:, but you can change this to your preferred emoji.

We also initialized the bot.postMessageToChannel function which is a SlackBot.js method to post a message to a channel. In this function, we pass the channel name we want to post to, the message in a string, and the params variable we declared earlier for the emoji. I used the #random channel and sent Get inspired while working with @inspirenuggets to it. Your app should restart automatically and your bot should do this:

Cool right?
You can also post messages to users and groups.

    // define existing username instead of 'user_name'
    bot.postMessageToUser('user_name', 'Hello world!', params); 


    // define private group instead of 'private_group', where bot exist
    bot.postMessageToGroup('private_group', 'Hello world!', params);

Error Handler

Let's also write a function to check for errors and return them:

bot.on('error', (err) => {
    console.log(err);
})

Message Handler

Now let's build the main bot functionality.

Like I said earlier, we'll be using the quotes JSON from the extension I built as our quotes API. The JSON can be found with this URL: https://raw.githubusercontent.com/BolajiAyodeji/inspireNuggets/master/src/quotes.json

When a user mentions our bot and adds inspire me, the bot returns a random quote from inspireNuggets. When the user types random joke, it returns a random joke from the Chuck Norris API. And when the user types help, it returns the instruction guide.

First, let's check for our command words from the user message (inspire me, random joke, and help):

function handleMessage(message) {
    if(message.includes(' inspire me')) {
        inspireMe()
    } else if(message.includes(' random joke')) {
        randomJoke()
    } else if(message.includes(' help')) {
        runHelp()
    }
}

Now let's create the three function we need

inspireMe()

Our demo JSON is not really an API, it's just some JSON I used in the Chrome Extension. We're only accessing it from GitHub raw contents. You can use any API you prefer, you'll just have to iterate differently to get your data depending on if your API returns an array or object - whichever it returns, it's not a big deal.

Check out my previous articles on:

• Manipulating Arrays in JavaScript and

• Iterating through JavaScript Objects  -  5 Techniques and Performance Tests.

function inspireMe() {
    axios.get('https://raw.githubusercontent.com/BolajiAyodeji/inspireNuggets/master/src/quotes.json')
      .then(res => {
            const quotes = res.data;
            const random = Math.floor(Math.random() * quotes.length);
            const quote = quotes[random].quote
            const author = quotes[random].author

            const params = {
                icon_emoji: ':male-technologist:'
            }

            bot.postMessageToChannel(
                'random',
                `:zap: ${quote} - *${author}*`,
                params
            );

      })
}

We just used Axios to get the JSON file which returns some data:

[
    {
        "number": "1",
        "author": "Von R. Glitschka",
        "quote": "The client may be king, but he's not the art director."
    },
    {
        "number": "2",
        "author": "Frank Capra",
        "quote": "A hunch is creativity trying to tell you something."
    },
.
.
.
.
]

This JSON currently contains 210 quotes and I update them frequently. So we want to get a random quote plus the author name every time the user request it. From our Axios response, we just do this:

const quotes = res.data;
const random = Math.floor(Math.random() * quotes.length);
const quote = quotes[random].quote
const author = quotes[random].author

And just like we did with the welcome message, we just return the quote and author instead of a string message:

`:zap: ${quote} - *${author}*`

Let's test this:

Type @inspirenuggets inspire me

Yayyy! It worked!

PS: You can always change the emoji type for every request. If you noticed I changed the inspireMe() to :male-technologist:

randomJoke()

We're getting the jokes from the Chuck Norris API from this endpoint https://api.chucknorris.io/jokes/random.

{
"categories": [],
"created_at": "2016-05-01 10:51:41.584544",
"icon_url": "https://assets.chucknorris.host/img/avatar/chuck-norris.png",
"id": "6vUvusBeSVqdsU9C5-ZJZw",
"updated_at": "2016-05-01 10:51:41.584544",
"url": "https://api.chucknorris.io/jokes/6vUvusBeSVqdsU9C5-ZJZw",
"value": "Chuck Norris once choked a wildcat to death with his sphincter muscle."
}

This is a real API that returns a random joke on every request, so we don't have to do Math.floor() again.

function randomJoke() {
    axios.get('https://api.chucknorris.io/jokes/random')
      .then(res => {
            const joke = res.data.value;

            const params = {
                icon_emoji: ':smile:'
            }

            bot.postMessageToChannel(
                'random',
                `:zap: ${joke}`,
                params
            );

      })
}

By now, you should understand how this works already. Make a post with the channel name, message and params.

runHelp()

This is similar to our welcome message: we just want to return a custom text when the user adds help to the request.

function runHelp() {
    const params = {
        icon_emoji: ':question:'
    }

    bot.postMessageToChannel(
        'random',
        `Type *@inspirenuggets* with *inspire me* to get an inspiring techie quote, *random joke* to get a Chuck Norris random joke and *help* to get this instruction again`,
        params
    );
}

Now let's test all three commands:

Everything works fine now, congratulations!!!! You just built your SlackBot.

There are an endless number of possibilities of Bots you can build with this to automate your own work or teamwork.

You can build a bot that:

• Fetches your tasks from somewhere and reminds you when you type hey what next,

• Welcomes every user to your workspace (I built this during one of the HNG Internship's),

• Gives you football matches updates while you're working,

• Tells your team when you hit a milestone in number of registered users,

and many more...

It's just about having somewhere to get the data from, and some basic iteration skills and the bot.postMessageToChannel() method.

Automation is one thing we should learn as developers. We have a lot to do, so we should automate the simpler tasks so we have time for the more difficult ones. I hope with this you can automate your tasks and I look forward to the creative ideas you'll bring to life.

Final Code

Here's our final index.js

const SlackBot = require('slackbots');
const axios = require('axios')
const dotenv = require('dotenv')

dotenv.config()

const bot = new SlackBot({
    token: `${process.env.BOT_TOKEN}`,
    name: 'inspirenuggets'
})

// Start Handler
bot.on('start', () => {
    const params = {
        icon_emoji: ':robot_face:'
    }

    bot.postMessageToChannel(
        'random',
        'Get inspired while working with @inspirenuggets',
        params
    );
})

// Error Handler
bot.on('error', (err) => {
    console.log(err);
})

// Message Handler
bot.on('message', (data) => {
    if(data.type !== 'message') {
        return;
    }
    handleMessage(data.text);
})

// Response Handler
function handleMessage(message) {
    if(message.includes(' inspire me')) {
        inspireMe()
    } else if(message.includes(' random joke')) {
        randomJoke()
    } else if(message.includes(' help')) {
        runHelp()
    }
}

// inspire Me
function inspireMe() {
    axios.get('https://raw.githubusercontent.com/BolajiAyodeji/inspireNuggets/master/src/quotes.json')
      .then(res => {
            const quotes = res.data;
            const random = Math.floor(Math.random() * quotes.length);
            const quote = quotes[random].quote
            const author = quotes[random].author

            const params = {
                icon_emoji: ':male-technologist:'
            }

            bot.postMessageToChannel(
                'random',
                `:zap: ${quote} - *${author}*`,
                params
            );

      })
}

// Random Joke
function randomJoke() {
    axios.get('https://api.chucknorris.io/jokes/random')
      .then(res => {
            const joke = res.data.value;

            const params = {
                icon_emoji: ':smile:'
            }

            bot.postMessageToChannel(
                'random',
                `:zap: ${joke}`,
                params
            );

      })
}

// Show Help
function runHelp() {
    const params = {
        icon_emoji: ':question:'
    }

    bot.postMessageToChannel(
        'random',
        `Type *@inspirenuggets* with *inspire me* to get an inspiring techie quote, *random joke* to get a Chuck Norris random joke and *help* to get this instruction again`,
        params
    );
}

What Next?

Our bot only runs in development now, and to use it we always have to npm start.

This isn't cool, right? We'll want to host it somewhere it can run every time. In my next article, I'll show you how to host this on either Heroku, Zeit or Netlify and publish it to the Slack Apps store so anyone around the world can use it.
Also, don't forget to add this in your .gitignore before pushing to GitHub:

/.env
/node_modules

Subscribe to my newsletter to get updated.

Useful Resources

• Slack API

• Slack API Docs

• SlackBot.js

• Slack Apps

• Slack Apps Guidelines

• An introduction to Slack apps

• inspireNuggets

• inspireNuggetsSlackBot

At their core, AI projects can be depicted as a simple pipeline of a few building blocks. The diagram above explains that pretty nicely: Unstructured content, usually in huge amounts of data, comes in from the left, and is fed into AI classifiers. These pre-trained machine- or deep- learning models separate the wheat from the chaff and reduce the input to a few numerical or string output values.

For example, megas of pixels and colors in an image are reduced to a label: this is a giraffe. Or a zebra. In audio, millions of wave frequencies produce a sentence through Speech To Text models. And in conversational AI, that sentence can be reduced further to a few strings representing the intent of the speaker and the entities in the sentences.

Once the input has been recognized, we need to do things, and generate some meaningful output. For example, a car recognized too close should turn the wheel in an autonomous car. A request to book a flight should produce some RESTFul database queries and POST calls, and issue a confirmation, or a denial, to the user.

This last part, shown in the diagram as rule-based logic, is an inseparable part of any AI system, and there’s no change in sight to that. It has usually been done by coding, thousands and thousands of lines of code — if it’s a serious system — or a couple of scripts if it’s a toy chatbot.

Behavior Trees

A Behavior Tree is a programming paradigm that emerged in video games to create human-like behaviors in non-player characters. They form an excellent visual language with which a software architect, a junior developer and even a non-coder, technical designer can all create complex scripts. In fact, since Behavior trees (BTs) allow logic operations like AND and OR, loops and conditions, any program that can be created by code, can be created with BTs.

Servo is an open-source AI conversational framework built on top of a JavaScript behavior tree framework called Behavior3. It’s designed to do the needed orchestration of inputs and outputs for conversational AI systems. It’s what is called “low-code” framework: you only need to code a little, and most of the tasks can be done in the visual editor.

It’s not your usual newbie's toy: it was designed to be extended using real-life, debuggable JS source files and classes, and abide by any team project-management methodologies. Moreover, it’s suitable for teams that grow in size, allowing the introduction and reuse of new modules through abstracted and decoupled sub-processes.

I’m the main developer of Servo. After 30-something years of coding, feeling the pain in long-delayed projects and watching legacy systems break under their own weight, I wanted to achieve maximum flexibility with minimum coding. Here I’m going to explain the magic that can be done when one combines Behavior Trees with NLU/NLP engines, using Servo and Wit.ai.

Any developer can benefit from this tutorial, but it’s best if you are a developer with experience in building chat- or voice-bots and have knowledge working with NLU/NLP engines like LUIS, Wit.AI, Lex (the Alexa engine), or Dialogflow. If you do not, it’s ok, but I’ll be covering some subjects a bit briefly.

If you want to learn about NLU and NLP engines, there are excellent resources all over the Internet — just search for ‘Wit tutorial’. If you want to learn how to build a heavyweight assistant, then just continue reading.

Getting Started with Servo

I won’t get into details of installing Servo here, but just say that getting started with Servo is really easy. You can read about it here. In essence, you clone the Github repo, npm-install it according to the readme, and run it locally. Then, every New Project would start you off with a small ready-made bot to get things going:

Every New Project has a starting tree

You can notice here the green hexagons named ‘chit-chat’, ‘cancel’ and others. By the end of this article, you’ll have a clear idea of what they are and how they work. But first, let’s tackle the first challenges.

Building An NLU Model

Let’s talk about building a banking assistant, and specifically, one that works for the money transfer department. Had it been a web application, we would have a form with few fields, among which the amount and the transferee’s (also called beneficiary) account are the most important. Let’s use these here for this tutorial. Actually, when using NLU engines, we can still think of it as forms, with the fields now called entities (also slots, in Alexa lingo). The NLU engines also produce an intent, which can be viewed as the name of the form that will guide the assistant to the area of that functionality of the user’s intent.

We should train the NLU engine with a few sentences, such as:

• “I’d like to send some money”
• “I’d like to send $100 “
• “Please transfer $490 to account #01–10099988”

And for these, we need to tell the engine to output the following:

• a TransferIntent intent for such sentences
• A wit/number for the amount
• An accountNumberEntity for the beneficiary account

Let’s do that on Wit.ai. Again, I won’t get into a Wit tutorial — there are plenty of guides. Servo comes with a general Wit model which you can take from Servo’s Github here. Then, open your own Wit app and import it.

I created a free-text entity for the account numbers (as account number might include other symbols), and a wit/number entity for the amount. I found composite entities work pretty well, too, although they need some training. For simplicity, for account numbers, I trained the model to be a # followed by 8 digits.

In general, it’s always better to experiment with different entity models. In our case, we might get two numbers in the same sentence (account number and amount) and we need a way to tell them apart, so it’s best if it’s two different entity names. But you can try other types: AI is still a very empirical science…

We then trained it with a few sentences and let Wit build the bank-transfer model. For convenience, I added it here, and also set the whole banking bot tutorial bot to come along with the pre-loaded examples.

Training Wit with sample bank transfer sentences

Last, we need to connect the NLU to the assistant. Go to Settings in Wit, and copy the access token. We need to paste it in our tree root’s properties. We do this by opening Servo’s editor, selecting the root, opening its properties, and pasting it under nlu. As you can see, Servo supports multi-language assistants and different NLU engines:

Start The Bank Assistant

Now, we can turn to Servo. We should construct a small tree with a question for each entity and intent.

As a reminder, the basic rules of Servo behavior-trees is as follows

1. The main loop of the tree is executing the root continuously
2. Each node executes its children
3. An AskAndMap node (the “Age” node in the diagram above) outputs a question to the user and waits for an answer
4. Once an answer comes in, the flow is routed to the appropriate child according to the intent and entities that the NLU engine gave it

Let’s first change the main, topmost question from “Age?” into “What would you like to do?”. Also, let’s delete the first (that is, left-most) child and its nodes, as we are not going to use them anymore:

Type in the initial assistant question

Why are we seeing the red dashes around the node? Hover over it and you’ll see the error:

Count of contexts number should be equal to the number of children

We will fix that in a minute.

Now let’s build the transfer flow. We’ll assume that once the user says “I’d like to wire money”, we want to descend into the first, leftmost child. For that, we’ll select the “How can I help you” node and go into its properties. There, change the first context to have an intentId of “TransferIntent”:

This will cause any sentence that the Wit determines to have a TransferIntent, to be routed there.

Mapping an entity

Now, once the NLU has recognized our intent to transfer money, we should get all the different “fields”, or entities. Let’s add a node for the amount:

We added an AskAndMap node, and set its prompt to a question about the amount. We also changed its title — it’s always a good practice. Last, don’t forget to save your work using the Save button or Ctrl-S.

You can also notice the red warning disappeared from the How can I help you node.

Last, let’s add a number entity to one of the child contexts of the Amount node, and map the value into a field called amount.

“contexts”: [
 {
   “entities”: [
    {
      “contextFieldName”: “amount”,
      “entityName”: “number”,
      “expectedValue”: “”,
      “entityIndex”: 0
    } 
   ]
 }

All this seems very simple, and it is: if a user says something like “I need to send some money”, they will be asked, “What is the amount?”. Once they enter the amount, the number will be extracted by the NLU and mapped to the context.amount in Servo. Then, we can use it later in the game. Visually, the flow started from the root:

And the assistant would ask:

“How can I help you?”

If the user answered:

“I’d like to transfer some money”

the NLU engine would output a TransferIntent and the flow would continue downstream to the context it identified — the leftmost child — and ask the next question, about the amount:

But what if the user doesn’t enter an amount?

Building Helpers

AskAndMap nodes support another type of a context child, called a Helper. This context is selected when the user answered something that couldn’t be mapped to any other context. Let’s add one into our What’s the amount AskAndMap:

"contexts":[  
   {  
      "entities":[  
         {  
            "contextFieldName":"amount",
            "entityName":"number",
            "expectedValue":"",
            "entityIndex":0
         }
      ]
   },
   {  
      "helper":true
   }
]

Let’s now add a right-most child with a message help. Something like:

Of course, there can be only one helper context child for the AskAndMap.

One could imagine an example of the flow:

User: “I’d like to transfer some money”

Assistant: “What is the amount?”

User: “You think I’d know. But I’m not sure”

Assistant: “Please provide the amount to transfer”

That looks simple: obviously, the assistant didn’t understand the “You think I’d know. But I’m not sure” and went on with the helper message “Please provide the amount to transfer”.

But in fact, if you’ll run the bot, you will get a surprising sentence after that last line:

User: “You think I’d know. But I’m not sure”

Assistant: “Please provide the amount to transfer”

Assistant: “How can I help you?”

What happened here? Where did the “How can I help you?” come from?

Here’s the flow. The helper node said its line and returned SUCCESS to its parent, the AskAndMap. This, in turn, returned SUCCESS too, and so on, until the root was reached. At which point, the whole tree was restarted, and we get the initial How can I help you?” question.

So, to avoid that, we need to put a loop before the AskAndMap, so that it won’t return until it really succeeded. That is done with something called a decorator.

Adding a repeat decorator

Behavior Trees implement loops using decorators, which are nodes that have one parent and one child. Depicted as a rhombus ⧫, we will use here the RepeatUntillSuccess decorator to loop the AskAndMap until it is successfully completed. Receiving a help message would not complete it, so we need to return a FAILURE after the help message. We do that by sequencing a Failer node right after the message. All in all, that’s the decoration we add to the AskAndMap construct:

Now it’s the time to add the next node that would map the beneficiary account number. Again, pretty straight-forward: as before, we add an an AskAndMap with the question for the account number and a map from accountNumberEntity to an accountNumber member on the context. We set it as a child of a RepeatUntilSuccess decorator, and a helper child that explains what’s needed for this entity.

Then, we should add the actual business logic to do the transfer. This would probably mean several API calls with the entities collected. We would simulate this with a message: we are going to transfer $X to account #Y. For that, you need to drag in a GeneralMessage as the first child of the accountNumberEntity, and make its properties as follows:

“debug-log”:””,
 “runningTimeoutSec”:600,
 “maxRetriesNumber”:5,
 “replayActionOnReturnFromContextSwitch”:true,
 “view”:false,
 “prompt”:[ 
 “About to transfer <%=context.amount%> to account <%=context.accountNumber%>”
],
…

This is how the tree looks like now:

The tree comes with Servo. It’s files are under server/convocode/anonymous/drafts/bank-bot.

Running and testing

Let’s test the bot and see what happens with various inputs. Click on the Debugger tab, then the play button ▶️. On the right hand the simulator will pop:

You can enter a sentence like:

I’d like to send money.

That would be answered, as expected, with

“What is the amount?”

And you can put in the amount, and continue.

But what if we say

I’d like to send $14141??

Test it, and you’ll see how the assistant nicely jumps over the amount question straight to the account number:

“What is the account number?”

Now, let’s make its life even harder:

I’d like to send money to account #87654321

Nicely enough, it asks only for the amount. Say you enter $3400, it would then skip the account number (since it knows it already) into the final confirmation sentence:

About to transfer 3400 to account #87654321.

How does it know to do all that magic?

The Context Flow

Servo comes equipped with a powerful context-recognition set of algorithms that helps it do all that. What happened here shows a bit of it. Let’s take the last example. After the assistant asked:

“How can I help you?”

And the user answered:

I’d like to send money to account #87654321

The NLU engine output a TransferIntent and the flow continued downstream to the next question, about the amount:

But the NLU also returned an accountNumberEntity! So before descending, this entity is saved on the ‘How can I help you’ context. And, every AskAndMap defines its own context.

That’s actually an important remark, so I’ll repeat it: every AskAndMap defines its own context.

At any point in the flow, when an entity is mentioned, Servo searches back (read: upwards) in the conversation to find it. If it hasn’t, it would ask for it.

So after the amount is entered, once we continue to the account number node, Servo finds that the accountNumberEntity was already mentioned, and uses it.

By the way, a process of similar characteristics happens also when we get to the last confirming GeneralMessage node. Its prompt reads:

About to transfer <%=context.amount%> to account <%=context.accountNumber%>

To resolve that, Servo searches up the context tree to find the needed entities, or context members.

Does this remind you of something? Folks familiar with JavaScript prototypical inheritance would see that it basically uses the same design. In Servo, we implemented that since we need more control over the variables. But it’s always interesting to see how object-oriented concepts are actually applied to real life, natural conversations.

But what if the user asks something much more unrelated, like:

“How much money do I have in my account?”

Or more so

“Who are you, for heaven’s sake??”

To which to bot responds:

“I’m an artificial intelligence assistant built by Servo Labs.”

Whaaaaaaaaaat?? Where did this come from?

Context and sub-trees

Almost all of the structural designs architects use to build manageable large systems can be divided into one of two categories:

• Reuse
• Modularize

If Servo is to stand as the infrastructure of large AI systems, it must provide some mechanism for allowing developers to achieve these goals. And that’s where sub-trees come into play.

We mentioned before the green hexagons:

This is a sub-tree. Double-click it, and you’ll enter a new tree, with that name. To create a new sub-tree, hover over the Trees on the left pane and select New:

A tree with a unique GUID name would appear. Change its name to something meaningful, and build it using any node from the left pane. Once built, you can drag, drop and connect it at any point in any other tree (including itself, by the way, but be very careful about that). Since sub-trees can have many leaf nodes, you can connect them only as leaves, too.

What happened when the user asked the assistant “Who are you”?

First, the NLU, already trained for such questions, returned a WhoAreYouIntent. Then context search was activated. If the conversation was somewhere down in the middle of a transfer conversation, the search went upwards, trying to find a context with WhoAreYouIntent. This context is found: it sits on the 4th context, in the How can I help you node. The flow then was redirected there, meaning, that route was made the active route. The flow here continued downstream into the chit-chat subtree, answered the question, returned up with a SUCCESS and the routing was returned to its previous context, the transfer one.

Here we learned something actually very important. The conversation flows down, but context is searched up. Never forget that:

The conversation flows down, but context is searched up

Connecting to a messenger client

Until now, we have used the internal simulator and debugger as our messaging client. Let’s connect our small assistant to a real Facebook messenger. There is one big important change on the root properties of our tree, and that is to change the channel name from the default channel “chatsim” to “facebook”:

"channels":"facebook"

On the Facebook side, these are the main high-level steps that one needs to take:

1. Open a Facebook page under your Facebook account
2. Create a new Facebook app in the Facebook developer center
3. Add a messenger functionality to your app
4. Subscribe the app to listen to events in the page
5. Set the assistant callback address as the webhook to post to. Servo always publish its bot with the format of

/entry//

So for a bank-bot assistant, running on www.mydomain.com, the address would be:

https:///entry/fb/bank-bot

You should set it in the page subscription section of the Facebook app, at the developer’s portal. You need to select at least messages, _messagingpostbacks, and to match the verify token with the validation token you set in the bot’s root properties:

By the way, https://serveo.net is a great tunneling system (another alternative is ngrok), if you are developing your assistants, like me, on localhost.

On the assistant root properties, set the same verify token and re-publish it:

"facebook": {
    "validationToken": "mytoken123",
    "accessToken": "<token here>"
  },

The access token should be set too, taken from Facebook’s messenger area:

Last, select a page to subscribe your webhook to the page events:

and… once you connect all these ends, you should have, at last, a full, orchestrated, end-to-end conversational AI system!

Connecting Backends

Real life connections vary, but luckily, most of them these days are done by using RESTFul API. For these, check out the documentation on RetrieveJSONAction and PostAction. Once data is retrieved, or a response is received, it is set into a memory field (context/global/volatile). You probably would want to query it. This is done using ArrayQueryAction, which implements an in-memory Mongo-like query language. For direct MongoDB queries, use the MongoQuery action.

In Summary

Servo is an open-source IDE and framework that uses a context-recognition search to place the user on the right conversation and output the right questions. We learned how to construct a simple conversation, and how to wrap such conversations in sub-trees for decoupling and re-use. Servo has many other features that are worth exploring, among which you could find

• Connectors to Facebook, Alexa, Twilio and Angular
• Connectors to MongoDB, Couchbase and LokiJS databases
• Harness for automated conversation testing
• A Conversation debugger
• More actions, conditions and decorators
• Flow control mechanisms
• Field assignment and compare
• Context manipulation
• Validation
• In-memory mongo-like queries
• And any customized action you come up with

Feel free to check it out and ask questions on the Github forum or at my @lmessinger Github name. Enjoy!

So a little background: I recently picked up Golang and decided to create a Twitter bot as a side project. Then came the problem. There is little to no documentation on using the Twitter API with Golang ?(particularly the oauth1 and CRC encryption parts of it). So after some days of trial and error and finally completing it, I want to share the process. Hopefully, this helps someone out there.

What are we going to build?

We will build a Twitter bot that will be served from our local machine. It will respond to any tweet that is tagged in with a “hello world”.

Here’s a brief explanation as to what this go program will do. It will:

• Listen and respond to webhook CRC validation.
• Register a webhook URL that points to it.
• Listen for tweets and respond with “hello world”.

What do you need?

• Some basic knowledge of Golang
• An approved Twitter developer account. How to apply.
• You should have an account activity API dev environment set up — call it dev for this project
• A Twitter app with generated consumer keys and access tokens (Read and write access)
• Golang installed on your development machine.
• Some determination.

Ready? Let’s Go

First things first. Create your project folder in your $GOPATH/src/ . We’ll be calling this project and our folder hellobot . In it create the intro file /hellobot.go

The first thing we need to do is to create an endpoint for our app to listen to CRC checks and respond. Twitter sums up the requirements for the check pretty well.

Setting up a server

The first thing we do is load the .env file. For that we are using the godotenv plugin. The .env file is usually in this format:

CONSUMER_KEY=CONSUMER_SECRET=ACCESS_TOKEN_KEY=ACCESS_TOKEN_SECRET=WEBHOOK_ENV=devAPP_URL=

Note: We will be using basic go get to install all our dependencies considering the tiny size of our project

Then we set up our server using mux as our handler, and listen to the base route and webhook/twitter . If you install this using go install and run hellobot, when you run it and navigate to your localhost:9090 you should see the message

CRC validation

Now for the CRC, update your CrcCheck() function with the following code:

Here what we do in the function is:

• Set the header to ‘application/json’
• Get the crc_token URL parameter
• Encrypt it using Hmac sha256 and encode it
• Print it to the response writer

Make sure to replace the CONSUMER_SECRET with the actual consumer secret key for your app. Now if you navigate to localhost:9090/webhook/twitter?crc_token=test you should get a response similar to this:

Now that we have a working CRC route, time to register our webhook. Now a couple of things to note here. Twitter will not accept localhost based URLs nor will it accept a URL with a port number or a non-https URL as a webhook. A way around that during development is to use a service like ngrok. Simply install it and start up a dev server pointing to your 9090 port:

ngrok http 9090

You should see a response similar to this:

Now if you go to the .ngrok.io URL you should see the same response as the localhost:9090. Don’t forget to add the URL to your .env file APP_ENV

Registering the webhook

For this tutorial we are going to check for the presence of a register flag in the arguments list. You can add this to your code:

Here our bot is checking for the presence of -register in the argument list. Then it runs registerWebhook() as a goroutine. We are defining the registerWebhook() function in a client.go file which we will use for all Twitter requests. Now, for the function’s body:

So, a break down of the new code. The first thing is to create a CreateClient() function. This function returns a pointer to an OAuth http.Client that we can then use to make all Twitter requests on behalf of our bot’s account. Remember to run go get in the project folder so it can fetch the neat go library we use for all OAuth requests. In the registerWebhook function, we:

• Fetch a client
• Pass our webhook’s URL as a parameter using url.Values
• Make a post response to the register webhook endpoint then unmarshall (decode) and read the response

Next, we need our code to subscribe our webhook to events.

Note: You can use the account-activity-dashboard app created by Twitter for managing webhooks during development

Update your client.go file as shown below:

The code above is very straightforward. Cand heck after registering, subscribe to events and check for a status code of 204 . Now if you run go install on your code and run the code as hellobot -register you should get the following response:

Starting ServerRegistering webhook...Webhook id of <hook_id> has been registeredSubscribing webapp...Subscribed successfully

Listening for events

Now we need our webhook to actually to listen for events once the URL is called. Update your files as shown below:

What we are doing in the hellobot.dev is listening for post requests to our routes and passing them to the appropriate function. While in the client.go we are adding the appropriate structs we would use to parse the JSON payload to our bot.

Now update your code so it sends the tweet on the tag.

The updates we added to our source files are simply to respond to webhook events. Check if it was a tweet_create_event and send a response as a reply using the SendTweet() method in our client.go file.

Note: Any tweet being sent as a reply needs to include the handle of the user it is replying to as the initial content of the reply

Now if you run this with the appropriate credentials your bot should respond to tags and reply with “Hello World”.

Conclusion

Now that’s done, and since this is an extremely basic version of a bot, you can try adding a few things:

• Checking and ignoring retweet events
• Adding a name to the response
• Responding to the tweet in the case of an error anywhere on the app.

The code for this walkthrough is on Github here. Feel free to fork and play around with it

Cheers!

Imagine you are a product owner who wants to know what people are saying about your product in social media. Maybe your company launched a new product and you want to know how people reacted to it. You might want to use a sentiment analyzer like MonkeyLearn or Talkwalker. But wouldn’t it be cool if we could make our own sentiment analyzer? Let’s make it then!

In this tutorial, we are going to make a Telegram Bot that will do the sentiment analysis of tweets related to the keyword that we define.

If this is your first time building a Telegram Bot, you might want to read this post first.

Getting started

1. Install the libraries

We are going to use tweepy to gather the tweet data. We will use nltk to help us clean the tweets. Google Natural Language API will do the sentiment analysis. python-telegram-bot will send the result through Telegram chat.

pip3 install tweepy nltk google-cloud-language python-telegram-bot

2. Get Twitter API Keys

To be able to gather the tweets from Twitter, we need to create a developer account to get the Twitter API Keys first.

Go to Twitter Developer website, and create an account if you don’t have one.

Open Apps page, click “Create an app”, fill out the form and click “Create”.

Click on “Keys and tokens” tab, copy the API Key and API Secret Key in the “Consumer API keys” section.

Click the “Create” button under “Access token & access token secret” section. Copy the Access Token and Access Token Secret that have been generated.

Great! Now you should have four keys — API Key, API Secret Key, Access Token, and Access Token Secret. Save those keys for later use.

3. Enable Google Natural Language API

We need to enable the Google Natural Language API first if we want to use the service.

Go to Google Developers Console and create a new project (or select the one you have).

In the project dashboard, click “ENABLE APIS AND SERVICES”, and search for Cloud Natural Language API.

Click “ENABLE” to enable the API.

4. Create service account key

If we want to use Google Cloud services like Google Natural Language, we need a service account key. This is like our credential to use Google’s services.

Go to Google Developers Console, click “Credentials” tab, choose “Create credentials” and click “Service account key”.

Choose “App Engine default service account” and JSON as key type, then click “Create”.

There is a .json file that will be automatically downloaded, name it creds.json.

Set the GOOGLE_APPLICATION_CREDENTIALS with the path of our creds.json file in the terminal.

export GOOGLE_APPLICATION_CREDENTIALS='[PATH_TO_CREDS.JSON]'

If everything is good, then it’s time to write our program.

Write the program

This program will gather all the tweets containing the defined keyword in the last 24 hours with a maximum of 50 tweets. Then it will analyze the tweets’ sentiments one by one. We will send the result (average sentiment score) through Telegram chat.

This is a simple workflow of our program.

connect to the Twitter API -&gt; search tweets based on the keyword -> clean all of the tweets -> get tweet’s sentiment score -> send the result

Let’s make a single function to define each flow.

1. Connect to the Twitter API

The first thing that we need to do is gather the tweets’ data, so we have to connect to the Twitter API first.

Import the tweepy library.

import tweepy

Define the keys that we generated earlier.

ACC_TOKEN = 'YOUR_ACCESS_TOKEN'
ACC_SECRET = 'YOUR_ACCESS_TOKEN_SECRET'
CONS_KEY = 'YOUR_CONSUMER_API_KEY'
CONS_SECRET = 'YOUR_CONSUMER_API_SECRET_KEY'

Make a function called authentication to connect to the API, with four parameters which are all of the keys.

def authentication(cons_key, cons_secret, acc_token, acc_secret):
    auth = tweepy.OAuthHandler(cons_key, cons_secret)
    auth.set_access_token(acc_token, acc_secret)
    api = tweepy.API(auth)
    return api

2. Search the tweets

We can search the tweets with two criteria, based on time or quantity. If it’s based on time, we define the time interval and if it’s based on quantity, we define the total tweets that we want to gather. Since we want to gather the tweets from the last 24 hours with maximum tweets of 50, we will use both of the criteria.

Since we want to gather the tweets from the last 24 hours, let's take yesterday’s date as our time parameter.

from datetime import datetime, timedelta

today_datetime = datetime.today().now()
yesterday_datetime = today_datetime - timedelta(days=1)
today_date = today_datetime.strftime('%Y-%m-%d')
yesterday_date = yesterday_datetime.strftime('%Y-%m-%d')

Connect to the Twitter API using a function we defined before.

api = authentication(CONS_KEY,CONS_SECRET,ACC_TOKEN,ACC_SECRET)

Define our search parameters. q is where we define our keyword, since is the start date for our search, result_type='recent' means we are going to take the newest tweets, lang='en' is going to take the English tweets only, and items(total_tweets) is where we define the maximum tweets that we are going to take.

search_result = tweepy.Cursor(api.search, 
                              q=keyword, 
                              since=yesterday_date,
                              result_type='recent', 
                              lang='en').items(total_tweets)

Wrap those codes in a function called search_tweets with keyword and total_tweets as the parameters.

def search_tweets(keyword, total_tweets):
    today_datetime = datetime.today().now()
    yesterday_datetime = today_datetime - timedelta(days=1)
    today_date = today_datetime.strftime('%Y-%m-%d')
    yesterday_date = yesterday_datetime.strftime('%Y-%m-%d')
    api = authentication(CONS_KEY,CONS_SECRET,ACC_TOKEN,ACC_SECRET)
    search_result = tweepy.Cursor(api.search, 
                                  q=keyword, 
                                  since=yesterday_date, 
                                  result_type='recent', 
                                  lang='en').items(total_tweets)
    return search_result

3. Clean the tweets

Before we analyze the tweets sentiment, we need to clean the tweets a little bit so the Google Natural Language API can identify them better.

We will use the nltk and regex libraries to help us in this process.

import re
from nltk.tokenize import WordPunctTokenizer

We remove the username in every tweet, so basically we can remove everything that begins with @ and we use regex to do it.

user_removed = re.sub(r'@[A-Za-z0-9]+','',tweet.decode('utf-8'))

We also remove links in every tweet.

link_removed = re.sub('https?://[A-Za-z0-9./]+','',user_removed)

Numbers are also deleted from all of the tweets.

number_removed = re.sub('[^a-zA-Z]',' ',link_removed)

The last, convert all of the characters into lower space, then remove every unnecessary space.

lower_case_tweet = number_removed.lower()
tok = WordPunctTokenizer()
words = tok.tokenize(lower_case_tweet)
clean_tweet = (' '.join(words)).strip()

Wrap those codes into a function called clean_tweets with tweet as our parameter.

def clean_tweets(tweet):
    user_removed = re.sub(r'@[A-Za-z0-9]+','',tweet.decode('utf-8'))
    link_removed = re.sub('https?://[A-Za-z0-9./]+','',user_removed)
    number_removed = re.sub('[^a-zA-Z]', ' ', link_removed)
    lower_case_tweet= number_removed.lower()
    tok = WordPunctTokenizer()
    words = tok.tokenize(lower_case_tweet)
    clean_tweet = (' '.join(words)).strip()
    return clean_tweet

4. Get tweet’s sentiment

To be able to get a tweet’s sentiment, we will use Google Natural Language API.

The API provides Sentiment Analysis, Entities Analysis, and Syntax Analysis. We will only use the Sentiment Analysis for this tutorial.

In Google’s Sentiment Analysis, there are score and magnitude. Score is the score of the sentiment ranges from -1.0 (very negative) to 1.0 (very positive). Magnitude is the strength of sentiment and ranges from 0 to infinity.

For the sake of simplicity of this tutorial, we will only consider the score. If you are thinking of doing deep NLP analysis, you should consider the magnitude too.

Import the Google Natural Language library.

from google.cloud import language
from google.cloud.language import enums
from google.cloud.language import types

Make a function called get_sentiment_score which takes tweet as the parameter, and returns the sentiment score.

def get_sentiment_score(tweet):
    client = language.LanguageServiceClient()
    document = types\
               .Document(content=tweet,
                         type=enums.Document.Type.PLAIN_TEXT)
    sentiment_score = client\
                      .analyze_sentiment(document=document)\
                      .document_sentiment\
                      .score
    return sentiment_score

5. Analyze the tweets

Let’s make a function that will loop the list of tweets we get from search_tweets function and get the sentiment’s score of every tweet using get_sentiment_score function. Then we’ll calculate the average. The average score will determine whether the given keyword has a positive, neutral, or negative sentiment.

Define score equals to 0 , then use search_tweets function to get the tweets related to the keyword that we define.

score = 0
tweets = search_tweets(keyword, total_tweets)

Loop through the list of tweets, and do the cleaning using clean_tweets function that we created before.

for tweet in tweets:
    cleaned_tweet = clean_tweets(tweet.text.encode('utf-8'))

Get the sentiment score using get_sentiment_score function, and increment the score by adding sentiment_score.

for tweet in tweets:
    cleaned_tweet = clean_tweets(tweet.text.encode('utf-8'))
    sentiment_score = get_sentiment_score(cleaned_tweet)
    score += sentiment_score

Let’s print out each tweet and its sentiment so we can see the progress detail in the terminal.

for tweet in tweets:
    cleaned_tweet = clean_tweets(tweet.text.encode('utf-8'))
    sentiment_score = get_sentiment_score(cleaned_tweet)
    score += sentiment_score
    print('Tweet: {}'.format(cleaned_tweet))
    print('Score: {}\n'.format(sentiment_score))

Calculate the average score and pass it to final_score variable. Wrap all of the codes into analyze_tweets function, with keyword and total_tweets as the parameters.

def analyze_tweets(keyword, total_tweets):
    score = 0
    tweets = search_tweets(keyword, total_tweets)
    for tweet in tweets:
        cleaned_tweet = clean_tweets(tweet.text.encode('utf-8'))
        sentiment_score = get_sentiment_score(cleaned_tweet)
        score += sentiment_score
        print('Tweet: {}'.format(cleaned_tweet))
        print('Score: {}\n'.format(sentiment_score))
    final_score = round((score / float(total_tweets)),2)
    return final_score

6. Send the tweet’s sentiment score

Let’s make the last function in the workflow. This function will takes user’s keyword and calculate the average sentiment’s score. Then we’ll send it through Telegram Bot.

Get the keyword from the user.

keyword = update.message.text

Use analyze_tweets function to get the final score, keyword as our parameter, and set the total_tweets = 50 since we want to gather 50 tweets.

final_score = analyze_tweets(keyword, 50)

We define whether a given score is considered negative, neutral, or positive using Google’s score range, as we see in the image below.

_source: [https://cloud.google.com/natural-language/](https://cloud.google.com/natural-language/" rel="noopener" target="blank" title=")

if final_score <= -0.25:
    status = 'NEGATIVE ❌'
elif final_score <= 0.25:
    status = 'NEUTRAL ?'
else:
    status = 'POSITIVE ✅'

Lastly, send the final_score and the status through Telegram Bot.

bot.send_message(chat_id=update.message.chat_id,
                 text='Average score for '
                       + str(keyword) 
                       + ' is ' 
                       + str(final_score) 
                       + ' ' 
                       + status)

Wrap the codes into a function called send_the_result.

def send_the_result(bot, update):
    keyword = update.message.text
    final_score = analyze_tweets(keyword, 50)
    if final_score <= -0.25:
        status = 'NEGATIVE ❌'
    elif final_score <= 0.25:
        status = 'NEUTRAL ?'
    else:
        status = 'POSITIVE ✅'
    bot.send_message(chat_id=update.message.chat_id,
                     text='Average score for '
                           + str(keyword) 
                           + ' is ' 
                           + str(final_score) 
                           + ' ' 
                           + status)

7. Main program

Lastly, create another function called main to run our program. Don’t forget to change YOUR_TOKEN to your bot’s token.

from telegram.ext import Updater, MessageHandler, Filters

def main():
    updater = Updater('YOUR_TOKEN')
    dp = updater.dispatcher
    dp.add_handler(MessageHandler(Filters.text, send_the_result))
    updater.start_polling()
    updater.idle()

if __name__ == '__main__':
    main()

In the end, your code should look like this

import tweepy
import re

from telegram.ext import Updater, MessageHandler, Filters
from google.cloud import language
from google.cloud.language import enums
from google.cloud.language import types
from datetime import datetime, timedelta
from nltk.tokenize import WordPunctTokenizer


ACC_TOKEN = 'YOUR_ACCESS_TOKEN'
ACC_SECRET = 'YOUR_ACCESS_TOKEN_SECRET'
CONS_KEY = 'YOUR_CONSUMER_API_KEY'
CONS_SECRET = 'YOUR_CONSUMER_API_SECRET_KEY'

def authentication(cons_key, cons_secret, acc_token, acc_secret):
    auth = tweepy.OAuthHandler(cons_key, cons_secret)
    auth.set_access_token(acc_token, acc_secret)
    api = tweepy.API(auth)
    return api

def search_tweets(keyword, total_tweets):
    today_datetime = datetime.today().now()
    yesterday_datetime = today_datetime - timedelta(days=1)
    today_date = today_datetime.strftime('%Y-%m-%d')
    yesterday_date = yesterday_datetime.strftime('%Y-%m-%d')
    api = authentication(CONS_KEY,CONS_SECRET,ACC_TOKEN,ACC_SECRET)
    search_result = tweepy.Cursor(api.search, 
                                  q=keyword, 
                                  since=yesterday_date, 
                                  result_type='recent', 
                                  lang='en').items(total_tweets)
    return search_result

def clean_tweets(tweet):
    user_removed = re.sub(r'@[A-Za-z0-9]+','',tweet.decode('utf-8'))
    link_removed = re.sub('https?://[A-Za-z0-9./]+','',user_removed)
    number_removed = re.sub('[^a-zA-Z]', ' ', link_removed)
    lower_case_tweet= number_removed.lower()
    tok = WordPunctTokenizer()
    words = tok.tokenize(lower_case_tweet)
    clean_tweet = (' '.join(words)).strip()
    return clean_tweet

def get_sentiment_score(tweet):
    client = language.LanguageServiceClient()
    document = types\
               .Document(content=tweet,
                         type=enums.Document.Type.PLAIN_TEXT)
    sentiment_score = client\
                      .analyze_sentiment(document=document)\
                      .document_sentiment\
                      .score
    return sentiment_score

def analyze_tweets(keyword, total_tweets):
    score = 0
    tweets = search_tweets(keyword,total_tweets)
    for tweet in tweets:
        cleaned_tweet = clean_tweets(tweet.text.encode('utf-8'))
        sentiment_score = get_sentiment_score(cleaned_tweet)
        score += sentiment_score
        print('Tweet: {}'.format(cleaned_tweet))
        print('Score: {}\n'.format(sentiment_score))
    final_score = round((score / float(total_tweets)),2)
    return final_score

def send_the_result(bot, update):
    keyword = update.message.text
    final_score = analyze_tweets(keyword, 50)
    if final_score <= -0.25:
        status = 'NEGATIVE ❌'
    elif final_score <= 0.25:
        status = 'NEUTRAL ?'
    else:
        status = 'POSITIVE ✅'
    bot.send_message(chat_id=update.message.chat_id,
                     text='Average score for '
                           + str(keyword) 
                           + ' is ' 
                           + str(final_score) 
                           + ' ' 
                           + status)

def main():
    updater = Updater('YOUR_TOKEN')
    dp = updater.dispatcher
    dp.add_handler(MessageHandler(Filters.text, send_the_result))
    updater.start_polling()
    updater.idle()

if __name__ == '__main__':
    main()

Save the file and name it main.py, then run the program.

python3 main.py

Go to your telegram bot by accessing this URL: [https://telegram.me/YOUR_BOT_USERNAME](https://telegram.me/YOUR_BOT_USERNAME.). Type any product, person name, or whatever you want and send it to your bot. If everything runs, there should be a detailed sentiment score for each tweet in the terminal. The bot will reply with the average sentiment score.

The pictures below are an example if I type valentino rossi and send it to the bot.

the detailed sentiment score

the bot’s response

If you managed to follow the steps until the end of this tutorial, that’s awesome! You have your sentiment analyzer now, how cool is that!?

You can also check out my GitHub to get the code. Please do not hesitate to connect and leave a message in my Linkedin profile if you want to ask about anything.

Please leave a comment if you think there are any errors in my code or writing.

Thank you and good luck! :)

Telegram is a great platform with lots of great users (I’m a Telegram user myself). And what would be the best way for Telegram users to receive notifications? We can’t know for sure. Maybe they like email or something else. But we can guess that sending notifications to Telegram would be pretty convenient.

If you would like to send Telegram notifications from your application, you’ve come to the right place. I’ve added this feature to my application and I love it.

One quick note. In this article I provide examples of code in Python. But the ideas are not Python-specific and can be translated into another language without any hastle.

So without further ado, let’s dive into how we can do it.

Create a Telegram bot

First of all, you need to create a Telegram bot. To do this you need to use another Telegram bot, BotFather. Just talk to him (press start).

Now you see what it can do. But what interests us is creating a new bot, so that’s what we’re going to choose (/newbot).

You’re quickly going to find out that bot’s name should end with “bot”. And since you’re like me and coming to the game too late, most bot names are already taken.

But eventually, you’re going to find a name for your bot and get an access token we’re going to need.

Now that you have a bot, Telegram users can find and use it. But there is one problem — you can’t associate users that come from Telegram to the users in your application. Let me show you why.

Once a user presses the “Start” button on your bot, you will receive an “update”. You can check all bot’s updates even in your browser by visiting the following URL https://api.telegram.org/bot{bot_token}/getUpdates (don’t forget to use your access token in the URL). Here’s what I got:

Can’t read anything? Don’t worry. You can fix it by installing some JSON prettifier extension in your browser. I use JSON Formatter for Chrome. It looks so much better.

So as you can see we don’t get that much information about the person. From this information, we can get their full name. But it would be lucky if the user would provide their full name in your application, and doesn’t guarantee uniqueness of it. So we can’t use that to find a user in your applications.

Another piece of information we get is the username. That is more useful as it is unique between all Telegram users. But most likely you don’t have that available in your applications. So we would need to ask a user to enter their username somewhere in the application. It’s just too much work that I’m not sure anyone would do.

Another option to associate a user would be to ask them to provide the email that they used in your application to the bot. But this has too many flaws: the user can make a typo while entering the email, the user can enter the email of another user and exploit the system. This is just too bad.

Can we do better?

Associating a user

Of course we can. To associate the user, we’ll use a technique called deep linking.

First, you need to create a random unique token for each user. I’ve used the following code to generate the token using Python:

from secrets import token_urlsafetoken = token_urlsafe(8)token# => 'uEDbtJFHxKc'

Then you need to save that token to be able to find a user with it later. You can save it to your database or use some other place like a cache for example. I have a Notification model so I added a field to a model’s table.

class Notification(models.Model):    user = models.ForeignKey(User, on_delete=models.CASCADE)    # ...    connect_token = models.CharField(max_length=64, null=True)

So we’ve generated uEDbtJFHxKc token and saved it. Now we need to use this token in a URL to the telegram bot which the user needs to click to make it all work:

telegram_url = 'https://www.telegram.me'bot_name = 'music_notification_bot'token = 'uEDbtJFHxKc'url = f'{telegram_url}/{bot_name}?start={token}'

Now that we have our URL, 'https://telegram.me/music_notification_bot?start=uEDbtJFHxKc', it’s time to show it to the user. Just display it in any place of your application and wait for the user to click on it.

Once the user takes the bait and clicks “Start” you should receive another update:

{    "ok": true,    "result": [        // ...        // previous updates           // ...        {            "update_id": 599162365,            "message": {                "message_id": 174,                "from": { ... },                "chat": { ... },                "date": 1549788357,                "text": "/start uEDbtJFHxKc",                "entities": [ ... ]            }        }    ]}

We can finally identify our user. The text field now contains our user token. Let’s go ahead and take it out of this field:

bot_token = 'your_bot_token'updates_url = f'https://api.telegram.org/bot{bot_token}/getUpdates'import requestsresponse = requests.get(updates_url).json()text = response['result'][0]['message']['text']text# => '/start uEDbtJFHxKc'splitted_text = text.split(' ')# => ['/start', 'uEDbtJFHxKc']token = splitted_text[-1]# => 'uEDbtJFHxKc'

This token can be used to find the user. Your implementation depends on the way you saved the token in the first place. But here’s how I do it:

notification = Notification.objects.get(channel='telegram', connect_token=token)user = notification.user

So the user had pressed the “Start” button. But they see that nothing happened. Let’s welcome them at least.

To welcome the user we need to discover that the user had started a conversation with our bot. There are two options for how we can do that: polling and webhooks.

You already know what polling is. You’ve already done it. Or at least have seen me do it. Once we’ve checked out the https://api.telegram.org/bot{bot_token}/getUpdates page we did one poll. Polling is checking for updates constantly, every 2 seconds for example. This way we can always know when someone interacted with the bot.

Webhooks take a bit of a different direction. Instead of checking every 2 seconds for updates, we just wait for an update to happen. And when it happens Telegram will send a request with the update data to a URL that we specify. This way we can give both our and Telegram servers some rest and just wait for the update to come.

Polling can be better if you’ve got high traffic but, unfortunately, it’s rather an exception so I’ve decided to go with the webhook.

Webhooks

Setting a webhook in Telegram is very easy. You just need to send a request to https://api.telegram.org/bot{bot_token}/setWebhook?url={your_server_url}. Opening this link in your browser works too. your_server_url is the URL Telegram will send updates to. Here’s what you should get in the response:

{    "ok": true,    "result": true,    "description": "Webhook was set"}

If you don’t trust yourself you can visit https://api.telegram.org/bot{bot_token}/getWebhookInfo just to doublecheck that everything is OK. You should see something like this:

{    "ok": true,    "result": {        "url": "https://example.com/your_server_endpoint",        "has_custom_certificate": false,        "pending_update_count": 0,        "max_connections": 40    }}

Now. If something is not OK (like you’ve set a wrong URL) you can always delete the webhook by visiting [https://api.telegram.org/bot{bot_token}/deleteWebhook](https://api.telegram.org/bot{bot_token}/deleteWebhook) and then setting the webhook again.

Local development

Before continuing I would like to say a few words about local development. Webhooks are not very suitable for it. Webhooks are sent to a URL and most likely you don’t know your computer’s URL. Also, a Telegram webhook requires the URL to be secure (HTTPS).

But there is a solution to this problem: ngrok. ngrok is a tool that exposes your local environment to the world. Download ngrok, install it and start it with the port your server is running on. My server is running on 8000 port so I would need to run in a console

/path/to/ngrok http 8000

Then ngrok should give you a URL that you can use to set a webhook up.

Welcoming a user

Now that you’re ready to develop, let’s welcome our user — they’re waiting for it.

Once the user clicks “Start”, your Telegram will send an update to your server’s URL. The interesting parts of the update should look like this:

{    "message": {        "chat": {            "id": 457        },        "text": "/start uEDbtJFHxKc",    }}

This is a perfect time to associate the user using message text. There is also an interesting piece of information, chat ID. Chat ID is what we need to send a message to that user. Telegram has an API endpoint to send a message that looks like this https://api.telegram.org/bot{bot_token}/sendMessage?chat_id={chat_id}&text={text}. I’m not sure I need to explain how to use it but here’s what my code that processes the webhook looks like:

import jsonimport requestsdef callback(request):    body = json.loads(request.body)    text = body['message']['text']    token = text.split(' ')[-1]    associate_user_by_token(token)    bot_key = os.environ.get('TELEGRAM_API_KEY')    chat_id = body['message']['chat']['id']    text = "Welcome!"    send_message_url = f'https://api.telegram.org/bot{bot_key}/sendMessage?chat_id={chat_id}&text={text}'    requests.post(send_message_url)

If we send a welcome message after the user clicked the famous “Start” button, the user won’t have any second thoughts whether everything is working or not.

Pushing notifications

Finally, we get to the point why we’re doing all of this — push notifications. You may want to notify the user about some information that happened in your application. For example, someone liked the user’s post or whatever. I use Telegram to notify about new music releases from the user’s favorite artists.

You already know how to send notifications. You just need to send a message using [https://api.telegram.org/bot{bot_token}/sendMessage?chat_id={chat_id}&text={notification_text}](https://api.telegram.org/bot{bot_token}/sendMessage?chat_id={chat_id}&text={notification_text}.).

Of course, if you’re planning to send notifications not only when the user interacts with the bot, you need to save chat_id in your database.

You might also want to include links or some other formatting in your message. In this case, you would need to add another parameter to the send message URL, parse_mode. There are 2 parsing options: Markdown or HTML. I use Markdown since I find it simpler to use. If you’re not familiar with Markdown you can use HMTL, but I would recommend reading how easy Markdown is.

Here’s how the send message URL looks with parse_mode parameter [https://api.telegram.org/bot{bot_token}/sendMessage?chat_id={chat_id}&text={notification_text}&parse_mode=markdown](https://api.telegram.org/bot{bot_token}/sendMessage?chat_id={chat_id}&text={notification_text}&parse_mode=markdown.).

I add links to new releases to the notifications text like so {release.date}: {release.artist.name} - [{release.title}]({release.url}). You can read more about how to format you messages here.

Also, there are more parameters available for the send message URL like disable_notification. There is always a place to explore.

Conclusion

Now you should know how to

• create a bot in Telegram using BotFather
• check for updates (and what is a better way — webhooks or polling)
• associate user using deep linking
• send a welcome message and continue sending notifications
• format messages you send

Hopefully, this article was useful to you. This is the fifth part of a series of articles about the MuN. Stay tuned for part 6. You can find the code of this project, as well as my other projects, on my GitHub page. Leave your comments down below and follow me if you liked this article.

Originally published at https://kholinlabs.com/telegram-push-notifications on February 12, 2019.

A complete DIY guide to build your own weather alert bot.

The morning routine is always stressful. Wouldn’t it be wonderful if you had one less thing to worry about in the morning?

What if you had a customizable weather alert bot that sent you a short message ONLY when there was a chance of rain above your pre-defined threshold?

Don’t waste your time checking the weather in a separate app. It can be live on your Facebook messenger chatbox!

What do you need?

• Python 3.6 (or earlier) with pandas and fbchat packages installed

pip install fbchat

AccuWeather Free Account

• AccuWeather developer account, the free package should be enough. It provides 50 calls/day with 1 key/developer account.

Let’s get started!

At the end of this how-to, you will have 3 files in the scripts folder:

keys.py : to store your facebook email, password, and accuweather API key

params.py : to store the threshold and weather forecast location id

main.py : this is the main script, it will call the keys.py and params.py

1. Setup Facebook account and AccuWeather API key

First, let’s put your account detail in the keys.py file.

# Your Facebook usersname (email)
FB_USERNAME= "" 

# Your Facebook password
FB_PASSWORD= "" 

# Your AccuWeather API key
ACCUWEATHER_API_KEY= ""

2. Setup parameters

In this step, we will define the threshold for the probability of rain or snow, delay time between each request and message, and also location.

Currently, we set the threshold at 25% for both rain and snow. We will get the alert message only if the AccuWeather data shows the probability ≥ 25%.

The scripts below will request data from AccuWeather every 1 hour ( UPDATE_INTERVAL_HR= 1) and will send a message every 4 hours ( DELAY_TIME_HR= 4).

These parameters will be stored in the params.py file.

# Define % threshold for probability of rain and snow. 
# The msg will be sent out if the % chance exceed the value
RAIN_THRESHOLD = 25
SNOW_THRESHOLD = 25

# time between Accuweather request (in hour)
UPDATE_INTERVAL_HR = 1 

# delay time between msg (in hour)
DELAY_TIME_HR = 4 

# location id
# for example, https://www.accuweather.com/en/fr/lille/135564/weather-forecast/135564
# location id is 135564
LOCATION_ID = "135564"

3. Retrieve data from AccuWeather

Now here comes the fun part. We will now work on the main script.

If you plan to run it locally, setup your directory and import keys and params. Make sure you put keys.py and params.py in the same folder as this main.py script.

#set the current directory
import os
os.chdir(r".\YOUR_PATH")
###############################################################################
#import keys and parameters other scripts in the same folder
from keys import FB_USERNAME,FB_PASSWORD,ACCUWEATHER_API_KEY
from params import RAIN_THRESHOLD,SNOW_THRESHOLD,UPDATE_INTERVAL_HR,DELAY_TIME_HR,LOCATION_ID

Import required modules.

#import required modules
import urllib
import urllib.parse
import json
import time
import requests
import pandas as pd
import logging
import sys
from fbchat import Client
from fbchat.models import *
from datetime import datetime

Define ‘url_page’ to be requested, in this example, we will retrieve 12-hour hourly forecast. Convert our update/delay time into seconds.

url_page = "http://dataservice.accuweather.com/forecasts/v1/hourly/12hour/"+str(LOCATION_ID)+"?apikey="+ACCUWEATHER_API_KEY+"&details=true&metric=true"
#convert hours to seconds
update_interval_sec = 60*60*UPDATE_INTERVAL_HR 
delay_time_sec = 60*60*DELAY_TIME_HR

Then, request the data and put in pandas DataFrame called ‘json_df’.

At this point, we can inspect the retrieved table. Extract and rename the elements that we need. In this example, we will need AccuWeather link, % rain, % snow, date, and time in the desired format.

    json_page = urllib.request.urlopen(url_page)
    json_data = json.loads(json_page.read().decode())
    json_df = pd.DataFrame(json_data)

    # set maximum width, so the links are fully shown and clickable
    pd.set_option('display.max_colwidth', -1)
    json_df['Links'] = json_df['MobileLink'].apply(lambda x: '<a href='+x+'>Link</a>')

    json_df['Real Feel (degC)'] = json_df['RealFeelTemperature'].apply(lambda x: x.get('Value'))
    json_df['Weather'] = json_df['IconPhrase'] 
    json_df['Percent_Rain'] = json_df['RainProbability'] 
    json_df['Percent_Snow'] = json_df['SnowProbability']

If we look closely, the ‘DateTime’ column is a bit tricky to extract and needs some work. After clean up, save it in ‘current_retrieved_datetime’ variable.

json_df[['Date','Time']] = json_df['DateTime'].str.split('T', expand=True)
# trim the time to hh:mm format, change to str
json_df[['Time']] = json_df['Time'].str.split('+', expand=True)[0].astype(str).str[:5]

current_retrieved_datetime = str(json_df['Date'][0])+' '+str(json_df['Time'][0])

Next, write an if-else condition to customize the alert message. The retrieved table provides us a 12-hr forecast. We will check each element of both the rain and snow columns and return a message if the probability is above the threshold.

First, initialize the alert message for each case.

rain_msg=""
snow_msg=""

Check ‘Percent_Rain’ and ‘ Percent_Snow’ columns, flag with 1 if the % probability is above threshold (or 0 otherwise).

Sum the columns and modify the ‘rain_msg’ and ‘snow_msg’.

    # check % Rain column, return rain_msg
    json_df.loc[json_df['Percent_Rain'] >= RAIN_THRESHOLD, 'Rain_Alert'] = 1  
    json_df.loc[json_df['Percent_Rain'] < RAIN_THRESHOLD, 'Rain_Alert'] = 0
    if (sum(json_df['Rain_Alert']) > 0):
        rain_msg = 'There is ' \
                    +str(json_df['Percent_Rain'][json_df['Rain_Alert']==1][0]) \
                    +' % chance of rain' \
                    +' at ' \
                    +str(json_df['Time'][json_df['Rain_Alert']==1][0])

    # check % Snow column
    json_df.loc[json_df['Percent_Snow'] >= SNOW_THRESHOLD, 'Snow_Alert'] = 1  
    json_df.loc[json_df['Percent_Snow'] < SNOW_THRESHOLD, 'Snow_Alert'] = 0
    if (sum(json_df['Snow_Alert']) > 0):
        snow_msg = 'There is ' \
                    +str(json_df['Percent_Snow'][json_df['Percent_Snow']==1][0]) \
                    +' % chance of snow' \
                    +' at ' \
                    +str(json_df['Time'][json_df['Percent_Snow']==1][0])

Initialize ‘alert_msg’, modify the messages if there is any ‘rain_msg’ or ‘snow_msg’.

alert_msg =""
if(len(rain_msg)|len(snow_msg)!=0):
     alert_msg = rain_msg +" "+snow_msg

Add the link to variable ‘ link_for_click’ this will be attached to the message when we send later on.

link_for_click = json_df['MobileLink'][0]

Up until this point, we can now wrap them into a function. Don’t worry if you get lost, I have put them together below.

def func_get_weather(url_page):

    json_page = urllib.request.urlopen(url_page)
    json_data = json.loads(json_page.read().decode())
    json_df = pd.DataFrame(json_data)

    # set maximum width, so the links are fully shown and clickable
    pd.set_option('display.max_colwidth', -1)
    json_df['Links'] = json_df['MobileLink'].apply(lambda x: '<a href='+x+'>Link</a>')

    json_df['Real Feel (degC)'] = json_df['RealFeelTemperature'].apply(lambda x: x.get('Value'))
    json_df['Weather'] = json_df['IconPhrase'] 
    json_df['Percent_Rain'] = json_df['RainProbability'] 
    json_df['Percent_Snow'] = json_df['SnowProbability'] 
    json_df[['Date','Time']] = json_df['DateTime'].str.split('T', expand=True)
    # trim the time to hh:mm format, change to str
    json_df[['Time']] = json_df['Time'].str.split('+', expand=True)[0].astype(str).str[:5]

    current_retrieved_datetime = str(json_df['Date'][0])+' '+str(json_df['Time'][0])

    rain_msg=""
    snow_msg=""

    # check % Rain column, return rain_msg
    json_df.loc[json_df['Percent_Rain'] >= RAIN_THRESHOLD, 'Rain_Alert'] = 1  
    json_df.loc[json_df['Percent_Rain'] < RAIN_THRESHOLD, 'Rain_Alert'] = 0
    if (sum(json_df['Rain_Alert']) > 0):
        rain_msg = 'There is ' \
                    +str(json_df['Percent_Rain'][json_df['Rain_Alert']==1][0]) \
                    +' % chance of rain' \
                    +' at ' \
                    +str(json_df['Time'][json_df['Rain_Alert']==1][0])

    # check % Snow column
    json_df.loc[json_df['Percent_Snow'] >= SNOW_THRESHOLD, 'Snow_Alert'] = 1  
    json_df.loc[json_df['Percent_Snow'] < SNOW_THRESHOLD, 'Snow_Alert'] = 0
    if (sum(json_df['Snow_Alert']) > 0):
        snow_msg = 'There is ' \
                    +str(json_df['Percent_Snow'][json_df['Percent_Snow']==1][0]) \
                    +' % chance of snow' \
                    +' at ' \
                    +str(json_df['Time'][json_df['Percent_Snow']==1][0])

    alert_msg =""
    if(len(rain_msg)|len(snow_msg)!=0):
         alert_msg = rain_msg +" "+snow_msg

    link_for_click = json_df['MobileLink'][0]

    return(current_retrieved_datetime,alert_msg,link_for_click)

4. Automated loop

Finally, for the last part, we will automate the process by using loops. The scripts below are putting the number of loops as ‘num_repeat = 999’.

num_repeat = 999 # number of loops to repeat
previous_alert_msg = "" # initialize alert msg

Use try and except to overcome errors (just in case something goes wrong with connections). Call ‘func_get_weather’ function and assign to variables.

for i in range(num_repeat):
    try:
        current_retrieved_datetime,alert_msg,link_for_click = func_get_weather(url_page)
    except (RuntimeError, TypeError, NameError, ValueError, urllib.error.URLError):
        print('error catched')

Then, check if there are any changes in the weather. If nothing has changed, print the message to the screen. No chat message will be sent.

    #if the weather forecast has not changed, no alert msg will be sent
    if len(alert_msg) > 0 and previous_alert_msg == alert_msg:
        print(i, current_retrieved_datetime, 'no changes in weather forecast')

The message will be sent only if there is any change in the weather.

We can finalize our message at this point. Fetch your user id of your friends and store in ‘friend_list’. Loop to send the message to each friend one-by-one. We put sleep time = 2 seconds between each message and logout after finish.

    if len(alert_msg) > 0 and previous_alert_msg != alert_msg:    
        # login and send facebook msg 
        client = Client(FB_USERNAME,FB_PASSWORD)
        users = client.fetchAllUsers()
        friend_list=[user.uid for user in users if user.uid!="0"]
        # loop though all friends
        for id in friend_list: 
            client.send(Message(text=current_retrieved_datetime+' '+'12-hr Weather Forecast' +' '+ alert_msg +' '+link_for_click),thread_id=id, thread_type=ThreadType.USER)
            #sleep for 2 secs between each msg
            time.sleep(2) 
        #logout after sent
        client.logout()

Execute delay time for the next message. Already defined in params.py file — in this case, it is 4 hours. And another one for AccuWeather request delay is 1 hour.

    time.sleep(delay_time_sec)                         
time.sleep(update_interval_sec)

Again, don’t worry if you get lost. I have put the complete loop together below.

# Execute functions, retrieve data and send facebook msg
num_repeat = 999 # number of loops to repeat
previous_alert_msg = "" # initialize alert msg
for i in range(num_repeat):

    try:
        current_retrieved_datetime,alert_msg,link_for_click = func_get_weather(url_page)
    except (RuntimeError, TypeError, NameError, ValueError, urllib.error.URLError):
        print('error catched')

    #if the weather forecast has not changed, no alert msg will be sent
    if len(alert_msg) > 0 and previous_alert_msg == alert_msg:
        print(i, current_retrieved_datetime, 'no changes in weather forecast')
    #if there is any changes in weather       
    if len(alert_msg) > 0 and previous_alert_msg != alert_msg:    
        # login and send facebook msg 
        client = Client(FB_USERNAME,FB_PASSWORD)
        users = client.fetchAllUsers()
        friend_list=[user.uid for user in users if user.uid!="0"]
        # loop though all friends
        for id in friend_list: 
            client.send(Message(text=current_retrieved_datetime+' '+'12-hr Weather Forecast' +' '+ alert_msg +' '+link_for_click),thread_id=id, thread_type=ThreadType.USER)
            #sleep for 2 secs between each msg
            time.sleep(2) 
        #logout after sent
        client.logout()    
        time.sleep(delay_time_sec)                         
    time.sleep(update_interval_sec)
print(current_retrieved_datetime,'Run Completed')

Ta-da! After all our hard work, here is a snapshot of the message we will get.

Facebook chatbox msg. The location id in this example is 135564.

In case we need to know more detail, we can directly click on the link. It will navigate to the AccuWeather mobile website.

AccuWeather Link

The completed script for this how-to is also documented on GitHub.

Thank you for reading. Please give it a try, have fun and let me know your feedback!

If you like what I did, consider following me on GitHub, Medium, and Twitter. Make sure to star it on GitHub :D

Imagine this, there is a message bot that will send you a random cute dog image whenever you want, sounds cool right? Let’s make one!

For this tutorial, we are going to use Python 3, python-telegram-bot, and public API RandomDog.

At the end of this tutorial, you will have a stress relieving bot that will send you cute dog images every time you need it, yay!

Getting started

Before we start to write the program, we need to generate a token for our bot. The token is needed to access the Telegram API, and install the necessary dependencies.

1. Create a new bot in BotFather

If you want to make a bot in Telegram, you have to “register” your bot first before using it. When we “register” our bot, we will get the token to access the Telegram API.

Go to the BotFather (if you open it in desktop, make sure you have the Telegram app), then create new bot by sending the /newbot command. Follow the steps until you get the username and token for your bot. You can go to your bot by accessing this URL: [https://telegram.me/YOUR_BOT_USERNAME](https://telegram.me/YOUR_BOT_USERNAMEa) and your token should looks like this.

704418931:AAEtcZ*************

2. Install the library

Since we are going to use a library for this tutorial, install it using this command.

pip3 install python-telegram-bot

If the library is successfully installed, then we are good to go.

Write the program

Let’s make our first bot. This bot should return a dog image when we send the /bop command. To be able to do this, we can use the public API from RandomDog to help us generate random dog images.

The workflow of our bot is as simple as this:

access the API -> get the image URL -> send the image

1. Import the libraries

First, import all the libraries we need.

from telegram.ext import Updater, CommandHandler
import requests
import re

2. Access the API and get the image URL

Let’s create a function to get the URL. Using the requests library, we can access the API and get the json data.

contents = requests.get('https://random.dog/woof.json').json()

You can check the json data by accessing that URL: https://random.dog/woof.json in your browser. You will see something like this on your screen:

{“url":"https://random.dog/*****.JPG"}

Get the image URL since we need that parameter to be able to send the image.

image_url = contents['url']

Wrap this code into a function called get_url() .

def get_url():
    contents = requests.get('https://random.dog/woof.json').json()    
    url = contents['url']
    return url

3. Send the image

To send a message/image we need two parameters, the image URL and the recipient’s ID — this can be group ID or user ID.

We can get the image URL by calling our get_url() function.

url = get_url()

Get the recipient’s ID using this code:

chat_id = update.message.chat_id

After we get the image URL and the recipient’s ID, it’s time to send the message, which is an image.

bot.send_photo(chat_id=chat_id, photo=url)

Wrap that code in a function called bop , and make sure your code looks like this:

def bop(bot, update):
    url = get_url()
    chat_id = update.message.chat_id
    bot.send_photo(chat_id=chat_id, photo=url)

4. Main program

Lastly, create another function called main to run our program. Don’t forget to change YOUR_TOKEN with the token that we generated earlier in this tutorial.

def main():
    updater = Updater('YOUR_TOKEN')
    dp = updater.dispatcher
    dp.add_handler(CommandHandler('bop',bop))
    updater.start_polling()
    updater.idle()

if __name__ == '__main__':
    main()

At the end your code should look like this:

from telegram.ext import Updater, InlineQueryHandler, CommandHandler
import requests
import re

def get_url():
    contents = requests.get('https://random.dog/woof.json').json()    
    url = contents['url']
    return url

def bop(bot, update):
    url = get_url()
    chat_id = update.message.chat_id
    bot.send_photo(chat_id=chat_id, photo=url)

def main():
    updater = Updater('YOUR_TOKEN')
    dp = updater.dispatcher
    dp.add_handler(CommandHandler('bop',bop))
    updater.start_polling()
    updater.idle()

if __name__ == '__main__':
    main()

5. Run the program

Awesome! You finished your first program. Now let’s check if it works. Save the file, name it main.py , then run it using this command.

python3 main.py

Go to your telegram bot by accessing this URL: https://telegram.me/YOUR_BOT_USERNAME. Send the /bop command. If everything runs perfectly the bot will reply with a random dog image. Cute right?

One random generatedly image

Handling errors

Great! Now you have a bot that will send you a cute dog image whenever you want.

There is more! The RandomDog API not only generates images, but also videos and GIFs. If we access the API and we get a video or GIF, there is an error and the bot won’t send it to you.

Let’s fix this so the bot will only send a message with an image attachment. If we get a video or GIF then we will call the API again until we get an image.

1. Match the file extension using regex

We are going to use a regex to solve this problem.

To distinguish an image from video or GIF, we can take a look at the file extension. We only need the last part of our URL.

https://random.dog/*****.JPG

We need to define, first, what file extensions are allowed in our program.

allowed_extension = ['jpg','jpeg','png']

Then use the regex to extract the file extension from the URL.

file_extension = re.search("([^.]*)$",url).group(1).lower()

Using that code, make a function called get_image_url() to iterate the URL until we get the file extension that we want (jpg,jpeg,png).

def get_image_url():
    allowed_extension = ['jpg','jpeg','png']
    file_extension = ''
    while file_extension not in allowed_extension:
        url = get_url()
        file_extension = re.search("([^.]*)$",url).group(1).lower()
    return url

2. Modify your code

Great! Now for the last part, replace the url = get_url() line in the bop() function with url = get_image_url() , and your code should look like this:

from telegram.ext import Updater, InlineQueryHandler, CommandHandler
import requests
import re

def get_url():
    contents = requests.get('https://random.dog/woof.json').json()    
    url = contents['url']
    return url

def get_image_url():
    allowed_extension = ['jpg','jpeg','png']
    file_extension = ''
    while file_extension not in allowed_extension:
        url = get_url()
        file_extension = re.search("([^.]*)$",url).group(1).lower()
    return url

def bop(bot, update):
    url = get_image_url()
    chat_id = update.message.chat_id
    bot.send_photo(chat_id=chat_id, photo=url)

def main():
    updater = Updater('YOUR_TOKEN')
    dp = updater.dispatcher
    dp.add_handler(CommandHandler('bop',bop))
    updater.start_polling()
    updater.idle()

if __name__ == '__main__':
    main()

Nice! Everything should run perfectly. You can also check out my GitHub account to get the code.

Finally, congratulations for finishing this tutorial, plus you have a cool Telegram bot now.

Please leave a comment if you think there are any errors in my code or writing, because I’m still learning and I want to get better.

Thank you and good luck practicing! :)

A quick guide that helps you avoid common pitfalls

Building a bot is a rewarding experience: creating your own artificial intelligence is amazing!

However, it can be a challenge, and there are mistakes to avoid. In this piece, we’re going to walk you through the most common or damaging mistakes new bot builders make in each phase of bot building: conception, training, building, connection, user experience and maintenance. Let’s roll!

Conception

Building a bot doesn’t start at the first line of code. It starts much earlier, during the conception.

During that first step, it’s important to define the use case of your chatbot. What is the problem you want it to solve? What are your business needs?

We often see people saying “I want a bot that does this”, but when we dig deeper, we realize a different bot would actually fix the issue much more efficiently. If you want to build a chatbot that manages customers’ questions on return policies, but later realize that these queries are less than 2% of your global volume, you might want to switch to another topic. So, start from the business problem and build from there.

Now that you’ve established the real-life business need, how should the bot conversation flow go to solve it? What we usually do is take out a drawing board and draw all the conversation flows, from start to finish. Modeling all possibilities allows you to make sure every topic is covered and gives the developer a good overview of what needs to be done. It is also the first step of creating your user experience, which we’ll talk about later. For now, simply keep in mind that each conversation should be about 3 or 4 exchanges, no more.

During this step, remember your audience: who are the end-users that will be talking to your bot? You have to make something that works for them.

Do not forget to include small talk in your conception. All chatbots are expected to understand and reply to a number of topics unrelated to their mission: jokes, weather questions, “how are you doing”, and even remarks like “will you marry me” or other off-topic stuff. Be sure to plan for those if you want the user to be satisfied with the experience. But no worries, we provide pre-trained small-talk Skills on SAP Conversational AI.

What not to do when building a bot:

1. Disregard it as a non-important step

2. Start from what you want and not from what you need

3. Incorrectly understand who the final users of the bot will be and design an experience they won’t appreciate

4. Not include small talk and other commonly asked questions

Training

Training the bot is the most important factor in determining its performance. Bad training will inevitably lead to a poor performing chatbot and frustrated users.

Based on the flow you’ve created during conception, training consists of creating intents and filling them with expressions. If you’re not comfortable with the concept of intents and expressions, this article should help you. But here are some things that make for good training.

The number of expressions in each intent is crucial. Five doesn’t cut it, you should go for 50+. SAP Conversational AI works very well on small datasets, but we still need a bit of information. These sentences should be varied and should come from end users. Never train your bot only with the development and project team: they know the technical slang too well to accurately represent the people that will actually use the bot.

Tagging entities has a few rules as well. Entities are keywords that you need to detect in a sentence to extract information (the key point here being “to extract information”). You don’t need to tag every noun, adjective or word per sentence just because you can! The point of entities is to extract relevant information that you can use in your code. Only tag those.

However, avoid having sentences that are only made of one word that is an entity (e.g. “Paris” as a complete sentence). This entity can be detected by any intent, which can lead to detection issues.

A common best practice for big bots is to use intents and entities hand in hand. It is better to create a global intent and use entities to specify the user request, than to create very specific intents that the classifier will confuse as they overlap.

Here, the global intent is troubleshooting, but entities detect which product isn’t functioning.

What not to do when building a bot:

5. Have less than 50 expressions per intent

6. Train your bot by people who are not the end-user

7. Tag every word in a sentence as an entity

8. Tag words as entities when you don’t use the extracted information

9. Have expressions that are only entities (i.e “Paris”)

10. Create very specific intents instead of using entities to understand the topic

Building

Building a bot is often assumed to involve just building the conversation flow. It is the fun part! It’s when everything comes to life. However, it can be a scary process.

The first thing to understand is that it’s ok to use multiple skills to complete one task. One skill doesn’t have to equal one full process. It can be a good solution to create one “mega-skill” whose job is to dispatch the user input to the correct skill.

In our troubleshooting (ts) example, a mega-skill redirects to the different skills that manage the specific procedures

That is also a solution if you have skills with triggers that overlap each other. And if something doesn’t work, be sure to use the logs in the debug console to understand where the problem is coming from.

What not to do when building a bot:

11. Insist on the “one skill = one task” philosophy

12. Not leverage the debugging tools of the platform

Connecting and User Experience

When connecting your bot, you have to decide where it is going to be available to your users, and therefore work on a user experience. There are a few things to know to provide an enjoyable UX, the first one being: your bot has to look pretty. An attractive bot with plenty of buttons, graphic elements, HD pictures, colors, and a good personality makes all the difference.

But how do you get that?

First, think of your audience when you choose your channel. If you’re targeting the 50 to 65 age demographics, you’re probably not going to put your bot on Kik! Don’t try to attract your audience to a channel they don’t use, even if it’s better. Instead, integrate the bot where your users already are.

Then, keep in mind a chatbot is a conversational interface. Conversations are interactive exchanges; therefore, your bot should never reply with long-winded blocks of texts (more than 60 characters is getting long).

Separate replies into different messages, use images, buttons, lists and other UX components based on the channel you use to make it lively. It’s also important to create a rewarding conversation: your bot isn’t an FBI agent. Nobody wants to be asked 20 questions before getting an answer. Instead, create your flow and UX to provide an answer every 3 or 4 exchanges to keep the user engaged.

Since we provide a powerful natural language processing API with our bot building tool, our users tend to want to do everything through language. While that’s admirable, we still advise to diversify: offer cards, buttons and other graphic elements for interactivity and ease of use, but still make sure the entire flow can be done using natural language. That’s when users know your bot is the real deal.

Giving a personality to your chatbot is essential, however you have to find the right balance. We always advise to let your users know they’re talking to a bot. It’s simply expectation management!

A human talking to another human is going to expect the highest level of interaction, whereas a human talking to a bot is going to know that they can’t ask about anything and everything. However, don’t make it too robotic: give it a name, an image, and use smileys and tone of voice to make it memorable.

What not to do when building a bot:

13. Mis-identify the channel your audience is using

14. Create conversations where the user has to answer 4+ questions to get a first answer

15. Send blocks of texts as replies (more than 60 characters is too much)

16. Discard all UX elements (buttons, cards, lists, etc) just to focus on text

17. Pass your bot as a human person

18. Not giving your bot a personality that attracts your audience

Maintenance

Once your bot is in production, your job is not done! Maintaining your bot is an essential part of its long-lasting success. That mainly consists of fine-tuning your training and monitoring what your users are saying to adapt your flow or create new use cases.

When training, proceed with caution. While it is important to add new user sentences via the log feed, you do not want to unbalance the training you’ve created that already works. Don’t swamp your intents by adding all the new expressions, only add what’s necessary. Keep in mind that all intents have to be trained the same amount! If one intent has 100 expressions and the other has 10, that’s no good. Therefore, check regularly when assigning new expressions. Our training analytics are your best friend when it comes to improving your training data!

Finally, your log feed is the place where you can see what users are talking about. Do you see a topic that your users are raising frequently that your bot doesn’t yet manage? Why not integrate it into your flow? That’s the best way to show your community that the bot they’re using is always striving to provide a great experience.

What not to do when building a bot:

19. Thinking that once the bot is in production, your job is done

20. Overflow intents with new user expression and mess up your existing training

21. Create inequalities in your intent size

22. Not pay attention to how people are using your bot

With all this in mind, you are fully on-board to build a first kick-ass bot! If you’re ready to go further, this step-by-step tutorial can guide you through the actual process to build an awesome joke-telling chatbot!

Happy building!

Originally published on SAP Conversational AI Blog.

Why create a Slack Bot ?

I am an HR professional. More specifically I am a Human Resources Information System (HRIS) Consultant. I work with Application Tracking Systems, Learning Management Systems, and Core HR. But I have never had the opportunity to work with an HR Bot. Which may be the Future of HR.

I read a lot about bots on Slack and Messenger, and used some of them in my daily life — Product Hunt, GitHub and Trello. But for HR purposes, I have never had the opportunity to work with a tool tailored for my needs.

That’s why I decided to work on my own bot.

Me starting to work

My Goals

My bot should be able to manage all the needs a small company could have on Slack:

• Onboarding
• Putting people in touch
• Reminders
• Announcements
• Birthdays /Anniversary
• And many more

Reviewing the basics

For this program, I’ll use:

• Botkit
• Node JS
• Express Server
• MongoDB
• Slack API & of course

Botkit is:

One easy way to build bot users, especially if you already work with Node.js, is Howdy’s Botkit. Botkit is a framework that takes care of most these API gymnastics, so you can focus on your bot’s behavior.

Exactly what I was looking for :-)

Botkit provides a boilerplate for Slack. But I have chosen to start from scratch to have a better understanding of my bot. However, it’s a good idea to train yourself with a bot created on Glitch.

How do Slack bots work?

I am not an expert. I have read again and again Slack and Botkit’s official documentation. I’m still not sure I understood everything. Here is my understanding of a Slack bot’s behavior:

Every App on Slack has a “scope” which is a perimeter on which an app can read or perform actions. A bot is part of an application created and installed on Slack.

Therefore, when you install an app on Slack, you give access to some information and permissions to it. For your bot, you want it to be, at least, able to send and reply to messages of other users.

There are then two cases:

1. You want your bot to react to events happening directly in Slack
2. You want your bot to react to events happening on your server

We will view both of them in this post!

Getting Started

Before anything else, you will need a server. In my case, Express.

Below you’ll find my server.js file:

var express = require('express');
var app = express();
var http = require('http').Server(app);
var dotenv = require('dotenv');

// configuration ===========================================
//load environment variables,
dotenv.load();

// public folder for images, css,...
app.use(express.static(__dirname + '/public'))

//parsing
app.use(bodyParser.json()); // for parsing application/json
app.use(bodyParser.urlencoded({
    extended: true
})); //for parsing url encoded

// view engine ejs
app.set('view engine', 'ejs');

// routes
require('./routes/routes')(app);

//botkit
require('./controllers/botkit')


//START ===================================================
http.listen(app.get('port'), function() {
    console.log('listening on port ' + app.get('port'));
});

This port must be public and accessible, not just on a localhost.

For the moment, this server is a blank page, showing and processing nothing.

You’ll then need a Slack App: just follow this link to create one.

Then, you’ll have to configure your controller. The controller is the brain of your bot. It contains every skill and configuration. Below is my botkit.js file. It has almost the same content found in Botkit’s Starter kit available here: https://github.com/howdyai/botkit-starter-slack

var mongoUri = 'mongodb://localhost:27017/nameofyourDB'
var database = require('../config/database')({
    mongoUri: mongoUri
})
var request = require('request')

if (!process.env.SLACK_ID || !process.env.SLACK_SECRET || !process.env.PORT) {
    console.log('Error: Specify SLACK_ID SLACK_SECRET and PORT in environment');
    process.exit(1);
}

var controller = Botkit.slackbot({
    storage: database,
    clientVerificationToken: process.env.SLACK_TOKEN
})

exports.controller = controller

//CONNECTION FUNCTIONS=====================================================

exports.connect = function(team_config) {
        var bot = controller.spawn(team_config);
        controller.trigger('create_bot', [bot, team_config]);
    }
    // just a simple way to make sure we don't
    // connect to the RTM twice for the same team
var _bots = {};

function trackBot(bot) {
    _bots[bot.config.token] = bot;
}

controller.on('create_bot', function(bot, team) {
    if (_bots[bot.config.token]) {
        // already online! do nothing.
        console.log("already online! do nothing.")
    } else {
        bot.startRTM(function(err) {
            if (!err) {
                trackBot(bot);
                console.log("RTM ok")
                controller.saveTeam(team, function(err, id) {
                    if (err) {
                        console.log("Error saving team")
                    } else {
                        console.log("Team " + team.name + " saved")
                    }
                })
            } else {
                console.log("RTM failed")
            }
            bot.startPrivateConversation({
                user: team.createdBy
            }, function(err, convo) {
                if (err) {
                    console.log(err);
                } else {
                    convo.say('I am a bot that has just joined your team');
                    convo.say('You must now /invite me to a channel so that I can be of use!');
                }
            });
        });
    }
});

//REACTIONS TO EVENTS==========================================================
// Handle events related to the websocket connection to Slack

controller.on('rtm_open', function(bot) {
    console.log('** The RTM api just connected!')
});

controller.on('rtm_close', function(bot) {
    console.log('** The RTM api just closed');
    // you may want to attempt to re-open
});

Unlocking the first case: react to the events happening on Slack

When you give the right permissions to your app, every time a message is sent on a channel, Slacks sends a request to your server with some information — the channel ID, the user, the timestamp and most importantly, the content of the message.

If we want our bot to react to a simple message like “Hi”, we have to give Slack an address to send the information to.

In a routes.js file write:

var Request = require('request')
var slack = require('../controllers/botkit')
module.exports = function(app) {
 app.post('/slack/receive', function(req,res){
//respond to Slack that the webhook has been received.
    res.status(200);
// Now, pass the webhook into be processed
    slack.controller.handleWebhookPayload(req, res)
  })
}

We now have a webhook : http://your-ip-or-domain:port/slack/receive

Once Slack is informed of this route via the Event Subscriptions page of your Slack App, it will be able to send it JSON. You will be able to receive it thanks to the parsing part of the server.js file above.

Here is a (simple) schema to explain the process behind it:

1- SLACK « Here is a JSON file with the latest event on your Slack Channel »

2- SERVER « Okay well received, I send it to Botkit»

3- BOTKIT «Here is a temporary answer, wait a second»

4- BOTKIT « Yeah! I hear a keyword, here is a JSON object with the action to perform »

If we want our bot to react every time it hears “Hello”, we can simply add this .hears() function to our controller:

controller.hears(['hello', 'hi'], 'direct_message,direct_mention,mention', function(bot, message) {
controller.storage.users.get(message.user, function(err, user) {
        if (user && user.name) {
            bot.reply(message, 'Hello ' + user.name + '!!');
        } else {
            bot.reply(message, 'Hello.');
        }
    });
});

Notice the storage.users.get() part in this snippet. Botkit is compatible with almost all the database systems available on the market. I have decided to use MongoDB because it was on my learning list for a long time. Plus the documentation with Botkit is detailed.

Now, we have to let our imagination do the work and find some fun features to create.

Second Case: initiate a conversation with your bot

For this feature, I wanted my bot to react to events which were not initiated on Slack. For example, do a daily routine. If it’s someone’s anniversary in the company, send them a survey asking their feelings about their first months/weeks.

I have decided to use node-cron: https://github.com/kelektiv/node-cron to manage the daily check.

Here is below a cronjob firing every weekday at 9:00 am. Thanks to the Date() method, the bot gets today’s date and can compare it to the “joinedDate” of the user.

To get only the right users and avoid a forEach loop, we can use a query on our Database:

var dailyCheck = new CronJob('00 00 9 * * 1-5', function() {
        /*
         * Runs every weekday (Monday through Friday)
         * at 09:00:00 AM. It does not run on Saturday
         * or Sunday.
         */
        console.log(`DailyCheck triggered ${new Date()}`)

        //Gets today's date
        let d = new Date()
        d.setUTCHours(0, 0, 0, 0)

        let threeMonthsAgo = new Date()
        threeMonthsAgo.setUTCMonth(d.getUTCMonth() - 3)
        threeMonthsAgo.setUTCHours(0, 0, 0, 0)


        let sevenDaysAgo = new Date()
        sevenDaysAgo.setUTCDate(d.getUTCDate() - 7)
        sevenDaysAgo.setUTCHours(0, 0, 0, 0)


        controller.storage.users.find({
            "joinedDate": {
                "$eq": +sevenDaysAgo
            }
        }, function(err, user) {
            user.forEach(function(member) {
                console.log(`Message was sent to ${member.name}(${member.id})`)
                bot.startPrivateConversation({
                    user: member.id
                }, Conversations.sendSurvey7)
            })
        })
    }, function() {
        /* This function is executed when the job stops */
    }, true,
    /* Start the job right now */
    timeZone = 'Europe/Paris' /* Time zone of this job. */ )

And… Tada!

_“A robot named Pepper holding an iPad” by [Unsplash](https://unsplash.com/@agkdesign?utm_source=medium&utm_medium=referral" rel="noopener" target="_blank" title="">Alex Knight on <a href="https://unsplash.com?utm_source=medium&utm_medium=referral" rel="noopener" target="blank" title=")

Conclusion

After more than a year of being a camper and learning to code, I am really happy to be able to start and finish a project like this one. I now have a bot working and performing almost all the actions I had in mind at the design phase. And I still have a lot of ideas!

I am still working on this bot. The GitHub repository is available here: https://github.com/alexandrobin/hrbot. Some of the commits are in French, but the codebase is commented in English. :-)

Besides, it’s quite easy to deploy it on Heroku with a Mongolab database if you don’t have a server!

If you have some suggestions or are interested by this article and project, feel free to leave a comment ! I would be happy to discuss with you.

In this article, I will go over how I built my Twitter lyric bot and how you’ll be able to set up your very own.

Procedure

Here’s a list of the components we have to set up.

1. Twitter Account
2. Text Editor/IDE
3. The bot
4. Heroku Automation

Setup New Twitter Application

To create a new Twitter application, go here. You will need to apply for developer access. After you submit the application, it may take a while but Twitter will notify you when you get accepted.

Setup Editor/IDE

Now you’re going to want to set up your editor. My preference is VS Code, so that’s what I’ll be using.

Make sure you have Git and Node installed.

Go ahead clone the following git repository to your computer.

git clone https://github.com/ShawnToubeau/lyric-bot.git

Code Walk Trough

The 3 main files that the bot consists of are bot.js, lyrics.txt, and .env.

SideNote: Your clone of the project will not contain a .env file because of the .gitignore, thus we will be creating our own later down in the article!

bot.js

Starting in bot.js, we start by importing Twit, fs, and dotenv.

Twit is a module that supports the Twitter Developer API.

Fs, or file system, is a file I/O nodule that allows us to interact with our lyrics.txt file.

Dotenv is a module that reads in environment variables stored in our .env file.

const Twit = require('twit');

const fs = require('fs');

require('dotenv').config();

const order = 4; // length of each n-gram

let nGrams = {};

const Bot = new Twit({

  consumer_key: process.env.TWITTER_CONSUMER_KEY,

  consumer_secret: process.env.TWITTER_CONSUMER_SECRET,

  access_token: process.env.TWITTER_ACCESS_TOKEN,

  access_token_secret: process.env.TWITTER_ACCESS_TOKEN_SECRET

});

nGrams is the object that keeps track of substring occurrences so that we are able to use a probability to generate our own lyrics randomly. You can read more about them here.

And Bot is…well...our Bot! We need to define some variables to make it work. Using the dotenv module, we can grab the values stored in our .env file.

Next we define a few functions as follows:

pickRandomStart()

function pickRandomStart(lyrics) {

  const random = Math.floor(Math.random()*lyrics.length)

  return lyrics.substring(random, random + order)

}

This selects the starting point for where we grab our first n-gram.

makeEngramModel()

function makeEngramModel(lyrics) {

  for (let i = 0; i < lyrics.length - order; i++) {

    const gram = lyrics.substring(i, i + order);

    if (!nGrams[gram]) {

    nGrams[gram] = [];

    }

    nGrams[gram].push(lyrics.charAt(i + order));

  }

}

This creates the model that tracks the order and occurrences of all the n-grams parsed from the lyrics. By using the number of occurrences as the n-gram’s probability, it allows us to generate new lyrics in a random order.

tweet()

function tweet() {

  fs.readFile('lyrics.txt', 'utf8', function(error, lyrics) {

  if (error) {

  console.log(error.message);

  } else {

    makeEngramModel(lyrics);

    let currentGram = pickRandomStart(lyrics);

      // checks to see if the start of the tweet doesn't start

      // with punctuation or special characters and ends with a space

      while (!currentGram.match(/^[0-9a-zA-Z]+$/)) {

        currentGram = pickRandomStart(lyrics);

      }

      let tweet = currentGram;

      // runs until char limit is reached while finishing the last word it was on

      for (let j = 0; (j < 150) || (tweet.charAt(j).match(/^[0-9a-zA-Z]+$/)); j++) {

        const possibilities = nGrams[currentGram];

        const next = possibilities[Math.floor(Math.random()*possibilities.length)];

        tweet += next;

        const len = tweet.length;

        currentGram = tweet.substring(len-order, len);

      }

      console.log(tweet)

      Bot.post('statuses/update', {status: tweet}, function(error, tweet, response) {

        if (error) {

          console.log("Error making post. ", error.message);

        };

      });

    }

  });

}

Last but not least, this is the part that interacts with the bot. It starts by reading in the lyrics using the fs module and then it create the n-gram model using the lyrics variable. It selects a random starting point to use as the first n-gram which will be the start of the new lyrics. It performs a check to see whether the first n-gram contains only alphanumeric characters, because then it has a higher chance to start somewhat more sensical.

It then chains randomly selected n-grams that pair with the last n-gram added to the tweet variable. It does this for at least 150 characters and like before, performs a check to see if it will end on an alphanumeric n-gram. If it does not end on a alphanumeric n-gram, it then will keep chaining from the model until it does.

And finally the bot makes a post request with the lyrics as the tweet payload.

Now that we have a good idea how how our code works, run the following command:

npm install

in the lyric-bot project folder.

This installs the necessary modules () // and explains what npm install does.

Configuration

Now you’ll want to copy in a set of lyrics into the lyrics.txt file.

Then create a .env file. This will store your Twitter API tokens.

Inside the new file, paste the following:

TWITTER_CONSUMER_KEY=

TWITTER_CONSUMER_SECRET=

TWITTER_ACCESS_TOKEN=

TWITTER_ACCESS_TOKEN_SECRET=

and copy the respective tokens from your app’s developer console, once you get your developer application approved.

Time to test it!

Type

node bot.js

And take a look at the console!

Lyric sample created from Dailily by Movements

And check out the Twitter account too, of course:

The tweet sent from the bot to the Twitter API

TA DA!

You now have a working twitter bot that is able to post newly generated song lyrics! ?

Hold on though, we still have to automate it…

Heroku Deployment

Go over to Heroku.com and login. If you don’t have an account, you can create a free one! ?

Now, from the main dashboard, create a new app by clicking New->Create new app.

Enter an available name then click Create App.

Here is your app’s main control panel!

If you scroll down in the ‘Deploy’ tab, you will see instructions for ‘Deploy using Heroku Git’. Follow the steps here, and once you’ve successfully deployed your app continue on to the next step.

Automation

Go over to the ‘Overview’ tab and click ‘Configure Add-Ons’. Then, in the add-on search bar, type ‘ Heroku Scheduler’ and select it. A dialog will pop-up, hit ‘Provision’.

Once added, you can then click on the add-on and create these things called ‘jobs’. Jobs are essentially tasks that get executed by Heroku Scheduler.

You’ll want to click ‘Add new job’ and a configure window will appear. In the command option, type the following:

node bot.js

and select the frequency you want to run the command. Once done click save.

And with that you have successfully deployed a Twitter lyric bot! ?

Acknowledgments

Most of the code for creating the custom text is credited to Daniel Shiffman. You can find his material here!

The lyric data I used in this article was sampled from a song called Daylily by Movements.

Big thank you to Morgan Allgrove-Hodges for giving feedback and fixing my silly grammar mistakes! ?

Connect with me on LinkedIn or follow me on Twitter! I love making new connections ?

~ Shawn Toubeau

On LinkedIn, there’s a section that’s titled, “People you may know.” It’s under the My Network tab.

This is the page that suggests people you might want to connect with.

You can click these Connect buttons to send connection requests to the people in this list.

A few years ago, I found this page, and I started randomly adding people there. I would just click on the connect button on every single person I found on this page.

I just figured it might be useful to have a lot of connections on LinkedIn to get the kinds of jobs I wanted to get, for example, software engineer internships.

But after a while, it became a little bit cumbersome to keep clicking on these connect buttons manually.

So, I decided to make a little bot to click these buttons for me.

This is an article about how I made this bot, what happened as a result, and what I learned from it.

How I made the bot

The tools I used

I made this simple bot to add random people on LinkedIn with JavaScript and Greasemonkey.

Greasemonkey is a Firefox add-on that helps you manage custom JavaScript code.

With it, you can set things up so that a certain set of code runs automatically when you open a certain URL.

You can also store some data in Greasemonkey. I used this feature to keep track of the number of people I added with this bot. That way, I was able to keep track of this number consistently even when I closed the browser or refreshed the page.

The code I used

Unfortunately, I did not keep the code I used to create my bot after I used it.

So, in this article, I’ll do my best to recreate it as closely as possible.

Initially, to create this bit of code, I used Google Chrome. Later, I switched to Firefox to use Greasemonkey, which I mentioned earlier. I chose to use Chrome initially just because I was more used to it.

Now, let’s together go through how I would recreate this code today. In this article, just to keep it simple, I’m only going to show you the core functionality of this bot - adding people. So, I’m going to skip the part about using Greasemonkey to store data persistently here.

Please let me know in the comments if you’d like me to cover that part in a separate article.

Step 0: JavaScript basics

In case you’re not too familiar with JavaScript, let’s quickly go over some JavaScript basics here.

We’re going to use Google Chrome here, but you can use any browser you’d like to use.

First, open any website, let’s say, Google.com.

Then, you’ll need to open the browser’s JavaScript console there.

On Google Chrome, you can do it in a few different ways.

The way I usually do it is the following:

• Right click anywhere on the page.
• Then, click Inspect out of the menu that’s popped up.

• When you click it, a window like the following should show up.

• Then, click the Console tab there to show the JavaScript console.
• Once you click the Console tab, you should see the JavaScript console.

This is where you can type in any JavaScript code to test it. You can use the code you enter to interact with the page that’s open in your browser.

For example, try typing in the following code in the console and press Enter.

selected = document.querySelector('body');

This selects the body tag in the page that’s open on the browser. Then, it assigns it to a new variable called selected.

In Chrome and Firefox, there is a shorthand for:

selected = document.querySelector('body');

Instead, you can just write:

selected = $('body');

This code is equivalent to the one above.

I’m going to use this shorthand notation with the dollar sign throughout this article to keep our code short and simple.

Also, don’t worry about it if you don’t know the basics of HTML and JavaScript yet. I’ll try my best to write this article so it’s easy to understand even for beginners.

If you’re not interested in the code I’m going to show you, you can also just skip to the sections about what happened and what I learned from this experience at the end.

Now, let’s walk through our bot’s code, step by step.

Step 1: Find the target element

First, you’ll need to write the bit of code that finds the buttons that you want to click.

First, log in to LinkedIn. Then, go to the My Network tab. It’s currently at https://www.linkedin.com/mynetwork/ (July, 2018).

You should be able to find the People you may know section there.

Then, on Chrome, right click on the “connect” button on one of the recommended people there. Then, click Inspect.

Once you do so, the element that you just clicked on will be highlighted in the developer window.

This is the HTML code that’s highlighted in blue here:

<span aria-hidden=”true”>Connect</span>

This is a span tab that shows the text: Connect. What we really want to click on is not this one, but its parent element, which is a button.

You can find it right above the span element that we selected.

Let’s now examine this button element:

<button data-control-name=”invite” class=”button-secondary-small” data-ember-action=”” data-ember-action-1596=”1596" data-is-animating-click=”true”> <span aria-hidden=”true”>Connect</span> <span class=”visually-hidden”> Invite Azul Pinochet Barros to connect </span></button>

There’s a bunch of stuff here, but here’s the important part:

<button data-control-name=”invite” ...> <span aria-hidden=”true”>Connect</span> ...</button>

Basically, this is a button element whose attribute, data-control-name, is “invite”.

In our script, all we need to do is select elements like this and click them.

You can select these elements with this piece of code:

selected = $(“button[data-control-name=invite]”);

This reads as, select all the button elements whose data-control-name is “invite”.

NOTE: It looks like LinkedIn’s website uses jQuery. So, the notation above is actually a jQuery selector, not a helper function defined by Chrome. Confusingly, their behaviours are slightly different ?

Anyway, once you run this code in your Chrome console, you should be able to see that the correct elements have been selected.

This is how you can make sure that the correct elements have been selected.

Now, with this piece of code - selected = $("button[data-control-name=invite]"); - your browser finds multiple button elements and puts them in an array. To pick the first one, you can just select the first element in this array like so:

toClick = $("button[data-control-name=invite]")[0];

Then, you can click it with this:

toClick.click();

If it goes through, you should see a confirmation window popping up.

A confirmation window that shows up when you click one of the connect buttons

Step 2: Loop through multiple target elements

Now, the next step is to loop through multiple target elements to click so we can add multiple people.

After some experimentation, I realized that there’s a simpler way to select multiple buttons and loop through them than the one I showed earlier.

Here’s how I would do it.

First, use Inspect Element to analyze the structure of this page a bit more. Then, you should be able to see that the people you may know is just an unordered list.

You should be able to find code that looks like this:

The parent element is a ul (unordered list) element. Its children are li (list item) elements.

Each li element represents each of the people you may know cards you see on the screen.

By selecting these li elements instead of selecting the buttons directly, it actually becomes easier to go through multiple people.

You can select this ul element, the parent of the li elements, like this:

ul = $('ul.mn-pymk-list__cards')[0];

This says, select the ul element with the class ul.mn-pymk-list__cards. We need to add [0] at the end because the raw result is an array containing a single element.

Then, you can select the first li element (the first person’s card) under the ul element like this:

firstLi = ul.querySelector('li');

We don’t need to add [0] at the end of this statement because the querySelector() function only returns one element.

Then, out of firstLi, you can select the button that we need to click like this:

buttonToClick = firstLi.querySelector("button[data-control-name=invite]");

After clicking this button with buttonToClick.click(), we should remove this li element so we can go to the next li element (the next person’s card). We can do that with this:

ul.removeChild(firstLi);

Putting them all together, and putting everything in a while loop, you’ll get something like this:

ul = $('ul.mn-pymk-list__cards')[0];firstLi = ul.querySelector('li');while(firstLi){ // do this while firstLi still exists.  buttonToClick = firstLi.querySelector("button[data-control-name=invite]");  ul.removeChild(firstLi);  firstLi = ul.querySelector('li');}

This code should work, but it has several issues.

1. We add people really fast with this, so it’s going to be hard to know what’s going on when you run this code.
2. We are not keeping track of how many people we’ve added.
3. We are assuming that buttonToClick is always the correct button to click. Sometimes this button has the text “Invite” instead of “Connect”. We don’t want to click on too many of those “Invite” buttons.

Step 3: Refine our code

I’ve fixed all of the issues I mentioned above and put together a relatively simple piece of code below.

It’s also here on Gist. Perhaps it’s easier to read there.

// this function allows us to stop our code for |ms| milliseconds.function sleep(ms) {  return new Promise(resolve => setTimeout(resolve, ms));}

// I've put our main code into this function.async function addPeople() {  ul = $('ul.mn-pymk-list__cards')[0];  firstLi = ul.querySelector('li');  count = 0; // this is the count of how many people you've added  while(firstLi && count < 100){ // stop after adding 100 people    buttonToClick = firstLi.querySelector("button[data-control-name=invite]");    // make sure that this button contains the text "Connect"    if (buttonToClick.innerText.includes("Connect")){      buttonToClick.click();      count += 1;      console.log("I have added " + count + " people so far.");    }    ul.removeChild(firstLi);    await sleep(1000); // stop this function for 1 second here.    firstLi = ul.querySelector('li');  }}

addPeople();

If you examine this code carefully, you should be able to notice the couple of changes I’ve made:

1. I’ve put our code into an async function called addPeople(). In this function, every time we add someone, we pause for 1 second with the sleep() function. More about this pattern here.
2. I added a count variable to keep track of how many people we’ve added.
3. I added this if statement: if (buttonToClick.innerText.includes("Connect"){...}. This way, we can make sure that the button we’re clicking contains the word “Connect” inside it.

With these changes, when I run this code, it looks like this:

Step 4: Make further improvements!

On top of what I showed above, I had a few more functionalities when I actually used my bot to add a bunch of people on LinkedIn.

First of all, I used Greasemonkey, which I mentioned earlier, to keep track of the total number of people I’ve added.

Also, to avoid being detected as a bot by LinkedIn, I added a few things:

1. I randomized the order in which I added people.
2. I randomized the amount of time I waited every time I added a new person.

I’ll leave all of these as exercise problems for you to solve in case you’re interested in solving them ?

What happened

With my script, I ended up adding 2000+ connections. Then, if I remember correctly, about 400 of them added me back.

As a result, I went from about 300 connections to 700+ connections within a week or so!

Then, after a while, I got banned by LinkedIn from adding any more people. I didn’t know that I could get banned! I was scared for a bit, but the ban lifted after 2 months or so.

More importantly, I was able to land a few interviews from those 400+ new connections. One of the interviews was with this company called Palantir.

Here’s a screenshot of the message I received from them:

What I learned from this experience

I thought what I was doing was pretty silly at the time, but I ended up learning a lot from this experience.

Takeaway #1

First of all, through this experience, I realized that LinkedIn actually works for getting jobs. I was able to get a few job interviews with my bot, after all.

Then, after a while, I also realized that adding thousands of random people was not the most efficient way to use LinkedIn. With that kind of approach, you end up adding a lot of people you don’t need to add.

So, after that experience, I changed my approach to a more focused one.

With my new approach, I would only add recruiters of the companies I wanted to work at. Then, I would only send messages to the people who added me back.

It turned out to be a much more focused, effective strategy to use LinkedIn. With this new strategy, I was able to get a few more job interviews with multiple tech companies, including Yelp and Xamarin. This time, I didn’t have to add thousands of new connections to achieve this result ?

NOTE: I talk more about this strategy in this article, just in case you’re curious about it.

Takeaway #2

Having fun is the best way to hone your programming skills!

Through this particular project, I was able to hone my JavaScript skills. What I learned included:

• How to set a timed interval between function executions
• How to select certain HTML elements with JavaScript
• How to store data locally with Greasemonkey

I learned these things through this project, and it didn’t feel like studying at all because it was so much fun.

Takeaway #3

From this experience, I’ve learned that it sometimes pays to do something weird. So, don’t be afraid of being a little bit mischievous and adventurous if you have any inclination to do so.

Even after this little experiment, I continued to do weird things for fun.

For example, when I was interning at Microsoft, I ran a little experiment where I “stole” a bunch of employee passwords. I did that by sending out a phishing email. It was supposed to be a huge give-away raffle with prizes like Xbox and Surface laptops. It was my hackathon project there.

I also started a programming-education YouTube channel, and eventually decided to work on it full-time and quit my full-time software engineer job.

Perhaps all of these things seemed a little bit weird to other people. But every time I went through each of these experiences, I learned something new, and I had tons of fun along the way. I would say the last one even made my career.

So again, don’t be afraid of trying something strange just for fun! You might learn something valuable along the way.

Okay, that’s it for this article.

This was supposed to be sort of a fun article, but I usually write about more serious stuff.

For example, I have articles about writing your software engineer resume, the best ways to apply for software engineer jobs, and how to get a job at a top tech company.

Feel free to check them out. They are all here on Medium.

Also, as always, if you have any questions about this or anything else, please feel free to let me know in a comment below or on Instagram or Twitter (@ykdojo on both).

Thank you for reading this article!