Intent Recognition icon

Intent Recognition

Join our community

Overview

This node performs intent recognition on user messages within conversations. It is designed to analyze a given user message, identify the most appropriate intent from a predefined list, and extract relevant parameters associated with that intent. The node interacts with an external intent recognition API service by sending conversation data and receiving processed intent results.

Common scenarios where this node is beneficial include:

  • Chatbots or virtual assistants that need to understand user intents to provide relevant responses.
  • Customer support automation where incoming messages are classified into categories like complaints, inquiries, or feedback.
  • Workflow automation where different intents trigger different processing paths.

Practical example: A chatbot receives a message "I want to book a flight for tomorrow." This node can recognize the "booking" intent and extract parameters such as "date" (tomorrow), enabling downstream nodes to handle booking logic accordingly.

Properties

Name Meaning
User Message The text message from the user to analyze for intent recognition. Typically sourced from incoming JSON data.
Chat ID Unique identifier for the conversation session. Used to track context across multiple messages. Defaults to "default-chat" if not provided.
System Prompt A guiding prompt for the intent recognition system to influence how it analyzes the user message. Helps customize the assistant's behavior.
Intents A list of intents to recognize. Each intent has:
- Intent Key: Unique identifier used as output label.
- Intent Name: Human-readable name.
- Description: Explanation of what the intent represents.
- Parameters: List of parameters to extract for the intent, each with key, name, description, and whether it is required.
Options → Generate Clarification Questions Whether the node should generate clarification questions when no clear intent is recognized. Defaults to true.

Output

The node outputs one separate output for each configured intent plus one additional fallback output for unrecognized intents. Each output contains an array of items corresponding to input items classified under that intent.

Each output item’s json field includes:

  • recognizedIntent: The key of the recognized intent or null if none matched.
  • extractedParams: An object or array containing extracted parameter values for the recognized intent, or null if none.
  • clarificationMessage: A message suggesting clarifications if the intent was ambiguous or incomplete, or null.
  • isFinal: Boolean indicating if the intent recognition is final or if further clarification is needed.
  • chatId: The conversation identifier.
  • userMessage: The original user message analyzed.
  • settingsId: Identifier of the settings configuration used in the external API.
  • metadata: Additional info including:
    • processingTime: Timestamp of processing.
    • Flags indicating presence of intent, extracted parameters, clarification message, or errors.
  • error: Present only if an error occurred during processing.
  • pairedItem: Reference to the original input item index.

If the input item contained binary data, it is preserved in the output under the binary field.

Dependencies

  • Requires connection to an external intent recognition API service.
  • Needs credentials providing:
    • Base URL of the API.
    • System name identifier.
    • API key for authentication.
  • The node uses HTTP Basic Authentication with these credentials.
  • No other external dependencies are required.

Troubleshooting

Common Issues

  • Missing Credentials: If any of the required credential fields (URL, system name, API key) are missing, the node will throw an error before execution.
  • API Request Failures: Network issues or incorrect API endpoint URLs can cause failures when creating settings, appending messages, or processing intents.
  • Unrecognized Intents: If the user message does not match any configured intent and clarification generation is disabled, the fallback output will receive the item without recognized intent.
  • Parameter Extraction Errors: If expected parameters are not found or malformed, the extracted parameters may be empty or incomplete.

Error Messages and Resolutions

  • Missing credentials: url=..., systemName=..., apiKey=...
    Ensure all required credential fields are correctly set in the node’s credential configuration.

  • Failed to create settings: <error message>. URL: <url>/api/settings
    Check API URL correctness and network connectivity. Verify credentials have permission to create settings.

  • Failed to append message: <error message>. URL: <url>/api/conversations/append
    Confirm the chat ID is valid and the API endpoint is reachable.

  • Failed to process intent: <error message>. URL: <url>/api/settings/process
    Indicates failure during intent processing; verify API health and request payload validity.

  • For any unexpected errors, enabling "Continue On Fail" allows the node to output error details per item instead of stopping execution.

Links and References

  • n8n Documentation – General information about n8n nodes and workflows.
  • External API documentation (not included in source) – Consult your intent recognition API provider for detailed API usage and credential setup instructions.

Discussion