Transformers - Cognigy Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

Use this file to discover all available pages before exploring further.

In Cognigy.AI 2025.25.0, transformers will start using the axios library for handling HTTP requests internally instead of request-promise. This change occurs to improve security and maintainability. The following HTTP request options will still be supported:

URL configuration — uri, url
Request method — method
Request headers and configuration — headers
Request body — form, json
Query parameters — qs, qsStringifyOptions
Authentication — auth
Connection and network — proxy, maxRedirects, gzip, encoding

If you use other HTTP request options, review your transformer code to ensure it is compatible with the axios library before the release of Cognigy.AI 2025.25.0.

Endpoint Transformers are functions that convert the text and data sent between the Endpoint and the Flow as well as through the Inject and Notify API requests. These functions allow you to manipulate the data from the user input, the Flow output, and third-party API services.Transformers fully support TypeScript and JavaScript, including npm modules.You can use transformers to:

Convert request payloads from an Endpoint before sending them to a Flow, for example, to encrypt data.
Convert the Flow output before sending it to an Endpoint.
Translate messages from the user into the Flow language.
Customize the default and custom Endpoint interfaces.
Convert a channel output to be compatible with another channel. For example, convert a Webchat output into a WhatsApp-compatible output.
Create custom Endpoints for additional integrations and handle webhook events from the custom Endpoints.

Depending on the type of the Endpoint in which you use the transformers, they might work differently. To learn more about Endpoint transformers, watch this webinar:

Cognigy Sessions: Endpoint Transformers - YouTube

Restrictions

You can’t send HTTP requests from Endpoint transformers to other Endpoints.
Endpoint transformers operate only on data exchanged between the Endpoint and the Flow. They don’t modify the prompt or response of an LLM Prompt Node or AI Agent Node.

Limitations

You can only send one HTTP request per execution from a transformer.
HTTP requests from transformer functions have a 5-second timeout. When the request times out, Flow execution throws an error and logs it. You can change or remove the timeout:
- For SaaS installations, contact Cognigy technical support.
- For on-premises installations, change the timeout by setting it in milliseconds in TRANSFORMER_FUNCTION_EXECUTION_TIMEOUT_MS or remove it by setting FEATURE_DISABLE_TRANSFORMER_HTTP_TIMEOUT to true.

Endpoint Types

There are three different types of Endpoints based on the underlying technology.

REST-based Endpoints
Webhook-based Endpoints
Socket-based Endpoints

REST-based Endpoints receive messages from the user and send a single reply. For these Endpoints, you can add more than one Say Node in the Flow, but all the outputs are processed only after the Flow execution has finished. The outputs are concatenated into one message and then sent to the user. The REST-based Endpoints are:

Alexa
Dialogflow
Twilio
Twilio SMS
Microsoft Teams
Userlike
AudioCodes
REST

Webhook-based Endpoints receive user messages and reply after each input. For these Endpoints, you can process each output after the user input. The webhook-based Endpoints are:

Facebook (Meta) Messenger
Slack
Microsoft Bot Framework
Sunshine Conversations
LINE
RingCentral Engage
Intercom
WhatsApp
Webhook

Socket-based Endpoints receive messages from the user and can reply after each input. For these Endpoints, you can process each output after the user input. The socket-based Endpoints are:

Webchat
Socket

Transformer Functions

The transformer function determines the transformer you use in the Endpoint settings. The following table provides an overview of the transformer functions:

Transformer Function	Transformer	Description
handleInput	Input	Executes when a user input is sent to an Endpoint, before the Flow is executed. The return value is sent to the Flow.
handleOutput	Output	Executes when a Flow sends an output to an Endpoint. For webhook- and socket-based Endpoints, the return value of each output is sent to the user. For REST-based Endpoints, the return value is stored and can be sent to the user after the Flow execution has finished with the execution finished transformer.
handleExecutionFinished	Execution finished	Executes when the Flow execution has finished. The return value is sent to the user. In this case, all outputs are concatenated and sent to the user. Applies only to REST-based Endpoints in which you use an output transformer.
handleNotify	Notify	Executes when you use the Notify API request. The return value is sent directly to the user.
handleInject	Inject	Executes when you use the Inject API request. The return value is sent to the Flow.

Working with Transformers

You can configure the transformer functions in the Transformer Functions section of the Endpoint settings. You need to activate the transformer functions individually and provide the corresponding code in the Transformer editor.

You can configure transformer settings using the Cognigy.AI API.

You can configure the transformer functions locally and deploy them with the Cognigy CLI. To do this, follow these steps:

In Deploy > Endpoints, select an Endpoint and activate the transformer functions you want to use in the Endpoint settings.
Clone your AI Agent to your local machine.
Make the changes to the transformer functions in the transformers.ts file in your Endpoint’s folder, for example, <root-directory>/agent/endpoints/Webchat/transformer.ts, where Webchat is the name of your Endpoint.
Restore the AI Agent to Cognigy.AI.

Transformer Settings

Setting	Type	Description
Abort on Error in Transformer	Toggle	Terminates transformer execution when an error occurs during execution.
Enable Input Transformer	Toggle	Activates the Input transformer function.
Enable Output Transformer	Toggle	Activates the Output transformer function.
Enable Execution Finished Transformer	Toggle	Activates the Execution Finished transformer function.
Enable Notify Transformer	Toggle	Activates the Notify transformer function.
Enable Inject Transformer	Toggle	Activates the Inject transformer function.
Transformer	Code editor	Includes the code for each transformer function. By default, includes one instance of each transformer function.

Available JavaScript Modules

npm Modules

The following npm modules are available for use in a transformer:

uuid — for generating UUIDs.
crypto — for encrypting data.
_ (Lodash) — for manipulating arrays, objects, and strings.
moment — for manipulating dates and times.
xmljs — for manipulating XML data.

Text Cleaner Class

Transformers can use the getTextCleaner function to retrieve an instance of the Text Cleaner class, which allows you to preprocess user input.

Modify the User ID in Transformers

Endpoint transformers can modify the user ID. If a transformer changes the user ID, Cognigy.AI uses the updated value consistently throughout the entire processing pipeline, including:

Flow execution
Notify API requests
xApps
Live Follow
Logs

To avoid exposing personally identifiable information, for example, phone numbers or email addresses, and to support GDPR compliance, hash the user ID.When implementing user ID transformation:

Use a deterministic method: the same input must always produce the same output.
Use simple string prefixing, such as "hashed_" + userId, only for testing or development. Prefixing doesn’t provide real security. In production, use a cryptographic hash function, such as SHA-256.

Example: Hashing the User ID (SHA-256)

const crypto = require("crypto");

function hashUserId(userId) {
    return crypto
        .createHash("sha256")
        .update(userId)
        .digest("hex");
}

handleInput: async ({ payload }) => {
    return {
        userId: hashUserId(payload.userId),
        sessionId: payload.sessionId,
        text: payload.text,
        data: payload.data
    };
};

Send HTTP Requests

You can send HTTP requests to external services from a transformer. All transformer functions can access the httpRequest module. Call the module as a function that takes a single configuration object as argument. You can use the following formats for the configuration object:

Axios
request-promise (deprecated)

The configuration object follows the format described in the Axios Request Config documentation. For example:

handleInput: async ({ payload }) => {
  const result = await httpRequest({
    url: "<url>",
    method: "POST",
    data: {
      userId: payload.userId,
      text: payload.text
    }
  });

console.log(JSON.stringify(result)); // Registers results on the Logs page
  return {
    userId: payload.userId,
    sessionId: payload.sessionId,
    text: payload.text,
    data: payload.data
  };
},

The request-promise library is deprecated. Review your transformer code to ensure it is compatible with the axios library.

Session Storage

The session storage is a JSON object available to all transformer functions that persists throughout a session. You can use the session storage to store variables for later use in other transformer functions or to store the conversation state. To access the stored data, use the getSessionStorage function inside the transformer functions. The getSessionStorage function takes the userId and sessionId as arguments and returns a promise. The returned promise resolves with the sessionStorage object, which can be manipulated as a regular object.

Example of session storage usage:

const handleOutput: async ({ userId, sessionId }) => {
    const sessionStorage = await getSessionStorage(userId, sessionId);

sessionStorage.test = "test";

// Mutating complex objects
    // Instead of changing the objects directly inside sessionStorage,
    // change them locally and then assign them to the sessionStorage
    let tempArr = sessionStorage.arr || [];
    tempArr.push(1);
    tempArr.push(2);
    sessionStorage.arr = tempArr;
}

Stop Transformer Execution

Every transformer function expects a certain return value that is further processed in an Endpoint or Flow. In certain cases, you might want to stop the execution completely, for example, if the output from a Flow is forwarded to another platform. To stop the transformer execution, set the transformer function to return a falsy value, such as null or void.

Error Handling in Transformers

By default, transformers log errors on the Logs page and continue with the Flow execution. This means that if an error occurs during the transformer execution, including timeout, the user input is still processed. If the transformer is essential to the pipeline, for example, when building a custom Endpoint integration, you might want to prevent the Flow execution after an error in the transformer execution. To do this, activate the Abort on Error in Transformer setting in the transformer settings.

Log Transformer Events

With the following methods, you can log transformer events on the Logs page:

console.log — as a debug log entry.
console.info — as an info log entry.
console.error — as an error log entry.

Create a Custom Endpoint

With transformers, you can create an integration with a custom Endpoint that Cognigy.AI doesn’t support by default. To create a custom Endpoint, you need to know the Endpoint type of the channel. Then, you can use a transformer to call the custom Endpoint service.

Transformer Examples

You can find examples of various transformers in the Cognigy GitHub repository.