API Functions - Cognigy Documentation

Documentation Index

Fetch the complete documentation index at: /llms.txt

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

CognigyScript

Use these functions to parse and evaluate CognigyScript expressions in text or conditions at run-time.

api.parseCognigyScript

Parses CognigyScript text or conditions.

Parameters

Returns Promise<any>
Example

// Parse CognigyScript as text
const parsedText = api.parseCognigyScript(
    "Hello {{cc.text}}, welcome!",
    false
);
api.say(parsedText);

// Parse CognigyScript as a condition
const parsedCondition = api.parseCognigyScript(
    "{{input.currentTime.year > 2024}}",
    true
);

if (parsedCondition === "true") {
    api.say("Condition is true");
} else {
    api.say("Condition is false");
}

api.parseCognigyScriptCondition

Evaluates a CognigyScript expression and returns a true or false value.
CognigyScript allows you to embed expressions like {{context.value > 5}} within strings. This function extracts and evaluates such an expression, used in logic checks for Flows, conditions, or custom functions.
This function is useful for dynamically checking conditions at run-time based on session data and information from the Input, Context, or Profile objects.

Parameters

Returns Promise<string>
Example

const parseCognigyScriptCondition = api.parseCognigyScriptCondition(
    "{{input.currentTime.year > 2024}}"
);
api.say(`${parseCognigyScriptCondition}`);

api.parseCognigyScriptText

Parses and renders a text string containing CognigyScript expressions. Each CognigyScript expression, for example, {{cc.userName}}, is evaluated using the current execution context.

Parameters

Returns Promise<string>
Example

const output = api.parseCognigyScriptText("Hello {{cc.text}}, welcome to {{cc.city}}!");
api.say(`The current state is: ${output}`);

Contact Profiles

Use these functions to activate, deactivate, delete, merge, and update Contact Profiles during a conversation.

api.activateProfile

Activates the Contact Profile.
Call this function to reactivate read and write operations on a previously deactivated Contact Profile.

Parameters None
Returns Promise<any>
Example

// Reactivate a previously deactivated Profile
api.activateProfile();

api.addContactMemory

Adds an entry to the memories array of the Profile object.

Parameters

Returns void
Example

api.addContactMemory("ppl");

api.deactivateProfile

Deactivates the Contact Profile. While the Contact Profile is deactivated, no data can be read from or written to the Contact Profile.

Parameters None
Returns Promise<any>
Example

// Deactivate a Contact Profile
api.deactivateProfile();

api.deleteProfile

Permanently deletes the Contact Profile from the system.

Parameters None
Returns Promise<any>
Example

// Delete the Contact Profile
api.deleteProfile();

api.mergeProfile

Merges the current Contact Profile with another one.
This function is useful for combining duplicate Contact Profiles or moving data between users.

Parameters

Returns Promise<any>
Example

api.mergeProfile("c-89374201a7bd5a9e4");

api.updateProfile

Updates a value in the current Contact Profile.

Parameters

Returns Promise<any>
Example

// Update the 'email' field of the current Contact Profile
api.updateProfile("email", "user@example.com");

// Update a custom string field
api.updateProfile("subscriptionStatus", "active");

// Update a numeric field
api.updateProfile("loyaltyPoints", 120);

// Update a boolean field
api.updateProfile("marketingConsent", true);

Context Object

Use these functions to read, write, and reset the Context object so you can store and manipulate conversation-scoped data across Nodes.

api.addToContext

Adds a value to the Context object, either replacing an existing value or appending to it as an array.

Parameters

Returns void
Example

// Simple mode: replaces existing value
api.addToContext("user.city", "Berlin", "simple");
// Context: { user: { city: "Berlin" } }

api.addToContext("user.city", "Munich", "simple");
// Context: { user: { city: "Munich" } }

// Array mode: appends to an array
api.addToContext("user.purchases", "book", "array");
// Context: { user: { purchases: ["book"] } }

api.addToContext("user.purchases", "laptop", "array");
api.addToContext("user.purchases", "coffee", "array");
// Context: { user: { purchases: ["book", "laptop", "coffee"] } }

api.deleteContext

Deletes the key and its value from the Context object.

Parameters

Returns void
Example

api.deleteContext("user.city");

api.getContext

Retrieves data from the specified key in the Context object.

Parameters

Returns any: The requested context data. Example

api.getContext("user.profile.name");

api.getConversationTranscript

Retrieves the current conversation transcript, including the last 10 user inputs and the associated outputs from the AI Agent.

Parameters

Returns Either the JSON array of conversation entries or the string representation. Example

// Get the transcript
const transcriptJson = api.getConversationTranscript({ turnLimit: 5 });

// Convert the JSON array to a string
const transcriptJsonPrint = JSON.stringify(transcriptJson, null, 2);

// Send it to the user
api.say(transcriptJsonPrint);

api.removeFromContext

Removes information from the Context object either by deleting a key entirely or by removing specific entries from an array stored at that key.

Parameters

Returns void
Example

// Simple mode: remove the entire key
api.removeFromContext("user.city", null, "simple");
// Context: { user: { city: undefined } }

// Array mode: remove specific values from an array
api.addToContext("user.purchases", "book", "array");
api.addToContext("user.purchases", "laptop", "array");
api.addToContext("user.purchases", "coffee", "array");

// Remove "laptop" from the purchases array
api.removeFromContext("user.purchases", "laptop", "array");
// Context: { user: { purchases: ["book", "coffee"] } }

api.resetContext

Resets the Context object for the current conversation. All keys and values added during the conversation are removed.

Parameters None
Returns void
Example

// Remove all context data added during the conversation
api.resetContext();

api.setContext

Sets the value for a specific key in the Context object, replacing any existing value.

Parameters

Returns void
Example

api.setContext("user.city", "Berlin");

Encoding and Decoding

Use these functions to handle string encoding and decoding, such as converting text to Base64 for safe transmission or decoding Base64 strings back to UTF-8.

api.base64Decode

Base64 decodes a given string.

Parameters

Returns string: The decoded string as UTF-8.
Example

const decoded = api.base64Decode("SGVsbG8sIFdvcmxkIQ==");
api.say(`Decoded string: ${decoded}`); // Output: "Hello, World!"

api.base64Encode

Base64 encodes a given string.

Parameters

Returns string: The base64 encoded string.
Example

const encoded = api.base64Encode("Hello, World!");
api.say(`Encoded string: ${encoded}`); // Output: "SGVsbG8sIFdvcmxkIQ=="

Execution Control

Use these functions to control Flow execution, including adding conditional Entrypoints, jumping to specific Nodes or Flows, resetting overrides, stopping execution, and simulating new inputs.

api.addConditionalEntrypoint

Adds a conditional Entrypoint for the current conversation.
If {condition} is met within the next {retentionTime} inputs, Flow execution starts at {entrypoint}.

Parameters

Returns void
Example

api.addConditionalEntrypoint({
    entrypoint: "c40c50f3-2f51-422c-8a3e-748e7cc92ed0",
    retentionTime: 2,
    condition: "input.text.includes('@')"
});

api.resetNextNodes

Clears any active overrides for the next Node in the Flow. This function is useful when you’ve changed the next Node using the api.setNextNode function, and you want to return to the default Flow behavior.

Parameters None
Returns void
Example

// Imagine you previously used api.setNextNode("fallback-node") to redirect the Flow.
// Now, you want to clear that override so the Flow continues as originally defined.
api.resetNextNodes();

api.setNextNode

Sets the Node with the given nodeId to be executed immediately after the current one.
This function is used by If and Lookup Nodes to select child Nodes based on their configuration.

Parameters

Returns void
Example

// The current Node is executing inside a Flow, and you want to control which Node should be executed next based on some logic.
// In this example, the execution will jump to a Node with the nodeId "c4c5c267-55d8-44ae-a123-f351d237f496" immediately after the current Node finishes.
api.setNextNode("c4c5c267-55d8-44ae-a123-f351d237f496");

// To continue the conversation in a different Flow after the current Node, specify both the target nodeId and the flowId.
// The Node with nodeId "c4c5c267-55d8-44ae-a123-f351d237f496" must be marked as an Entrypoint in the target Flow with flowId "67f511b11acdc139f91946b8".
// Execution will jump directly to that Node after the current one finishes.
api.setNextNode("c4c5c267-55d8-44ae-a123-f351d237f496", "67f511b11acdc139f91946b8");

api.stopExecution

Stops the execution of the Flow.

Parameters None
Returns void
Example

api.stopExecution();

api.thinkV2

Restarts Flow execution with a simulated input using the provided text and data.

Parameters

Returns void
Example

api.thinkV2(
    "Hello, how's the weather?",
    { location: "Berlin", units: "Celsius" }
);

Input and Output

Use these functions to enrich the Input object and send text or data responses to the user from a Code or Extension Node.

api.addToInput

Adds a key-value pair to the Input object.

Parameters

Returns void
Example

api.addToInput("username", "John Doe");

api.output / api.say

Executes a basic output to the contact, similar to the Say Node.

Parameters

_cognigy is an internal parameter and not part of the public API. This parameter is unsupported and may change without notice.

Returns void
Example

// Send text with additional data
api.say("Hello, this is a message from the Code Node!", { customData: 123 });

// `api.output` is an alias of `api.say`
api.output("Hello, this is a message from the Code Node!", { customData: 123 });

Logging and Monitoring

Use these functions to write Project logs, send debug messages, inspect LLM token usage, track analytics steps, and configure sensitive logging behavior.

api.completeGoal

Completes the task. The information that the task has been completed is recorded and is available in Cognigy Insights and the Cognigy.AI OData endpoint.

Parameters

Returns Promise<void>
Example

api.completeGoal("Order Pizza");

api.emitToOpsCenter

Forwards an error to the Ops Center Error page. Automatically sets the component to Flow and the subcomponent to FlowNodeExecution.

Parameters

Returns void
Example

api.emitToOpsCenter({
    projectId: "6874becb018c552bc267cc51",
    title: "Something went wrong",
});

api.getLLMTokenUsageForSession

Retrieves the LLM token usage information for the current session.

Parameters None
Returns

{
    "llmDisplayName": string,
    "providerType": string,
    "modelType": string,
    "usage": {
        "inputTokens": number,
        "outputTokens": number
    }
}

Example

api.getLLMTokenUsageForSession();

api.log

Writes a message to the Project logs.

Parameters

Returns void
Example

api.log("info", "This is an informational message.");
api.log("error", "An error occurred during Flow execution.");
api.log("debug", "Debugging details for Flow execution.");

api.logDebugMessage / api.logDebugError

Sends a debug message. The message is visible only in the Interaction Panel with activated debug mode.

Parameters

Returns void
Example

// Log a simple string
api.logDebugMessage("Flow started successfully", "Flow Info");

// Log multiple variables together
const sessionInfo = { sessionId: "abc123", timestamp: new Date().toISOString() };
const userData = { name: "Alice", age: 25 };

// Combine objects into one for logging
api.logDebugMessage(JSON.stringify({ sessionInfo, userData }, null, 2), "Session & User Info");

api.setSensitiveLoggingSettings

Configures masking of sensitive data in logs, analytics, and conversation content for the session.

Parameters

Returns void
Example

api.setSensitiveLoggingSettings({
    maskLogging: true, // Mask sensitive information in conversation logs
    maskAnalytics: true, // Mask sensitive information in analytics and Insights
    maskIPAddress: true, // Optional: mask user IP addresses
    disableConversations: true, // Disable conversation logging entirely
    disableIntentTrainer: true // Disable logging for the Intent Trainer
}, "trace-12345"); // Optional trace ID for debugging

api.trackAnalyticsStep

Tracks a custom analytics step for the session. Useful for monitoring user interactions or workflow progress.

Parameters

Returns void
Example

// Track that the user reached the "Checkout" step
api.trackAnalyticsStep("Checkout");

States (deprecated)

As of Cognigy.AI 2026.7.0, States are deprecated. The removal of States is planned for Cognigy.AI 2026.12.0. Before the removal, delete your States and retrain your NLU model so it no longer uses state-based Intent masking. For alternative approaches to control Intent recognition, use Intent Conditions.

Use these functions to get, set, and reset the conversation State of a Flow.

api.getState

Returns the current State of the conversation.

Parameters None
Returns string
Example

// Get the current State of the Flow
const currentState = api.getState();

// Send the State to the user
api.say(`The current state is: ${currentState}`);

api.resetState

Resets the State of the Flow to the initial State.

Parameters None
Returns Promise<string>
Example

api.resetState();

api.setState

Updates the conversation State to a specified State.

Parameters

Returns void
Example

// Set the conversation state to "awaiting_input"
ap.setState("awaiting_input");

// Verify by getting the current state
const currentState = api.getState();
api.say(`The current state is: ${currentState}`);

xApps

Use these functions to manage conversations with xApps.

api.setAppState

Updates the state of the xApp Session for the current conversation. Only works if an xApp Session was started beforehand.

Parameters

Returns void
Example

// Load an xApp template hosted at a URL
api.setAppState("https://my-xapp-template-url", {
    my: "xapp-template-data",
});

// Load a generic HTML xApp page
const html = `
<html>
<body>
Hello, World!
<button type="button" onclick="SDK.submit({});">continue</button>
<script src="/sdk/app-page-sdk.js"></script>
</body>
</html>
`;
api.setAppState("generic-html", { html });

// Close the active xApp page
api.setAppState(null, {});

Other

Use these functions to manage conversation behavior, such as adding Keyphrases, handling handovers, and localization settings.

api.addLexiconKeyphrase

Adds a new Keyphrase to a Lexicon.

Parameters

Returns Promise<string>
Example

// Add a new keyphrase to the existing Lexicon
api.addLexiconKeyphrase(
    "6942550bf16d8343c6f1adec",
    "password reset",
    ["account", "security"], // tags
    ["reset password", "forgot password"], // synonyms
    {
        priority: "high",
        source: "dynamic",
    }
);

api.evaluateRule

Evaluates a condition based on a rule configuration that follows the left, operand, right pattern. This function works similarly to the If Node. The left value is compared with the right value using the specified operator, for example, !=, >, includes. If the condition evaluates to true, the associated logic or transition is executed.

Parameters

Returns Promise<boolean>
Example

api.evaluateRule({
    left: "hello world",
    operand: "contains",
    right: "hello"
});

api.handover

Initiates a handover to a human agent or another system.

Parameters

Returns Promise<void>
Example

api.handover({
    text: "Connecting you to a human agent...",
    cancelIntent: "CancelHandover",
    unavailable: "No agents are available at the moment.",
    unsupportedChannel: "This channel doesn't support handover.",
    quickReply: "Talk to an agent",
    chatwootInboxId: "chatwoot_123",
    liveAgentInboxId: "liveagent_456"
});

api.setLocaleReferenceId

Sets the Reference ID to specify which Locale is used for localization. Parameters

Returns void
Example

api.setLocaleReferenceId("b4dc8ff5-bd05-467a-a281-2514122c4aa2");

api.setRating

Sets a rating for the conversation to prefill a rating prompt with a specific value or update it based on other actions or user inputs. Using this function, you can collect feedback at specific steps.

Parameters

Returns void
Example

api.setRating({
    rating: 1,
    comment: "The conversation was helpful."
});

api.setTimezoneOffset

Sets the time zone offset from UTC for the session, allowing time-related data to be interpreted correctly. You can view the applied time zone in the Input object under input.currentTime.timezoneOffset.

Parameters

Returns void
Example

// Set the session timezone offset to UTC+4
api.setTimezoneOffset(4);

More Information

• Node Execution API: Function Reference

Last modified on June 24, 2026