# AICord Applets

Welcome to the **AICord Applet System**! Applets are tiny JavaScript tools that let your AI characters do powerful things - like pulling live data, reacting to server events, or integrating with external services. No big setup, no bloated codebase - just one file of code, one idea.

> Applets let your characters do *real-world* tasks: call APIs, fetch data, trigger webhooks giving them **agentic capabilities** beyond just conversation.

## What’s an Applet?

An **applet** is a simple `JavaScript` code in AICord's Applet Editor that contains one or more named functions. AICord runs them in a safe sandbox and invokes the appropriate one based on context (like a user message, or Discord event).

> Think of applets like "mini apps" your characters can use. They're plug-and-play extensions of their minds.

## How to code an applet?

In this tutorial, we are going to create an applet that allows AI characters to get the weather of a city when needed. 

To manage applets installed to your Discord server, go to the [AICord Dashboard](https://aicordapp.com/dashboard), then click the <i class="fa-puzzle-piece">:puzzle-piece:</i> **Applets** menu on the sidebar.

You'll be able to see 2 sections for applets:

* **Discover:** Browse and install public applets made by other AICord users
* **Installed:** The applets you either created or installed from Discover tab

{% hint style="info" %}
You'll be only able to modify code of your own applets. In case of installed public applets, you can only modify its secrets.
{% endhint %}

Now click on the <img src="/files/xASaXloghS54yqAvl7d5" alt="" data-size="line"> button, which will create a new applet and lead you straight to the **Applet Editor**:

<figure><img src="/files/2bVjnya4vEUjZytWMjNZ" alt=""><figcaption></figcaption></figure>

This interface might seem scary at first, but for now let's just get to know the essential areas & tabs on the top and walk through setting up our weather applet!

#### <i class="fa-code">:code:</i> **Code**

<figure><img src="/files/XmjTZegTYDWTtGrqqkJp" alt=""><figcaption></figcaption></figure>

Here you can write your applet code in exported JS functions. The most important thing to make your applet work is to export a function named `run` like this:

```javascript
export async function run(myAppletInput) {
  // Your code goes here
  // You can do anything, like call an API with fetch(), do calculations, etc.
  return "The applet then returns a text like this, and the character will use it for its final response";
}
```

**Applets work like this:** An user asks the character for current weather. The character looks for available applets it has access to, and checks their manifest to see what data applets are waiting for. After this, the character decides to call the weather applet's run function which does its own logic and returns a string with the result in a way that the character understands it. Then, the character will use this result and respond to the user.

For our weather applet, let's use this code for now. I'll explain its details later.

```javascript
export async function run({ city }) { // Gets input data in param
  const res = await fetch(`https://wttr.in/${city}?format=3`); // Fetches weather for the given city from wttr.in
  return await res.text(); // Returns the result in a text
}
```

#### <i class="fa-square-code">:square-code:</i> Manifest

This tab and field stores your applet input configuration and metadata. This JSON structure contains these fields mainly:

<table><thead><tr><th width="120">Field name</th><th>Purpose</th><th>Type</th></tr></thead><tbody><tr><td><code>name</code></td><td>Defines the name of your applet</td><td>string</td></tr><tr><td><code>description</code></td><td>Defines the description of your applet</td><td>string</td></tr><tr><td><code>visibility</code></td><td>This field stores whether your applet is public (visible to all AICord users) or private</td><td>string, can only be "public" or "private"</td></tr><tr><td><code>input</code></td><td>This contains the data structure of the inputs so the characters know what parameters to call your applet with</td><td>any (can be string or object)</td></tr><tr><td><code>triggers</code></td><td>Shows which events your applets support</td><td>list of strings</td></tr></tbody></table>

Here's a simple manifest for our weather applet:

```json
{
  "name": "getWeather",
  "description": "Gets weather of a specific city from wttr.in",
  "visibility": "private",
  "input": {
    "city":"string" // You should put the data type of input after input field name within ""
  },
  "triggers": []
}
```

Notice that we added an object to input with the name of the field (in our case `city`) and it's data type which is `string`

When the character will try to call our applet to get the weather in a specific city (now let's say Budapest), it will send this object to your applet:

```json
{
    "city":"Budapest"
}
```

So the applet's run function will get this data as the value of its input argument:

{% code title="applet.js" lineNumbers="true" %}

```javascript
export async function run(input) { ... // <- here input will contain the object {"city": "Budapets"} when gets called
```

{% endcode %}

Or you could "unbox" input values like this for your weather applet for easier access:

{% code title="applet.js" lineNumbers="true" %}

```javascript
export async function run({ city }) {
  const res = await fetch(`https://wttr.in/${city}?format=3`);
  return await res.text();
}
```

{% endcode %}

<figure><img src="/files/PCMmr2dIowBlgMxFmkeW" alt=""><figcaption></figcaption></figure>

#### <i class="fa-terminal">:terminal:</i> Test

In this section, you can test whether or not your applet works and does its job. You just need to add a JSON structure acting as if you were the character yourself and passed the data to the applet:

```json
{
    "city": "London"
}
```

Once data is added, click **Run Test**. The test output panel on the right side will show the output if applet call was successful or an error if not:

<figure><img src="/files/5H166SEzkIb7MijxVk0C" alt=""><figcaption></figcaption></figure>

## ⚡ Supported Functions

{% hint style="success" %}
Each function gets the inputs as one `input` param, and you need to unbox it.
{% endhint %}

| Function Name            | Triggered When...                                                                                         | Params                                    |
| ------------------------ | --------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
| run(input)               | **This is the default function.** AI uses the applet as a tool (for example when user asks about weather) | Anything your applet requires             |
| onGuildMemberAdd({user}) | A user joins the server                                                                                   | Discord `user` object within `user` value |

{% hint style="info" %}
**More coming soon!** Suggest new events on our Discord server!
{% endhint %}

### <i class="fa-brain">:brain:</i> Agentic AI + Applets = Magic

Applets power your AI characters to interact with the world. With applets, they can:

* Fetch stock prices
* Call APIs like OpenWeather or HuggingFace
* Send Discord messages
* React to users joining
* Access user-provided secrets (API keys)

It’s like giving your AI a Swiss Army knife, and you control what tools it gets.

### <i class="fa-lock">:lock:</i> Using Secrets

Add placeholders like:

```javascript
const API_KEY = "{{OPENWEATHER_KEY}}";
```

When run, AICord will inject the actual secret. You keep your code clean and safe. Secrets for applets can be defined on AICord Dashboard.

{% hint style="success" %}
If your applet is public and someone clones it, they will need to add their own API keys so not yours is used.
{% endhint %}

{% hint style="danger" %}
Never hardcode your actual secrets & keys into the code directly!!!
{% endhint %}

### ✅ What’s Allowed in Applets

Since Applets are executed as serverless functions in a safe container, there are some limitations. AICord Team is always working on extending these to allow you to use truly anything!

* ✅ `fetch()` — Make external API calls
* ✅ `console.log()` — Logs visible in your dashboard
* ✅ Use `export function` style syntax
* ✅ Use multiple named exports
* ✅ AICord passes some common and popular modules to your code automatically without you having to import them. You can suggest modules in Discord server.
* 🚫 3rd party `import`/`require` — Not supported (yet!)
* 🚫 `fs` or file system access
* 🚫 Long-running code (>60s timeout)

**Note**: You can still expose helper functions within your file and AICord will run it in a controlled Node.js VM with specific permissions you configure.

### 🌤 Sample Applet: Weather

```javascript
export async function run({ city }) {
  const res = await fetch(`https://wttr.in/${city}?format=3`);
  return await res.text();
}
```

<figure><img src="/files/GK5ItId5EBtOHxBI7P9j" alt=""><figcaption></figcaption></figure>

## <i class="fa-icons">:icons:</i> How Applets Work Behind the Scenes

{% code overflow="wrap" %}

```
1. An user asks the character for current weather.
2. The character looks for available applets it has access to, and checks their manifest to see what data applets are waiting for. 
3. AICord replaces all {{secrets}} placeholders with actual secrets.
4. The code is sandboxed and compiled.
5. The character decides to call the weather applet's run function which does its own logic and returns a string with the result in a way that the character understands it. 
6. The character will use this result and respond to the user.
```

{% endcode %}

Events are dynamically routed. If your applet exports `onGuildMemberAdd`, it runs *only* when a user joins.

{% hint style="info" %}
AICord has a GitHub repo with applet examples & templates [here](https://github.com/aicordapp/applet-example)
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.aicordapp.com/premium/aicord-applets.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.