Web and files

Call web APIs, download files, render image templates, ask AI, run saved scripts and find emojis.

These functions reach outside the command: the web, your image templates, AI and your saved scripts.

Write await in front of fetch, render_template, ask_ai and load_script. The bot adds it for load_file.

Limits#

Each run has its own count. Pre-hook and post-hook share it.

What	Free	Premium
`fetch` different requests per run	5	20
`load_file` different links per run	5	20
Download size, each	5 MB	100 MB
Download time, each	20 seconds	120 seconds
`render_template` per minute, whole server	20	120
Images inside one template	5	15
`ask_ai`	not available	available

Asking for the same fetch or load_file link again in the same run is free. The bot reuses the first answer.

Note

The bot only fetches public web addresses. Links to private or local network addresses are refused.

fetch#

Calls a web address and returns the answer.

python

await fetch(url, method="GET", to="json", dynamic=False, **options)

Argument	What it does
`url`	The web address.
`method`	`GET`, `POST`, `PUT`, `PATCH` or `DELETE`.
`to`	How to read the answer: `json` (a dict or list), `text` or `bytes`.
`dynamic`	`True` asks again every time, even for the same link. Use it for random answers.
`**options`	Sent with the request, for example `headers=`, `json=` or `data=`.

Returns None when the site answers with an error (status 400 or higher), or when the answer cannot be read as to.

Example: a random cat fact

python

data = await fetch("https://catfact.ninja/fact")
if data is None:
    set_error("The cat fact site is down. Try again later.")
set_content(data["fact"])

Example: send JSON to an API

python

await fetch(
    "https://example.com/api/report",
    method="POST",
    json={"user": str(user.id), "reason": reason},
    headers={"Authorization": "Bearer " + server_var("api_key")},
)

Random answers

Two calls to the same link in one run return the same answer. For a new random result each time, pass dynamic=True.

load_file#

Downloads a file from a link so you can attach it to a message.

python

load_file(file, filename=None)

Argument	What it does
`file`	The link to the file.
`filename`	The name Discord shows. Optional.

Returns None when the download fails. Fails with "File size is greater than 5MB" when the file is too big for your plan.

python

pic = load_file("https://example.com/banner.png", "banner.png")
send_message(channel, "New banner!", attachments=[pic])

render_template#

Draws an image from one of your Image Templates and returns it as a file.

python

await render_template(name, **values)

Argument	What it does
`name`	The template name from the dashboard.
`**values`	A value for each variable in the template. `avatar` also fills the template's avatar picture.

python

card = await render_template(
    "rank-card",
    name=user.display_name,
    avatar=user.avatar_url,
    level=member_var("level", 1),
)
add_attachment(card)

Put the result in attachments=, add_attachment(...), or a Message(image=...).

Fails when a variable has no value, and names the missing ones. On a free server, going over 20 renders a minute fails. On premium the call waits for a free slot.

ask_ai#

Premium only. Asks an AI model a question and returns the answer as text.

python

await ask_ai(
    prompt,
    instructions=None,
    max_words=None,
    use_context=True,
    cache=False,
)

Argument	What it does
`prompt`	The question.
`instructions`	How the AI should answer, like a role or a tone.
`max_words`	A shorter limit for the answer. The most is 1,024 words.
`use_context`	`True` tells the AI about your server and its commands.
`cache`	`True` reuses a recent answer to the same question.

python

answer = await ask_ai(question, instructions="Answer in one friendly sentence.")
set_content(answer)

The longest prompt depends on the plan: Starter 500, Basic 1,000, Advanced 2,000 characters. On a free server it fails with "ask_ai is a premium feature".

load_script#

Runs one of your saved Scripts inside this command.

python

await load_script(script_id, **variables)

Argument	What it does
`script_id`	The script's ID from the dashboard.
`**variables`	Extra variables the script can read.

The script sees all of your command's variables, plus the ones you pass. When it changes a plain variable, your command does not see the change.

python

await load_script("give-xp", amount=10)

A script cannot load another script. A disabled script fails and says why.

emoji#

Finds an emoji and returns it ready to put in a message.

python

emoji(query, as_emoji=False)

Argument	What it does
`query`	A custom emoji's name or ID from this server, or a name like `":fire:"`.
`as_emoji`	`True` returns the emoji object instead of text.

python

set_content(f"GG {emoji('pepe_happy')} {emoji(':tada:')}")

Returns nothing when no emoji matches.

These functions reach outside the command: the web, your image templates, AI and your saved scripts.

Write await in front of fetch, render_template, ask_ai and load_script. The bot adds it for load_file.

Limits#

Each run has its own count. Pre-hook and post-hook share it.

What	Free	Premium
`fetch` different requests per run	5	20
`load_file` different links per run	5	20
Download size, each	5 MB	100 MB
Download time, each	20 seconds	120 seconds
`render_template` per minute, whole server	20	120
Images inside one template	5	15
`ask_ai`	not available	available

Asking for the same fetch or load_file link again in the same run is free. The bot reuses the first answer.

Note

The bot only fetches public web addresses. Links to private or local network addresses are refused.

fetch#

Calls a web address and returns the answer.

python

await fetch(url, method="GET", to="json", dynamic=False, **options)

Argument	What it does
`url`	The web address.
`method`	`GET`, `POST`, `PUT`, `PATCH` or `DELETE`.
`to`	How to read the answer: `json` (a dict or list), `text` or `bytes`.
`dynamic`	`True` asks again every time, even for the same link. Use it for random answers.
`**options`	Sent with the request, for example `headers=`, `json=` or `data=`.

Returns None when the site answers with an error (status 400 or higher), or when the answer cannot be read as to.

Example: a random cat fact

python

data = await fetch("https://catfact.ninja/fact")
if data is None:
    set_error("The cat fact site is down. Try again later.")
set_content(data["fact"])

Example: send JSON to an API

python

await fetch(
    "https://example.com/api/report",
    method="POST",
    json={"user": str(user.id), "reason": reason},
    headers={"Authorization": "Bearer " + server_var("api_key")},
)

Random answers

Two calls to the same link in one run return the same answer. For a new random result each time, pass dynamic=True.

load_file#

Downloads a file from a link so you can attach it to a message.

python

load_file(file, filename=None)

Argument	What it does
`file`	The link to the file.
`filename`	The name Discord shows. Optional.

Returns None when the download fails. Fails with "File size is greater than 5MB" when the file is too big for your plan.

python

pic = load_file("https://example.com/banner.png", "banner.png")
send_message(channel, "New banner!", attachments=[pic])

render_template#

Draws an image from one of your Image Templates and returns it as a file.

python

await render_template(name, **values)

Argument	What it does
`name`	The template name from the dashboard.
`**values`	A value for each variable in the template. `avatar` also fills the template's avatar picture.

python

card = await render_template(
    "rank-card",
    name=user.display_name,
    avatar=user.avatar_url,
    level=member_var("level", 1),
)
add_attachment(card)

Put the result in attachments=, add_attachment(...), or a Message(image=...).

Fails when a variable has no value, and names the missing ones. On a free server, going over 20 renders a minute fails. On premium the call waits for a free slot.

ask_ai#

Premium only. Asks an AI model a question and returns the answer as text.

python

await ask_ai(
    prompt,
    instructions=None,
    max_words=None,
    use_context=True,
    cache=False,
)

Argument	What it does
`prompt`	The question.
`instructions`	How the AI should answer, like a role or a tone.
`max_words`	A shorter limit for the answer. The most is 1,024 words.
`use_context`	`True` tells the AI about your server and its commands.
`cache`	`True` reuses a recent answer to the same question.

python

answer = await ask_ai(question, instructions="Answer in one friendly sentence.")
set_content(answer)

The longest prompt depends on the plan: Starter 500, Basic 1,000, Advanced 2,000 characters. On a free server it fails with "ask_ai is a premium feature".

load_script#

Runs one of your saved Scripts inside this command.

python

await load_script(script_id, **variables)

Argument	What it does
`script_id`	The script's ID from the dashboard.
`**variables`	Extra variables the script can read.

The script sees all of your command's variables, plus the ones you pass. When it changes a plain variable, your command does not see the change.

python

await load_script("give-xp", amount=10)

A script cannot load another script. A disabled script fails and says why.

emoji#

Finds an emoji and returns it ready to put in a message.

python

emoji(query, as_emoji=False)

Argument	What it does
`query`	A custom emoji's name or ID from this server, or a name like `":fire:"`.
`as_emoji`	`True` returns the emoji object instead of text.

python

set_content(f"GG {emoji('pepe_happy')} {emoji(':tada:')}")

Returns nothing when no emoji matches.