Build and use a Custom Action

Custom Actions let you extend your automations with your own logic. When the standard blocks do not cover a use case, you can write a Custom Action in TypeScript to do things like call an external API, look up a record in another system, transform data, or apply custom business rules. Once published, a Custom Action becomes a reusable block that you can drop into any flow.

This guide explains where to find Custom Actions, how to build one, and how to use it inside an automation flow. For a refresher on flows themselves, see Create your first automation flow.

What is a Custom Action?

A Custom Action is a small TypeScript program that runs as a step in an automation. It runs in a secure, sandboxed environment, so you have access to the same modules you would expect in a standard Node.js application, plus a special tekst object that gives your code the context of the message and automation it is running in.

In practice this means you can:

• Read the incoming message and your models' predictions for it
• Call external services such as an order management system or a CRM
• Apply custom logic that the standard action blocks do not offer
• Pass data back into the automation so later steps can use it

Custom Actions are private to your organization and are versioned, so you can safely improve them over time without breaking the flows that already use them.

Where to find Custom Actions

Custom Actions live in the Automation area of the platform. Open <yourcompany>.tekst.com/flows (or click Automations in the side menu), then select the Custom Actions tab at the top of the page. This tab is available to administrators.

The Custom Actions page lists every action your organization has created, along with the automations that use it, its version, and when it was last modified. From here you can search existing actions or create a new one.

Create a new Custom Action

1. Open the editor

On the Custom Actions page, click New custom action. This opens a "What do you want to build?" screen where you describe the action in a few sentences. Click Start Building to have Tekst generate a first version of the code from your description, or Start from Scratch to go straight to an empty code editor. Either way you land in the code editor, where you write and test your code.

Give your action a clear name and description at the top of the editor. A good name and description help your colleagues understand what the action does when they add it to a flow.

2. Write your code

The editor is a full TypeScript environment with syntax highlighting and type checking. The Problems tab below the editor lists any errors or warnings, and the Output tab shows logs when you run your code.

Inside your code you have access to the tekst object, which carries everything your action needs about the context it is running in:

• tekst.input contains the incoming data. tekst.input.thread holds the message data, tekst.input.facet holds the output of your active models (for example the predicted tag), and tekst.input.integrationType tells you which integration triggered the automation.
• tekst.variables holds the configurable values that the person using your action sets when they add it to a flow.
• tekst.secrets holds sensitive values such as API keys.
• tekst.dump(...) is how you send data back to the automation so that later steps can use it.

Because tekst.input.thread differs per integration, it is good practice to check tekst.input.integrationType and handle the relevant thread shape accordingly.

3. Configure variables, secrets, and dependencies

Open the settings panel in the editor to configure the inputs and resources your action needs:

• Variables let the person adding your action to a flow pass in non-sensitive configuration values. You define each variable's type and name, optionally provide a list of accepted values, and mark whether it is required. Variables are read in your code through tekst.variables.<name>.
• Secrets are for sensitive values such as API keys or client secrets. They are stored securely and read through tekst.secrets.<NAME>. By convention, secrets are named in uppercase with underscores between words, for example tekst.secrets.ORDER_API_KEY.
• Dependencies let you install packages from the npm registry to extend what your action can do. Search for a package and add it as either a runtime dependency (needed when the action runs) or a development dependency (only needed while you write the code).

4. Return data to the automation

If you want later steps in a flow to use data your action produced, pass an object to tekst.dump(...). Anything you dump becomes available in subsequent steps under the custom namespace, for example custom.orderNumber. This is what makes Custom Actions powerful for enriching a flow: an action can look up information and hand it back so a later condition or action can act on it.

5. Test before you publish

Use the Run button to execute your code and watch the result in the Output tab. To test against realistic data, open the simulate panel, choose an integration type and provide sample message content, then run the action. This lets you confirm the behavior before any live message is processed.

When the Problems tab reports no errors, your code is ready to publish.

6. Publish a version

Custom Actions are versioned. When you are happy with your changes, open the publish panel, add a short description of what changed, and publish. You can publish a major, minor, or patch version depending on the size of the change. Each published version is listed in the editor, so you can always see the history of an action and who published each version.

Flows always reference a published version, so your work in the editor does not affect live automations until you publish.

Use a Custom Action in a flow

Once a Custom Action is published, it is available as a building block in the flow editor.

1. Open or create a flow as described in Create your first automation flow.
2. Add a new block by hovering over an existing block and clicking the + icon.
3. In the block picker, open the Custom section. Your published Custom Actions appear here.
4. Select your action to add it to the flow.

If your action defines variables or secrets, you will be prompted to fill those in for this particular flow. Required variables must be set before the flow can be activated.

From then on, the Custom Action runs as a step whenever the flow reaches it, and any data you returned with tekst.dump(...) is available to the blocks that follow.

Related articles

• What are automations?
• Create your first automation flow
• Using the filter block in automations