How to Create a Basic Calculator Command with BotGhost [API Guide #1]

Do not index

Getting Started

To get started, you must first have created a Discord bot on BotGhost. If you have not created a bot before, follow this guide before proceeding.

What is an API, why are they powerful and where can I find them?

API is an acronym that stands for Application Programming Interface. APIs are tools that enable two services to share data and communicate with each other over the internet. To keep it simple, an API is simply the way applications talk across the internet. For example, whenever you hit the save button on BotGhost, your updated bot is sent to the BotGhost servers through an internal API.

Within BotGhost, APIs allow your bots to interact and use data from the outside world. This guide and others to come will cover a few simple examples of commands using publicly available APIs. You can then take these examples and apply them to other APIs you may be interested in.

Where can I find them?

There are thousands of publicly available APIs which you can tinker and play with. I highly recommend checking these out and playing around with the ones that you are interested in. You can test APIs with applications such as Postman which allow you to easily interact with and see the results of your API requests.

Here is a list of some resources to find APIs you may be interested in:

Rapid API

Public APIs

API List

Any API

You can also generally find any API you are looking for by just googling the topic you want and ‘API’. For example, googling ‘Roblox API’ may give you some ideas on how you can create your own Roblox discord bot.

API Request Action

In BotGhost, instead of using programs like Postman to interact with APIs, we use an API request action in our custom commands and events. To get to the API Request Action, go to Custom Commands or Custom Events in your BotGhost dashboard and click the Command Builder area to open up the command builder.

You are now in the BotGhost command/event builder. From here you can create custom commands and events by linking options, actions, and conditions into a flow that is run when the command or event is triggered. The API Request action is an action that when triggered, executes an HTTP request to an API and saves any data returned that you can then use in other actions and conditions. To get to the API request action, click on Actions and then search for ‘API’.

Next, click or drag the Action into the builder.

To open up the settings for the API request, click on the block.

Settings

This open up the API Request actions settings page. You should first give a simple name to your API request. This will be used as the ‘variable’ which you will use in other actions and conditions to retrieve a value returned by this action. After you have entered a name, you can then click on the Request Builder button. This button will open up the Request Builder which is the way you configure your API request.

Request Builder

The Request Builder houses all the components required to build out an API request. Because each API is different, you may or may not use all these options. In this guide and future guides to come, we will create a few commands which should cover the basics of all these options. If you want a more in-depth explanation of all these fields, please read our documentation on API requests here.

Calculator Command

The first command we are going to make is a simple calculator command. This command will let users input an expression, and return the result. To do this, we are going to use the Mathjs API. This API takes any expression and returns the calculated result. You can find the documentation for this API here. Reading the documentation for an API is extremely important. This is because the data that APIs return and how they expect to receive data are almost always different.

To get started, create a command by following the steps above and give your command a name and description. To do this, click on the ‘root’ block in the middle of the builder and enter a name and description in the inputs that pop up. I’ve simply called my command calculator.

If you click Save Command in the top left of your screen and go into Discord and type in /calculator you should see your new blank command.

Head back over to the command builder and drag in a Send an API Request action block. Link this block to your root node and give your request a name. For simplicity, I have called my request calculator.

Finally, open the request builder by clicking the blue button.

Configuring the Math.js API Request

We now must read the Math.js API documentation to see what information we have to enter. Open up their documentation and read the first section. This section tells us we must make a GET request to https://api.mathjs.org/v4 and send along some other query parameters.

Request Types

All API requests are sent using an HTTP method or type. These methods tell the server what type of request you are trying to make to that API. The most common types of HTTP request methods are GET, POST, HEAD, PUT and DELETE. The vast majority of the time however we will just use GET and POST types. GET requests ‘get’ or retrieve data from a server or API, whereas POST requests ‘post’ or send data to a server or API. To make things simple, GET requests only receive data, and POST requests send and receive data.

In the Request Builder, we change the request type by clicking the request type dropdown. The Math.js API documentation told us to make a GET request so select GET from the dropdown.

Request URL

The Request URL of the API is the location we are sending our HTTP request. Different APIs will use different URL structures. Some APIs may even have the same URL which can receive different request types.

In the request builder, paste https://api.mathjs.org/v4 in the URL field.

Request parameters

The final piece of information this API requires us to send is query parameters.

These parameters are additional information that is at the end of the URL which is then sent to the API server. This is the information you find after a question mark in URLs. Different APIs call this information different things such as request parameters, URL parameters, or just parameters.

In BotGhost we call these URL Params and can be added to our request in two ways. You can either simply put them on the end of the URL after a question mark, or put them one by one in the URL params window.

The Math.js API documentation tells us it requires a expr parameter to be added to the URL and that this is the expression we want to calculate. To do so, add the URL parameter by entering a key called expr and the expression you want to be evaluated. For a simple example, we will use 1+1.

Testing your API Request

Now that we have set up a basic request, we need to test to see if the request actually works. We can do this by clicking on the Test Request tab in the builder.

Once you are on this tab, click the Test Request button to run the request. If you have done everything correctly, you should see the result of your API request and some data.

We can see from this result that Math.js returned three pieces of information:

A response of 2 (which is 1+1 for those who are mathematically impaired)

A ‘status’ of 200

And a statusText of “OK”

Status Codes

Status codes are the way APIs tell you if an HTTP request you have sent has been successfully completed. There are hundreds of status codes that all mean different things. 200 status codes mean that the request was successful and 400 status codes mean that the request encountered some sort of error. By reading the status code and accompanying status text, you can figure out what error you made and how to fix it.

Because we received a status code of 200 and see the correct response, we know that the request was successful and we can begin using the result of our API.

Using our result

Now that we have actually configured, sent, and received a response from the Math.js API, we are ready to actually use and display the result in our command. BotGhost uses a variable system that you can use to display and use the information returned by an API. This variable consists of the name of the request you specified earlier and dot notation to access parts of the API response.

We can click on the results of the test API request to get the associated variable required to display that information in another action. To get the variable of the response of the calculator expression, click the 2 in the API response.

This will show and copy the variable {calculator.response} which can be used in other actions to display the response of this API request. For example, if we put this variable in a Plain Text Reply and ran this command, the command would simply respond back with 2.

If we wanted the status of the response, the variable would be {calculator.status} and if we wanted the statusText of the response, the variable would be {calculator.statusText}.

Adding a response to our command

Now that we have the variable we need, we can use this variable in a response action to show the result to whoever used our command.

Click out of the Request Builder and go to the Actions list again. This time drag or click a Plain Text Reply. Connect this action to your API request action.

This action replies with plain text whenever it is ran. This is how we will display the result of our calculator command. Click on the action and type ‘The result is {calculator.response}!’ in the content text area. If you forgot what your variable is, you can use the variable editor by clicking on the clipboard in the input. Your Plain Text Reply should now look like this.

Save your command by clicking the green Save Command button and head back over to discord. Use the /calculator command and your command should now return the result of 1+1.

Great! You have now made an HTTP request to an API and returned the result in discord to the user. However, this is not very useful unless you consistently forget what 1+1 is. To make this command more powerful we need to let the user enter their own expressions. To do this we will use a Text Option and slightly tweak our API request.

Letting the User enter the expression

To make our command actually useful we need to let the user input the expression to be calculated. In the builder, we can add a text option that will prompt users to input some text before the command is executed.

Creating your expression option

To do this, tab back into your command on the BotGhost Dashboard. This time, click the Options menu and drag or click a Text option into the builder. It will be automatically linked to your command.

Click on the new option and give it a name and description. This will be displayed to the user when they use your command. Finally set the option as required by clicking on the toggle. This will ensure that when people use your command they are required to enter an expression. Once you are done, your option should look something like this.

Using our new option in our API request

Now that we have made our expression text option, we can go ahead and use it in our API request. Click on your Send an API Request block and open back up the request builder. Here we want to replace our 1+1 expression with what the user inputs through our expression option. To get the value of an option we use a variable called option followed by the name of the option we are referencing. Because I called my option ‘expression’ my variable is therefore {option_expression}. Replace the 1+1 in the URL params section with your option variable. Your builder should now look something like this.

Once done, back out of the request builder and save your command. Wait a moment for your command to update and head over to discord and use your /calculator command. This time you will be prompted to enter an expression. Enter an expression to be calculated and wait for the result. If you entered a valid expression you should see the correct result from your bot.

Congrats on creating an actual calculator command that can calculate more than just 1+1. Go ahead and try some more difficult equations. For those who want to go further, try and implement a system to check if the request was successful. Sometimes users may enter expressions that are not valid. As a hint, you will need to use a comparison condition to check the value of the status code returned by the API response. Best of luck!