API Requests
Last updated
Last updated
API Request actions allow you to run a http request when the action is executed. API Requests allow you to access and interact with the resources of another server outside of BotGhost. You can then use the returned information in your custom commands and events.
For the safety of your bot token you can use {TOKEN_SECRET} in the HTTP Header instead of copy & pasting your bot token.
API request actions use a custom variable that you can use to access the data returned by the request. You must first set a unique name that will be used as the variable for this request.
This name must be different from any other API request in the command or event.
Once you have set the name for this action you will be able to start building your API request. Click the Request Builder to start building out your request.
This will open up the Request Builder modal which has six main components.
At the top of the window you must first enter the URL of the API you wish to send a HTTP request to. If you would like to find some APIs to play around with check out this collection. Paste the URL of the API endpoint in the URL field at the top. Next, select the request type of the URL you are trying to interact with. Consult the documentation for the API you are trying to interact with for this field, but in general a GET request retrieves data and a POST request sends data.
URL parameters or query strings are the way to structure additional information for the URL. These are generally added to the end of the Request URL after a ? symbol. You can add these by clicking the Add button on the URL Params menu.
These values will be added to the end of the URL and encoded correctly. You can use all variables in both the key and value.
Some APIs require you to pass headers along with the request to identify who the request is coming from or other information specific to that API. To add a header click on the HTTP Headers option in the menu and then click Add. You can use all variables in both the key and value.
This will create a new empty Header for your request. Enter the key and value for your header as defined by the APIs documentation. For example if the API requires Basic Authorization, your header might look like this:
If you select a request type that requires some data to be sent along with it, you may attach this data through adding data to your Request Body. To add new data to your request's body, click the Request Body menu option and then click Add.
Similarly to headers, fill in the key and value of the data you wish to add to the request body. You can use all variables in both the key and value.
The request builder has a set of options that change how your request is executed by the BotGhost backend.
Automatically exclude fields that are empty
This field will remove headers and body fields that are empty from the request.
Replace variables in the URL
Enabling this option will mean BotGhost will search for and replace variables in the URL of the request.
Replace variables in the URL Params
Enabling this option will mean BotGhost will search for and replace BotGhost variables in the URL Params.
Replace variables in the HTTP Headers
Enabling this option will mean BotGhost will search for and replace variables in the Headers of the request
Replace variables in Request Body
Enabling this option will mean BotGhost will search for and replace variables in the Request Body.
You are able to simulate and test how your API Request action will respond and test the potential value of a variable returned by the API. After you have filled out the above options, click the Test Request button to run a test request.
This will return the response, status and status text of the API request.
You can access the data returned by using the name you set earlier and dot notation. Click on the value you want to automatically copy the variable required to return that data. For example using the above example with a name of calculator:
{calculator.response.age}- 64
{calculator.response.name} - Tom
{calculator.status} - 200
{calculator.statusText} - OK
You can click on any value in the response to get the variable required to return that data
You can test the value of any variable by putting it into the Test Variable input field.
If the Variable Result returns either undefined or [object Object] double check the variable you are trying to test. Only text and numbers can be returned. You can click on any value in the response to get the variable required to return that data.
These variables can then be used in any action or condition.
For the safety of your bot token you can use {TOKEN_SECRET} in the HTTP Header instead of copy & pasting your bot token.
