Input Transformer - 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.

The Input Transformer converts the user input after it’s sent to an Endpoint. This allows you to manipulate the user input data before it is sent to the Flow, for example, to communicate with external systems, to implement integrations with a custom channel, and much more. You can configure the input transformer in the handleInput function in the Endpoint settings or via CLI.

Restrictions

• The return value is validated against a set of rules. If these rules aren’t met, the transformer throws an error. The following rules apply:
  • userId is a string with up to 256 characters.
  • sessionId is a string with up to 256 characters.
  • text is a string with up to 10,000 characters.
  • data is an object.

Transformer Function Arguments

Depending on the Endpoint type in which you want to use the transformer, the function arguments vary:

• Webhook- and REST-based Endpoints
• Socket-based Endpoints

Endpoint Configuration Object

endpoint Object Properties

Return Values

The input transformer returns the user ID, session ID, text, and data, which are subsequently sent to the Flow. These values are extracted from the Endpoint payload. The payload format is specific to the Endpoint type you use, for example, Alexa or Facebook (Meta) Messenger. Read the documentation of the specific Endpoint to know how to format the payload.

Example of Transformer Return Values

return {
    userId: payload.userId,
    sessionId: payload.sessionId,
    text: payload.text,
    data: { "test": 1 }
};

Undefined Return Values

If the transformer returns undefined for userId, sessionId, text, or data, this means that the transformer uses the value from the Endpoint.

Example of Undefined Return Values

The following example overwrites text and data, but uses the userId and sessionId from the Endpoint:

return {
    userId: undefined,
    sessionId: undefined,
    text: payload.text,
    data: { "test": 1 }
};

Endpoints Event Messages

The Webchat and the Socket.IO Endpoints output event messages that indicate user activity, such as whether the user is connected (user-connected) or disconnected (user-disconnected). These event messages neither trigger Flows nor are counted. The event messages inform handover providers about user activity, allowing human agents to determine if the user is still engaged in the conversation. You can access the event messages with the data._cognigy.event property in the return value of the input transformer.

Example of Return Values with Event Messages

return {
    "userId": payload.userId,
    "sessionId": payload.sessionId,
    "text": payload.text,
    "data": {
        "_cognigy": {
              "event": {
                "type": "user-connected"
            }
        }
    }
}

If you want to access event messages in the input transformer, don’t modify them. The event messages are only recognized if their data payload follows a specific format. The following code snippet shows how to use event messages in the input transformer:

Example of Input Transformer with Event Messages

{
handleInput: async ({ payload, endpoint }) => {
  if (!!payload.data?._cognigy?.event) {
// pass on "event messages" without modification
      return payload;
    }

// rest of your input transformer code
  }
}

Transformers and Conversation Counts

Conversations in Cognigy.AI are counted if the input transformer returns any result but falsy.

Last modified on April 21, 2026