Use a code step in an automation

A code step lets you run a small piece of custom logic directly inside an automation flow, alongside your actions, conditions, and model steps. It is a lightweight way to drop in tailored behavior exactly where you need it - you write and edit the code without leaving the builder, and a built-in AI assistant can generate the code for you, so you do not need coding experience to use one.

This guide explains when to reach for a code step, how to add one to a flow, and how to write, test, and configure it. For a refresher on flows themselves, see Create your first automation flow.

What is a code step?

A code step runs a short TypeScript program as a single step in your flow. When the flow reaches the step, Tekst runs your code with the data available at that point in the flow: the conversation that triggered the automation and the predictions of your models. Any values your code saves as output become available to the steps that follow.

You can keep the logic simple, or, for more advanced needs, add npm packages as dependencies. Because the code lives inside the flow, you can iterate on it quickly and see at a glance what it does.

Code step or Custom Action?

Code steps and Custom Actions both let you add custom logic, but they suit different situations:

• Use a code step when the logic is only needed in a single automation. You keep it right where it is used and can edit it in place, without creating a separate, reusable building block.
• Use a Custom Action when you want logic that can be reused across many automations, with versioning and shared variables and secrets. Code steps do not have variables or secrets of their own, so use a Custom Action when your logic needs something like an API key. See Build and use a Custom Action.

A good rule of thumb: start with a code step for one-off logic, and promote the logic to a Custom Action when you find yourself needing it in more than one flow.

Add a code step to a flow

In the automation builder:

1. Open or create a flow as described in Create your first automation flow.
2. Hover over the block you want the code step to run after, then click the + icon that appears.
3. In the block picker, go to Utilities and select Code ("Run custom TypeScript code").

The code step is added to your flow, ready for you to write its logic.

Write the code

Select the code step to open its side panel. The panel contains a code editor where you can write directly, and an Open in code editor link that opens a larger editor with the AI assistant next to your code.

Use the AI assistant

In the larger code editor, describe what you want the code to do in plain language, and the AI assistant writes and edits the code for you. It can also add npm packages when your logic needs them. This is the fastest way to get started and does not require any coding experience. Review the result, reply to the assistant with any changes, and repeat until the code does what you want.

Write it yourself

The editor is a TypeScript editor with syntax highlighting, autocomplete, and live error checking, so you can catch problems as you type. A code step follows a few rules:

• Put your logic inside an async function called run. Tekst calls run() for you, without any arguments, so do not call it yourself and do not give it parameters.
• Import the Tekst SDK with import tekst from "tekst"; at the top of the code.
• Read the data from the flow through tekst.input. Use tekst.input.thread for the conversation that triggered the automation, and tekst.input.facet for the predictions of your classification, extraction, and matching models. The editor's autocomplete shows the fields available for your inbox type and for the models that run before this step.
• Read the output of a step that runs before the code step with $("<step name>"). See Use data from earlier steps in a code step.
• Save output with tekst.dump({ key: value }). The value run returns is not used, so anything later steps need must go through tekst.dump. You can call it more than once; each call adds to the output.

The SDK also includes a few helpers:

• tekst.getFile(ref) and tekst.getFileText(ref) read the content of an attachment, using the ref from the attachment's details in tekst.input.thread.
• tekst.generateText(prompt, { system }) asks a Tekst-hosted language model for a text answer. You do not need your own API key for this.
• console.log("message", { extra: "details" }) writes to the step's logs, which you can check after a run.

Here is a short example that builds a reference from the conversation ID and saves it as output:

import tekst from "tekst";

async function run() {
  const threadId = tekst.input.thread.id;
  const today = new Date().toISOString().slice(0, 10);

  console.log("Building reference", { threadId });

  tekst.dump({ reference: `${threadId}-${today}` });
}

Use the output in later steps

In the fields of the blocks that come after the code step, refer to a value you dumped with {{custom.<key>}}. In the example above, that is {{custom.reference}}. Output keys from all code steps in a flow share the same custom namespace, so give each value a distinct name.

Add packages

If your logic needs functionality beyond plain TypeScript, click Dependencies in the side panel or the code editor, then Add dependency to search the npm registry. Once added, you can import and use the package in your code just as you would in a Node.js project. Dependencies are installed each time the step runs.

View the code in the flow

Select a code step on the canvas to see its code in the side panel. When the automation is not in edit mode, the panel shows a read-only view of the code, so you can scan a flow and understand where your custom logic runs without changing anything.

Configure the step's settings

Click the settings icon next to Code Configuration in the side panel to open the advanced code settings:

• Estimated time saved (seconds): How many seconds the step saves compared to doing the work by hand. This feeds into your automation's reporting on the impact of the flow.
• Continue flow on error: By default, if the code throws an error the flow stops at that step. Enable this option to let the flow continue to the next step even when the code fails.

Test before you publish

Run a test to confirm the code step behaves as expected before it processes live messages:

1. Click Test in the toolbar at the bottom of the canvas to open the Test automation panel.
2. Pick the message to test with and choose a test mode. Code steps run your own code and can make real changes in external systems, so Safe mode skips them. Choose Full, or Custom with the code step selected, to include it in the test.
3. Run the test and select the code step to check its output and logs. Make sure the values it dumps are the ones later steps expect, and that error handling behaves the way you want.

Once you are happy with the result, click Review and publish. The review checks your flow before publishing and points out common code step problems, such as code without a run function or code that calls run() itself.

Related articles

• What are automations?
• Create your first automation flow
• Build and use a Custom Action
• Using the filter block in automations