Skip to main content
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 may work differently. To learn more about Endpoint transformers, watch this webinar:

​
Restrictions

  • You can’t send HTTP requests from transformers to other Endpoints.

​
Limitations

  • You can only send one HTTP request per execution from a transformer.

​
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 one reply back. 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

​
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 FunctionTransformerDescription
handleInputInputExecutes when a user input is sent to an Endpoint, before the Flow is executed. The return value is sent to the Flow.
handleOutputOutputExecutes 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.
handleExecutionFinishedExecution finishedExecutes 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.
handleNotifyNotifyExecutes when you use the Notify API request. The return value is sent directly to the user.
handleInjectInjectExecutes when you use the Inject API request. The return value is sent to the Flow.

​
Working with Transformers

  • GUI
  • API
  • CLI
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.

​
Transformer Settings

SettingTypeDescription
Abort on Error in TransformerToggleIf activated, an error during the execution of a transformer function terminates the transformer execution.
Enable Input TransformerToggleActivates the Input transformer function.
Enable Output TransformerToggleActivates the Output transformer function.
Enable Execution Finished TransformerToggleActivates the Execution Finished transformer function.
Enable Notify TransformerToggleActivates the Notify transformer function.
Enable Inject TransformerToggleActivates the Inject transformer function.
TransformerCode editorThis code editor includes the code for each transformer function. By default, the code editor 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.

​
Send HTTP Requests

You can send HTTP requests to external services from a transformer. All transformer functions can access the httpRequest module. The module is invoked as a function that takes a single configuration object as argument. This object has the same format as the options object for the NPM module Request. Here is an example of an HTTP request: 
handleInput: async () => {
  const result = await httpRequest({
    uri: "<uri>",
    method: "POST",
    body: {},
    json: true,
  });

  console.log(result);
  return result;
};

​
Session Storage

The session storage is a storage 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.
You shouldn’t mutate complex objects, such as arrays, directly. Instead, you should mutate them locally and then re-assign them to the session storage object.
Here is an 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 may 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, the user input is still processed. If the transformer is essential to the pipeline, for example, when building a custom Endpoint integration, you may 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.
  • When an error occurs during the transformer execution, the logs list the line number where the error occurred. The line number may be incorrect because the logs don’t account for lines used for interfaces and comments. - Errors caused by a return value validation error don’t show a line number in the logs.

​
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 isn’t supported by Cognigy.AI 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.