Code node: run JavaScript in a conversation flow

​

When to use a Code node

​

Configure a Code node

1

Add a Code node

Select Code from the action nodes in the left sidebar.

2

Open the code editor

Select the node, then select Open under Code Configuration.

3

Write JavaScript

Read values from dv or metadata and return a JSON-serializable value. Objects are the easiest return type to map into response variables.

const start = new Date(dv.appointment_start);

if (Number.isNaN(start.getTime())) {
  return { valid: false, error: "Invalid appointment_start" };
}

return {
  valid: true,
  appointment_label: start.toISOString()
};

4

Store fields as variables

Under Store Fields as Variables, map a dynamic-variable name to a path in the returned value. For the example above, map appointment_is_valid to valid and appointment_label to appointment_label.See Store response variables for nested and array paths.

5

Configure execution and transitions

Set the timeout in the code editor. In the node settings, choose whether the agent talks or plays a typing sound while the code runs and whether the flow waits for the result before transitioning.

6

Test the code

Use Dynamic Variables in the editor to add test values, then select Run Code. The result and any console.log() output appear below the editor.Test values stay in the dashboard and don’t change the live agent. The dashboard test doesn’t populate metadata, so metadata-dependent code must handle an empty object during testing.

​

JavaScript environment

​

dv: dynamic variables

const customerName = dv.customer_name;
const orderTotal = Number(dv.order_total);
const callerNumber = dv.user_number;

​

metadata: call or chat metadata

const customerId = metadata.customer_id;
const priority = metadata.priority_level;

​

fetch(url, options): HTTP requests

const response = await fetch("https://api.zippopotam.us/us/90210");

if (!response.ok) {
  return { found: false, status: response.status };
}

const location = await response.json();
return {
  found: true,
  city: location.places[0]["place name"],
  state: location.places[0]["state abbreviation"]
};

​

console.log(): test output

console.log("Customer:", dv.customer_name);

​

Runtime limits

​

Store response variables

return {
  status: "confirmed",
  order: {
    id: "ord_123",
    items: [{ name: "Replacement filter" }]
  }
};

​

Control transition timing

• When it is on, Retell waits for the code to finish before evaluating the node’s transition conditions. The return value and stored response variables are available to those conditions and the next node.
• When it is off, the flow can transition while the code is still running. The result and stored variables might not be available to the next node.

​

Node settings

​

Use Code node safely

• Don’t put API keys, credentials, or sensitive tokens in code, dv, or metadata.
• Use fetch() for low-risk HTTP reads. Put authenticated requests and state-changing operations behind a custom function on your backend.
• For critical routing, provide a safe else path. A timeout, thrown error, or sandbox failure doesn’t retry automatically and doesn’t extract response variables.

​

FAQ