> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.uponai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Code Node
> Execute JavaScript code directly in UponAI's sandbox — no external server needed.
Code node executes JavaScript code when the agent enters it. Unlike custom functions, code nodes run directly in UponAI's sandbox — no external server needed. The node is not intended for having a conversation with the user, but the agent can still talk while code is running if needed.
## Code Node vs Custom Function
| | Code Node | Custom Function |
| ------------- | ----------------------------------------------------------- | ------------------------------------------------ |
| Runs | JavaScript in UponAI's sandbox | HTTP request to your server |
| Requires | Nothing — runs directly | Your own API endpoint |
| Best for | Data transformation, simple API calls, logic & calculations | Complex integrations, accessing internal systems |
| Max code size | 5,000 characters | N/A (runs on your server) |
Code Node is designed for lightweight logic like formatting, calculations, and simple read-only lookups. Do not use it to access internal systems, write to production databases, or handle sensitive credentials. Both `dv` and `metadata` values are stored in plaintext with every call record. For integrations that require authentication, secrets management, or write access, use a Custom Function hosted on your own backend.
## Write Your Code
Click the Code node from the left sidebar to add it to the canvas.
Click **Open** on the code node to launch the code editor.
Write your JavaScript code in the editor. You have access to dynamic variables, call metadata, and the fetch function for HTTP requests.
```javascript theme={null}
// Example: look up an order and return the status
const response = await fetch("https://api.example.com/orders/" + dv.order_id);
const data = await response.json();
return { status: data.status, estimated_delivery: data.delivery_date };
```
Use **Store Fields as Variables** to extract values from your code's return value and save them as dynamic variables. Specify a variable name and the JSON path to the value.
For example, if your code returns `{ "status": "shipped", "estimated_delivery": "March 25" }`:
| Variable Name | JSON Path | Extracted Value |
| -------------- | ------------------- | --------------- |
| order\_status | status | "shipped" |
| delivery\_date | estimated\_delivery | "March 25" |
These variables can then be referenced as `{{order_status}}` and `{{delivery_date}}` in other nodes.
Click **Run Code** at the bottom of the editor to test. Use the Dynamic Variables dropdown to set test values — these only apply during testing and won't affect your live agent. The output panel shows the result and any `console.log()` output.
## JavaScript Environment
Your code runs in a JavaScript sandbox with the following globals available. The code editor provides autocomplete for globals, dynamic variable names, and built-in functions.
### `dv` — Dynamic Variables
Access your agent's dynamic variables as properties on the `dv` object. All values are strings.
```javascript theme={null}
const name = dv.customer_name; // "John Doe"
const orderId = dv.order_id; // "78542"
const total = parseFloat(dv.amount); // Convert to number if needed
```
### `metadata` — Call Metadata
Access metadata passed when the call was created via the API.
```javascript theme={null}
const customerId = metadata.customer_id;
const priority = metadata.priority_level;
```
Both `dv` and `metadata` values are stored in plaintext with every call record and are visible in call logs and API responses. Do not use them to pass API keys, database credentials, or other sensitive secrets.
### `fetch(url)` — HTTP Requests
Make HTTP requests to external APIs. Works like the standard Fetch API.
```javascript theme={null}
// GET request
const response = await fetch("https://api.example.com/data");
const data = await response.json();
// POST request
const response = await fetch("https://api.example.com/submit", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ name: dv.customer_name })
});
```
### `console.log()` — Debugging
Logs appear in the test output panel when using Run Code, and are also available in call logs.
```javascript theme={null}
console.log("Customer:", dv.customer_name);
console.log("API response:", JSON.stringify(data));
```
**Environment notes:**
* Standard JavaScript built-ins available: `Math`, `JSON`, `Date`, `Array`, `Object`, `String` methods, etc.
* External packages (`require`, `import`) are not available — use `fetch()` for external integrations
* Code is limited to 5,000 characters
## Examples
### Format data from dynamic variables
```javascript theme={null}
const fullName = dv.first_name + " " + dv.last_name;
const summary = `Customer ${fullName} (ID: ${dv.customer_id}) requested a callback.`;
return { full_name: fullName, summary: summary };
```
### Fetch data from a public API
```javascript theme={null}
const response = await fetch("https://api.weatherapi.com/v1/current.json?q=" + encodeURIComponent(dv.city));
const weather = await response.json();
return {
location: weather.location.name,
temperature: weather.current.temp_f + "°F",
condition: weather.current.condition.text
};
```
### Conditional logic with API call
```javascript theme={null}
const response = await fetch("https://api.example.com/customers/" + dv.customer_id);
const customer = await response.json();
if (customer.tier === "premium") {
return { action: "priority_support", wait_time: "0 minutes" };
} else if (customer.tier === "standard") {
return { action: "standard_queue", wait_time: "5 minutes" };
} else {
return { action: "general_queue", wait_time: "10 minutes" };
}
```
## Security and Architecture Guidance
| Use case | Recommended |
| ------------------------------------------------------------------------------------ | ----------------------- |
| Formatting, calculations, string cleanup | Code Node |
| Simple read-only lookups to low-risk public APIs | Code Node, with caution |
| Accessing internal systems or private APIs | Custom Function |
| Writing to CRM, EHR, booking, payment, or ticketing systems | Custom Function |
| Workflows requiring secrets, audit logs, retries, idempotency, or policy enforcement | Custom Function |
## When Can Transition Happen
**If Wait for Result is turned off:**
* Speak During Execution on → transitions once agent is done talking
* Speak During Execution off → transitions immediately after code starts running
* User interrupts → transition happens once user is done speaking
**If Wait for Result is turned on:**
* Speak During Execution on → transitions once code finishes and agent is done talking
* Speak During Execution off → transitions once code finishes
* User interrupts → transition happens once code finishes and user is done speaking
You can write transition conditions based on the code result or the extracted dynamic variables.
## Node Settings
| Setting | Description |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Speak During Execution | Agent says something while code runs. Choose **Prompt** (LLM generates) or **Static Text** (exact text). |
| Wait for Result | Agent waits for code to finish before transitioning. Guarantees result and variables are ready at the next node. |
| Timeout | How long code can run before timing out. Range: 5–60 seconds. Default: 30 seconds. |
| Global Node | See Global Node guide. |
| Block Interruptions | Agent will not be interrupted by user when speaking. |
| LLM | Choose a different model — used for speak-during-execution message generation when set to Prompt. |
| Fine-tuning Examples | Fine-tune transition behavior. See Finetune Examples guide. |