- 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.
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 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
- 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
Setting | Type | Description |
---|---|---|
Abort on Error in Transformer | Toggle | If activated, an error during the execution of a transformer function terminates the transformer 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 | This 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 thegetTextCleaner
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 thehttpRequest
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:
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 thegetSessionStorage
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.
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 asnull
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 adebug
log entry.console.info
— as aninfo
log entry.console.error
— as anerror
log entry.