diff --git a/guide/Cooldown/channelCooldown_ai.md b/guide/Cooldown/channelCooldown_ai.md index ccd5dc9d..e20a5562 100644 --- a/guide/Cooldown/channelCooldown_ai.md +++ b/guide/Cooldown/channelCooldown_ai.md @@ -1,55 +1,61 @@ # $channelCooldown -Sets a cooldown for a command, *per channel*! This means the command can only be used again in the specific channel after the specified cooldown has expired. +Sets a cooldown for a command in channel. -#### Usage: +## Usage -`$channelCooldown[time (default is 5s);Error message]` +```bash +$channelCooldown[time;error message] +``` +1. **time** - (Optional) default value: `5s`. The cooldown duration. Example times: `10s`, `1m`, `2h`, `1d` +2. **error message** - (Optional) default value: (none). The message to send if a cooldown is still in progress. -* **time:** The cooldown duration. Defaults to 5 seconds if not provided. Examples: `10s`, `1m`, `2h`, `1d`. -* **Error message:** The message to send when a user tries to use the command before the cooldown expires. +## Example -### Example: +#### Using $channelCooldown + +As you can see, first time it will set the cooldown and execute code below, second time, it won't allow execution - - !!exec $channelCooldown[2h;You can get points again after %time%]
- $sendMessage[You received 100x points.] - - - You can get points again after 1 hour 54 minutes and 56 seconds - + + !!exec $channelCooldown[5m;You're on cooldown!]
+ You're not on cooldown! + + + You're not on cooldown! + + + !!exec $channelCooldown[5m;You're on cooldown! Still %mins%m remaining!]
+ You're not on cooldown! + + + You're on cooldown! Still 4m remaining! + -In this example, the command will give the user 100 points. If they try to use the command again within 2 hours in the same channel, they will receive the error message: "You can get points again after [remaining time]". - -## Usable Macros in Error Message: +## Placeholders -These macros can be used in your error message to provide dynamic information about the cooldown. +Available placeholders you can use in error message -| Macro | Description | Output Example | -| ------------ | ------------------------------------------------- | ---------------------------------------- | -| `%time%` | Replaced with the remaining time in a readable format. | `5 days 1 hour 54 minutes and 56 seconds` | -| `%days%` | The number of days remaining. | `5` | -| `%hrs%` | The number of hours remaining. | `1` | -| `%mins%` | The number of minutes remaining. | `54` | -| `%secs%` | The number of seconds remaining. | `56` | -| `%timestamp%` | Unix timestamp (seconds) for when the cooldown expires. | `1680711176` | -| `%relative%` | Displays the remaining time using Discord's relative timestamp feature (updates automatically). | ![](https://i.imgur.com/F2bAFnk.png) | +| Placeholder | Description | Output Example | +| ------------- | --------------------------------------------------------- | ----------------------------------------- | +| `%time%` | The full time remaining | `1 day 2 hours 3 minutes and 4 seconds` | +| `%days%` | The number of days remaining | `1` | +| `%hrs%` | The number of hours remaining | `2` | +| `%mins%` | The number of minutes remaining | `3` | +| `%secs%` | The number of seconds remaining | `4` | +| `%timestamp%` | Timestamp of cooldown expiration in seconds | `1735689600` | +| `%relative%` | Shows Discord relative timestamp (Automatically Updates) | `` - Displays: `in 1 day` | -::: tip Note -You can send styled messages or embeds by using the [Message Curl Format](../CodeReferences/ref.message_curl_format.md) in the error message. +::: warning Warning +Place this function above the code you want to use cooldown for. All code before this function will be executed. ::: - -::: tip Related Functions -* [$cooldown](../Cooldown/cooldown.md): Sets a cooldown for a command, *per user*. -* [$serverCooldown](../Cooldown/serverCooldown.md): Sets a cooldown for a command, *per server*. +::: tip Suggestion +You can send embeds, select menus and buttons by using the [message curl format](../CodeReferences/ref.message_curl_format.md). ::: -::: danger Important -Place the `$channelCooldown` function on the **FIRST line** of your command's code. If it's not the first line, the code before it will execute regardless of the cooldown, and the cooldown won't apply correctly. -::: -##### Function Difficulty: +##### Related functions: [$cooldown](../Cooldown/cooldown.md) [$serverCooldown](../Cooldown/serverCooldown.md) -###### Tags: \ No newline at end of file +##### Function Difficulty: +###### Tags: \ No newline at end of file diff --git a/guide/Cooldown/clearCoolDown_ai.md b/guide/Cooldown/clearCoolDown_ai.md index 3576808e..d72add7c 100644 --- a/guide/Cooldown/clearCoolDown_ai.md +++ b/guide/Cooldown/clearCoolDown_ai.md @@ -1,39 +1,43 @@ # $clearCooldown -Clears a cooldown set by the `$cooldown` function. This allows you to bypass or reset cooldowns for specific users, channels, or servers. +Clears a cooldown set by cooldown function. **Type:** Clears or resets a pre-existing cooldown. ## Usage ```bash -$clearCooldown[type (optional, default: user); id (optional, default: "$authorID")] +$clearCooldown[type;id] ``` - -**Parameters:** - -* **`type` (Optional):** Specifies the scope of the cooldown to clear. Can be one of the following: - * `user`: Clears the cooldown for a specific user. (Default) - * `channel`: Clears the cooldown for the current channel. - * `server`: Clears the cooldown for the current server. -* **`id` (Optional):** Specifies the ID of the user, channel, or server to clear the cooldown for. Defaults to `$authorID` (the user who triggered the command) if no ID is provided. - -## Example: Cooldown Exception for a Specific User - -This example demonstrates how to set a cooldown for everyone *except* a specific user. The user "Mido" will be exempt from the cooldown. - -```bash -$cooldown[1m;You are in cooldown because you are not Mido] -$if[$username==Mido] - $clearCooldown[user;$authorID] -$endIf -``` - -**Explanation:** - -1. **`$cooldown[1m;You are in cooldown because you are not Mido]`**: This line sets a 1-minute cooldown for all users executing the command. The message "You are in cooldown because you are not Mido" will be displayed if a user tries to use the command within the cooldown period. -2. **`$if[$username==Mido]`**: This checks if the username of the user executing the command is "Mido". -3. **`$clearCooldown[user;$authorID]`**: If the username is "Mido", this line clears the cooldown specifically for that user (`$authorID`). This means Mido can bypass the 1-minute cooldown. -4. **`$endIf`**: Closes the `$if` statement. - -In summary, this example sets a general cooldown but then removes it for the user "Mido", allowing them to use the command without waiting. \ No newline at end of file +1. **type** - (Optional) default value: `user`. Can be `user`, `channel` or `server`. The type of cooldown to clear. +2. **id** - (Optional) default value: `$authorID` if type is user. The ID of a user or channel to clear cooldown from. + +## Example + +#### Remove cooldown from a user + +How to remove cooldown from a user + + + + !!exec $cooldown[5m]
+ $clearCooldown
+ No cooldown + + + No cooldown + + + !!exec $cooldown[5m]
+ $clearCooldown
+ No cooldown 2nd try + + + No cooldown 2nd try + + + +##### Related functions: [$getCooldownTime](../Cooldown/getCooldownTime.md) + +##### Function difficulty: +###### Tags: \ No newline at end of file diff --git a/guide/Cooldown/cooldown_ai.md b/guide/Cooldown/cooldown_ai.md index 660fdde8..d47a40fd 100644 --- a/guide/Cooldown/cooldown_ai.md +++ b/guide/Cooldown/cooldown_ai.md @@ -1,59 +1,62 @@ # $cooldown -Sets a per-user cooldown for a command. This prevents users from spamming a command within a specified timeframe. +Sets a cooldown in a command for user. -#### Usage: +## Usage -`$cooldown[time (default 5s);Error message;user id (optional)]` +```bash +$cooldown[time;error message;userID] +``` +1. **time** - (Optional) default value: `5s`. The cooldown duration. Example times: `10s`, `1m`, `2h`, `1d` +2. **error message** - (Optional) default value: (none). The message to send if a cooldown is still in progress. +3. **userID** - (Optional) default value: `$authorID`. The ID of a user you want to set a cooldown to. -* **time:** The duration of the cooldown. Defaults to 5 seconds if not provided. Examples: `10s`, `1m`, `2h`, `1d`. -* **Error message:** The message displayed to the user if they try to use the command before the cooldown expires. You can use macros in this message (see below). -* **user id (optional):** Apply the cooldown to a specific user ID instead of the user executing the command. Useful for moderator commands. +## Example -### Example: +#### Using $cooldown -This example sets a 2-hour cooldown on a command that gives the user points. If the user tries to use the command before the cooldown expires, they will receive a message indicating how much time is left. +As you can see, first time it will set the cooldown and execute code below, second time, it won't allow execution - - !!exec $cooldown[2h;You can get points again after %time%]
- $sendMessage[You received 100x points.]
- - - You can get points again after 1 hour 54 minutes and 56 seconds

- + + !!exec $cooldown[5m;You're on cooldown!]
+ You're not on cooldown! + + + You're not on cooldown! + + + !!exec $cooldown[5m;You're on cooldown! Still %mins%m remaining!]
+ You're not on cooldown! + + + You're on cooldown! Still 4m remaining! + -## Usable Macros In Message: +## Placeholders -These macros can be used in the `Error message` to provide dynamic information about the remaining cooldown time. +Available placeholders you can use in error message -| Macro | Description | Output Example | -| -------------- | -------------------------------------------- | ------------------------------------- | -| `%time%` | Human-readable time remaining. | 5 days 1 hour 54 minutes and 56 seconds | -| `%days%` | Days remaining. | 5 | -| `%hrs%` | Hours remaining. | 1 | -| `%mins%` | Minutes remaining. | 54 | -| `%secs%` | Seconds remaining. | 56 | -| `%timestamp%` | UNIX timestamp (in seconds) of cooldown expiration. | 1680711176 | -| `%relative%` | Discord's relative timestamp (auto-updates). | ![](https://i.imgur.com/F2bAFnk.png) | +| Placeholder | Description | Output Example | +| ------------- | --------------------------------------------------------- | ----------------------------------------- | +| `%time%` | The full time remaining | `1 day 2 hours 3 minutes and 4 seconds` | +| `%days%` | The number of days remaining | `1` | +| `%hrs%` | The number of hours remaining | `2` | +| `%mins%` | The number of minutes remaining | `3` | +| `%secs%` | The number of seconds remaining | `4` | +| `%timestamp%` | Timestamp of cooldown expiration in seconds | `1735689600` | +| `%relative%` | Shows Discord relative timestamp (Automatically Updates) | `` - Displays: `in 1 day` | -::: tip Note -You can send an embed as the error message using [Message Curl Format](../CodeReferences/ref.message_curl_format.md). +::: warning Warning +Place this function above the code you want to use cooldown for. All code before this function will be executed. ::: - -::: tip Related Functions - -* [$channelCooldown](../Cooldown/channelCooldown.md): For a channel-based cooldown. -* [$serverCooldown](../Cooldown/serverCooldown.md): For a server-based cooldown. - +::: tip Suggestion +You can send embeds, select menus and buttons by using the [message curl format](../CodeReferences/ref.message_curl_format.md). ::: -::: danger Important -Place this code on the **FIRST** line of your command's code. If it's not the first line, the code *before* `$cooldown` will execute regardless of the cooldown. - -::: +##### Related functions: [$channelCooldown](../Cooldown/channelCooldown.md) [$serverCooldown](../Cooldown/serverCooldown.md) -##### Function difficulty -###### Tags: \ No newline at end of file +##### Function Difficulty: +###### Tags: \ No newline at end of file diff --git a/guide/Cooldown/getCooldownTime_ai.md b/guide/Cooldown/getCooldownTime_ai.md index b84ec8f8..6355dddb 100644 --- a/guide/Cooldown/getCooldownTime_ai.md +++ b/guide/Cooldown/getCooldownTime_ai.md @@ -1,46 +1,37 @@ # $getCooldownTime -Retrieves the remaining cooldown time, in milliseconds, set by the `$cooldown` function. This allows you to check if a user, channel, or server is still subject to a cooldown. - -**Type** specifies the scope of the cooldown and can be one of the following: `user`, `channel`, or `server`. +Returns remaining time of a cooldown in miliseconds. ## Usage -``` +```bash $getCooldownTime[time;type;id] ``` - -* **`time`**: The cooldown duration specified in the `$cooldown` function (e.g., `10m` for 10 minutes). This *must* match the original `$cooldown` duration for the function to work correctly. -* **`type`**: The scope of the cooldown: `user`, `channel`, or `server`. -* **`id`**: Required only when `type` is `user` or `channel`. Specify the user ID or channel ID respectively. Leave empty if `type` is `server`. +1. **time** - (Optional) default value: (last cooldown set). The time your cooldown was set to. +2. **type** - (Optional) default value: `user`. Can be `user`, `channel` or `server`. The type of cooldown to return remaining time of. +3. **id** - (Optional) default value: `$authorID` if type is user. The ID of a user or a channel to check cooldown from. ## Example -This example demonstrates how to check if a command is on server-wide cooldown before executing it. +#### Using $getCooldownTime -``` -$if[$getCoolDownTime[10m;server]!=0] - $interactionReply[You can't use this, this command is globally on cooldown.] - $stop -$else - $servercooldown[10m] - $interactionReply[Command executed!] - ... REST OF CODE -$endIf -``` +How to use $getCooldownTime -**Explanation:** + + + !!exec $channelCooldown[5m]
+ $getCooldownTime[5m;channel;$channelID] + + + 299937 + + -1. **`$if[$getCoolDownTime[10m;server]!=0]`**: This checks if the remaining server cooldown time for a cooldown originally set for `10m` is *not* equal to 0. If it's not 0, it means the cooldown is still active. -2. **`$interactionReply[You can't use this, this command is globally on cooldown.]`**: If the cooldown is active, the bot sends a reply indicating that the command cannot be used. -3. **`$stop`**: Stops further execution of the command since it's on cooldown. -4. **`$else`**: If the cooldown time is 0 (meaning the cooldown has expired). -5. **`$servercooldown[10m]`**: Sets a new server-wide cooldown for `10m`. -6. **`$interactionReply[Command executed!]`**: Confirms command execution and signifies the start of any other code logic. -7. **`... REST OF CODE`**: Represents the remaining code of the command, which will only execute if the cooldown has expired and is now reapplied. +::: warning Note +The `time` argument in must exactly match the time in the original cooldown function used. Mismatched durations will result in incorrect cooldown checks. +::: -**Important Considerations:** +##### Related functions: [$clearCooldown](../Cooldown/clearCooldown.md) -* The `time` argument in `$getCooldownTime` must exactly match the `time` argument in the original `$cooldown` function. Mismatched durations will result in incorrect cooldown checks. -* When using `user` or `channel` cooldowns, ensure you provide the correct `id`. -* `$getCooldownTime` returns the remaining cooldown time in milliseconds. You can use mathematical operations or formatting functions to convert it to more human-readable formats (e.g., seconds, minutes). \ No newline at end of file +##### Function difficulty: +###### Tags: \ No newline at end of file diff --git a/guide/Cooldown/serverCooldown_ai.md b/guide/Cooldown/serverCooldown_ai.md index cdb9fc60..12d61c4e 100644 --- a/guide/Cooldown/serverCooldown_ai.md +++ b/guide/Cooldown/serverCooldown_ai.md @@ -1,61 +1,61 @@ # $serverCooldown -This function sets a cooldown for a command, applying to *all* members within the server. While a user is on cooldown, the command execution will be halted, and an error message will be displayed to them. This is useful for preventing command spam and abuse. +Sets a cooldown in a command for the whole server. -## Usage: +## Usage -`$serverCooldown[time (default is 5s);Error message]` +```bash +$serverCooldown[time;error message] +``` +1. **time** - (Optional) default value: `5s`. The cooldown duration. Example times: `10s`, `1m`, `2h`, `1d` +2. **error message** - (Optional) default value: (none). The message to send if a cooldown is still in progress. -* **time:** The duration of the cooldown. You can specify the time in seconds (s), minutes (m), hours (h), or days (d). If no time is provided, the default cooldown is 5 seconds. -* **Error message:** The message displayed to the user when they attempt to use the command while on cooldown. +## Example -### Example: +#### Using $serverCooldown -This example demonstrates how to give users points, with a cooldown of 2 hours. +As you can see, first time it will set the cooldown and execute code below, second time, it won't allow execution -```html - - !!exec $serverCooldown[2h;You can get points again after %time%]
- $sendMessage[You received 100x points.]
+ + !!exec $serverCooldown[5m;You're on cooldown!]
+ You're not on cooldown! + + + You're not on cooldown! + + + !!exec $serverCooldown[5m;You're on cooldown! Still %mins%m remaining!]
+ You're not on cooldown! - - You can get points again after 1 hour 54 minutes and 56 seconds

+ + You're on cooldown! Still 4m remaining! -``` - -In this example: -* `$serverCooldown[2h;You can get points again after %time%]` sets a 2-hour server-wide cooldown. If a user tries to run the command within those 2 hours, they will receive the specified error message. -* `$sendMessage[You received 100x points.]` will send a message to the user if they are not on cooldown. +## Placeholders -## Available Macros in Error Message: +Available placeholders you can use in error message -You can use the following macros within your error message to dynamically display cooldown information: +| Placeholder | Description | Output Example | +| ------------- | --------------------------------------------------------- | ----------------------------------------- | +| `%time%` | The full time remaining | `1 day 2 hours 3 minutes and 4 seconds` | +| `%days%` | The number of days remaining | `1` | +| `%hrs%` | The number of hours remaining | `2` | +| `%mins%` | The number of minutes remaining | `3` | +| `%secs%` | The number of seconds remaining | `4` | +| `%timestamp%` | Timestamp of cooldown expiration in seconds | `1735689600` | +| `%relative%` | Shows Discord relative timestamp (Automatically Updates) | `` - Displays: `in 1 day` | -| Macro | Description | Output Example | -| ------------ | ----------------------------------------- | ------------------------------------ | -| `%time%` | Replaced with human-readable time left. | `5 days 1 hour 54 minutes and 56 seconds` | -| `%days%` | Number of days left on the cooldown. | `5` | -| `%hrs%` | Number of hours left on the cooldown. | `1` | -| `%mins%` | Number of minutes left on the cooldown. | `54` | -| `%secs%` | Number of seconds left on the cooldown. | `56` | -| `%timestamp%` | Unix timestamp (seconds) of expiration. | `1680711176` | -| `%relative%` | Discord's relative timestamp. | ![](https://i.imgur.com/F2bAFnk.png) | - -::: tip Note -You can format the error message as an embed using [Message Curl Format](../CodeReferences/ref.message_curl_format.md). +::: warning Warning +Place this function above the code you want to use cooldown for. All code before this function will be executed. ::: - -::: tip Related Functions -* [$channelCooldown](../Cooldown/channelCooldown.md): Sets a cooldown for a command on a per-channel basis. -* [$cooldown](../Cooldown/cooldown.md): Sets a cooldown for a command on a per-user basis. +::: tip Suggestion +You can send embeds, select menus and buttons by using the [message curl format](../CodeReferences/ref.message_curl_format.md). ::: -::: danger Important -This function **must** be placed on the **first line** of your command code. Otherwise, the code before it will execute regardless of the cooldown, defeating the purpose of the function. -::: -##### Function difficulty -###### Tags: \ No newline at end of file +##### Related functions: [$serverCooldown](../Cooldown/serverCooldown.md) [$cooldown](../Cooldown/cooldown.md) + +##### Function Difficulty: +###### Tags: \ No newline at end of file diff --git a/guide/Request/httpRequest.md b/guide/Request/httpRequest.md index 0ee12677..40f0c11d 100644 --- a/guide/Request/httpRequest.md +++ b/guide/Request/httpRequest.md @@ -1,33 +1,33 @@ -# $httpRequest - -Perform an http request, with a content and headers and return the response content - -## Usage - -```bash -$httpRequest[URL;Method;Content;Header 1;Header 2;...] -``` - -### Methods: -Accepts PUT, GET, POST, DELETE, HEAD, PATCH methods, if not provided, it will use GET method - -### Content Input: -It can any content that suitable for your `content-type` header, like with `content-type: application/json` you can put the content as json format and so on - -### Header: -It accept the header in format of header: value\ -for example: `Content-Type: application/json` - -### Example (Sending JSON Request): - - - !!exec $let[response;$httpRequest[My API URL;post;{"name":"Mido"};Content-Type: application/json]]
Response is $response
Response Status is $httpRequestStatus

- - - Response is {"success":true}
Response Status is 200

- - - -### Some Notes: -* This function wont throw error if request non-ok status, so please check on your own the return value of $httpRequestStatus after the request to make sure its valid status you expecting +# $httpRequest + +Perform an http request, with a content and headers and return the response content + +## Usage + +```bash +$httpRequest[URL;Method;Content;Header 1;Header 2;...] +``` + +### Methods: +Accepts PUT, GET, POST, DELETE, HEAD, PATCH methods, if not provided, it will use GET method + +### Content Input: +It can any content that suitable for your `content-type` header, like with `content-type: application/json` you can put the content as json format and so on + +### Header: +It accept the header in format of header: value\ +for example: `Content-Type: application/json` + +### Example (Sending JSON Request): + + + !!exec $let[response;$httpRequest[My API URL;post;{"name":"Mido"};Content-Type: application/json]]
Response is $response
Response Status is $httpRequestStatus

+ + + Response is {"success":true}
Response Status is 200

+ + + +### Some Notes: +* This function wont throw error if request non-ok status, so please check on your own the return value of $httpRequestStatus after the request to make sure its valid status you expecting * Make sure the response data length is less than 1 MB, or it will errorRandom \ No newline at end of file diff --git a/guide/Request/httpRequestHeader.md b/guide/Request/httpRequestHeader.md index ebfd52e5..7c6f31a0 100644 --- a/guide/Request/httpRequestHeader.md +++ b/guide/Request/httpRequestHeader.md @@ -1,19 +1,19 @@ -# $httpRequestHeader - -return the header values from the most recent request performed with $httpRequest - -## Usage - -```bash -$httpRequestHeader[header name] -``` - -### Example: - - - !!exec $let[response;$httpRequest[My API URL]]
Response Content type is $httpRequestHeader[content-type]

- - - Response Content type is application/json - +# $httpRequestHeader + +return the header values from the most recent request performed with $httpRequest + +## Usage + +```bash +$httpRequestHeader[header name] +``` + +### Example: + + + !!exec $let[response;$httpRequest[My API URL]]
Response Content type is $httpRequestHeader[content-type]

+ + + Response Content type is application/json + \ No newline at end of file diff --git a/guide/Request/httpRequestHeader_ai.md b/guide/Request/httpRequestHeader_ai.md index 54fd085f..7e0414c9 100644 --- a/guide/Request/httpRequestHeader_ai.md +++ b/guide/Request/httpRequestHeader_ai.md @@ -1,45 +1,32 @@ -# $httpRequestHeader - -Retrieves the value of a specific header from the most recent HTTP request made using the `$httpRequest` function. - -## Syntax - -```bash -$httpRequestHeader[header name] -``` - -**`header name`**: The name of the HTTP header you want to retrieve. This is case-insensitive. - -## Description - -This function allows you to access the headers returned by the server after making an HTTP request with `$httpRequest`. You can use this to inspect the response and handle it accordingly. Common headers include `content-type`, `content-length`, `date`, and `server`. - -**Important:** This function only works if a successful `$httpRequest` has been made *before* it's called within the same execution context. - -## Example - -This example makes an HTTP request and then retrieves and displays the `content-type` header from the response. - -```discord -!!exec $let[response;$httpRequest[My API URL]] -Response Content type is $httpRequestHeader[content-type] -``` - -Here's a breakdown of what's happening: - -1. `$let[response;$httpRequest[My API URL]]`: This first makes an HTTP request to "My API URL" (replace this with an actual URL). The response is stored in a variable called `response`. While the response itself is stored, the crucial part here is that `$httpRequest` is executed and its headers become available. - -2. `Response Content type is $httpRequestHeader[content-type]`: This retrieves the value of the `content-type` header from the previous `$httpRequest` call and includes it in the message. - -**Example Output:** - - - - !!exec $let[response;$httpRequest[My API URL]]
Response Content type is $httpRequestHeader[content-type]

- - - Response Content type is application/json - - - -**Note:** Replace `My API URL` with a valid URL in your actual command. The output `application/json` is just an example; the actual value will depend on the API you're querying. \ No newline at end of file +# $httpRequestHeader + +Returns the value of a given header from the last request. + +## Usage + +```bash +$httpRequestHeader[header name] +``` +1. **header name** - The header name to return value from. (case-insensitive) + +## Example + +#### Using $httpRequestHeader + +How to return Content-Type from last request + + + + !!exec $httpRequest[https://api.example.com/]
+ Content-Type Header: $httpRequestHeader[content-type] + + + {"message": "Api response!"}
+ Content-Type Header: application/json + + + +##### Related functions: [$httpRequest](../Request/httpRequest.md) [$httpRequestStatus](../Request/httpRequestStatus.md) + +##### Function difficulty: +###### Tags: \ No newline at end of file diff --git a/guide/Request/httpRequestStatus.md b/guide/Request/httpRequestStatus.md index 0e75eaab..ced2c84d 100644 --- a/guide/Request/httpRequestStatus.md +++ b/guide/Request/httpRequestStatus.md @@ -1,22 +1,22 @@ -# $httpRequestStatus - -return the request status from the most recent request performed with $httpRequest - -## Usage - -```bash -$httpRequestStatus -``` - -### Example: - - - !!exec $let[response;$httpRequest[My API URL]]
Request status is $httpRequestStatus

- - - Request Status is 200

- - - -### Note: +# $httpRequestStatus + +return the request status from the most recent request performed with $httpRequest + +## Usage + +```bash +$httpRequestStatus +``` + +### Example: + + + !!exec $let[response;$httpRequest[My API URL]]
Request status is $httpRequestStatus

+ + + Request Status is 200

+ + + +### Note: Its recommended to check the request status directly after $httpRequest, to check if it was valid status. \ No newline at end of file diff --git a/guide/Request/httpRequestStatus_ai.md b/guide/Request/httpRequestStatus_ai.md index 5137c148..7559a97c 100644 --- a/guide/Request/httpRequestStatus_ai.md +++ b/guide/Request/httpRequestStatus_ai.md @@ -1,35 +1,31 @@ -# `$httpRequestStatus` - -Returns the HTTP status code of the most recent request made using the `$httpRequest` function. - -## Description - -This function allows you to check the outcome of your HTTP request, helping you handle success and error scenarios. - -## Usage - -```bash -$httpRequestStatus -``` - -## Example - -This example demonstrates how to use `$httpRequest` and `$httpRequestStatus` to make an API request and check its success. - - - - !!exec $let[response;$httpRequest[My API URL]]
Request status is $httpRequestStatus - - - Request Status is 200 - - - -**Explanation:** - -1. `$let[response;$httpRequest[My API URL]]`: This line makes an HTTP request to the specified "My API URL" using `$httpRequest` and stores the response (if any) into the `response` variable. -2. `Request status is $httpRequestStatus`: This retrieves the HTTP status code of the previous `$httpRequest` call using `$httpRequestStatus` and displays it. In this example, the status code is `200`, which typically indicates a successful request. - -## Important Note - -It's highly recommended to check the `$httpRequestStatus` immediately after using `$httpRequest`. This allows you to verify if the request was successful before proceeding with further actions based on the response. For example, you can use this to conditionally execute code based on whether the API call returned a 200 OK or an error code like 404 or 500. \ No newline at end of file +# $httpRequestStatus + +Returns the $httpRequest status code of the last request. + +## Usage + +```bash +$httpRequestStatus +``` + +## Example + +#### Using $httpRequestStatus + +How to use $httpRequestStatus to display status code of request + + + + !!exec $httpRequest[https://api.example.com/]
+ Code: $httpRequestStatus + + + Api response!
+ Code: 200 + + + +##### Related functions: [$httpRequest](../Request/httpRequest.md) [$httpRequestHeader](../Request/httpRequestHeader.md) + +##### Function difficulty: +###### Tags: \ No newline at end of file diff --git a/guide/Request/httpRequest_ai.md b/guide/Request/httpRequest_ai.md index e817688e..0fe0ed88 100644 --- a/guide/Request/httpRequest_ai.md +++ b/guide/Request/httpRequest_ai.md @@ -1,53 +1,57 @@ -# $httpRequest - -Performs a HTTP request, with a content and headers and returns the response content. - -::: warning Warning -In order to use `$httpRequest`, the API you wish to use needs to be whitelisted. To request a whitelist, please open a ticket in our Support Server. -::: - -## Usage - -```bash -$httpRequest[URL;Method;Content;Header 1;Header 2;...] -``` - -**Explanation:** This function sends an HTTP request to the specified URL with the given method, content, and headers. It returns the content of the HTTP response. - -### Parameters: - -* **URL:** The URL to send the request to. -* **Method:** The HTTP method to use (e.g., `PUT`, `GET`, `POST`, `DELETE`, `HEAD`, `PATCH`). If no method is provided, it defaults to `GET`. -* **Content:** The body of the HTTP request. The format should match the `Content-Type` header. For example, if you're sending JSON, set the `Content-Type` header to `application/json` and format the content as a JSON string. -* **Headers:** A list of HTTP headers to include in the request. Each header should be in the format `Header: Value`. Separate multiple headers with semicolons. - -### Header Format: - -Headers should be provided in the format `Header-Name: Header-Value`. For example: - -* `Content-Type: application/json` -* `Authorization: Bearer your_api_token` - -### Example (Sending a JSON Request): - -This example demonstrates sending a POST request with JSON data to an API. - - - - !!exec $let[response;$httpRequest[My API URL;post;{"name":"Mido"};Content-Type: application/json]]
Response is $response
Response Status is $httpRequestStatus

- - - Response is {"success":true}
Response Status is 200

- - - -### Important Notes: - -* **Error Handling:** This function does *not* automatically throw an error if the HTTP request returns a non-success status code (e.g., 404, 500). You *must* check the value of `$httpRequestStatus` after the request to ensure the status code is what you expect. For example: - - ```bash - $let[response;$httpRequest[My API URL;get;;Content-Type: application/json]] - $if[$httpRequestStatus!=200;Error: Request failed with status code $httpRequestStatus;Request successful: $response] - ``` - -* **Response Size Limit:** The response data must be less than 1 MB in size. Requests exceeding this limit will result in an error. +# $httpRequest + +Makes a HTTP request, with a content and headers. Returns the response content. + +## Usage + +```bash +$httpRequest[URL;Method;Content;Header 1;Header 2;...] +``` +1. **URL** - The URL you want use for your request. +2. **Method** - (Optional) default value: `GET`. Can be `PUT`, `GET`, `POST`, `DELETE`, `HEAD` or `PATCH`. The type of request you want to make. +3. **Content** - (Optional) default value: (empty). The body of your request. Useful with POST and similar. Format is `Content: value`. +4. **Header N** - (Optional) default value: (empty). The headers used with your request. This can be used for authorization, content-type to await and other data that your URL requires to request with. + +## Example + +#### Successful http request + +How to successfuly get data from an api + + + + !!exec $httpRequest[https://api.example.com/]
+ Code: $httpRequestStatus + + + Api response!
+ Code: 200 + + + +#### Unsuccessful http request + +Unsuccessful request without error message + + + + !!exec $httpRequest[https://api.example.com/path]
+ Code: $httpRequestStatus + + + Code: 404 + + + +::: warning Warning +The response data must be less than 1 MB in size. Requests exceeding this limit will result in an error.
+In order to use `$httpRequest`, the URL you wish to use needs to be whitelisted. To request a whitelist, please open a ticket in our [Support Server](https://ccbot.me/discord). +::: +::: danger Error Handling +This function does not automatically throw an error if the request fails. You must check the value of `$httpRequestStatus` after the request to ensure the status code is what you expect. +::: + +##### Related functions: [$httpRequestStatus](../Request/httpRequestStatus.md) [$httpRequestHeader](../Request/httpRequestHeader.md) + +##### Function difficulty: +###### Tags: \ No newline at end of file