Neuron: Generic

Overview

The Generic Neuron enables developers to create custom blocks with dynamic outputs tailored to specific API response patterns. While the standard HTTP Neuron provides a simple binary success/failure model, Generic Neurons allow for more sophisticated integration scenarios where APIs return multiple distinct response states that require different handling logic and conversation routing.

Generic Neurons are pre-registered blocks that extend the BotBuilder's functionality beyond the standard blocks available in the left sidebar menu. Under the hood, these blocks are also HTTP calls, but they provide the capability to implement branch-based responses with multiple outputs. This makes Generic Neurons ideal for scenarios where an API integration needs to handle various business logic states, such as "user not found," "insufficient permissions," "payment required," "rate limit exceeded," or any other custom response patterns that require different conversation flows or user messages.

Creating Generic Neurons

To create a Generic Neuron, you must register it by making an HTTP request to Talqui's registration endpoint. This registration process creates a custom block that will appear in the BotBuilder's editor, making it available for use in your conversation flows.

Registration Endpoint

To register a Generic Neuron, make a POST request to:

https://api-bot.talqui.chat/tenants/<tenantID>/neurons/extensions

Replace <tenantID> with your tenant ID.

Registration Request

The registration request must include the following information:

• neuronExtensionLabel: A human-readable label for your neuron (this will appear in the editor)
• neuronExtensionDescription: A description explaining what the neuron does
• neuronExtensionEndpoint: The URL where requests will be sent when this neuron executes
• neuronExtensionIcon: An icon identifier for visual representation in the editor
• neuronExtensionSchema: A JSON Schema defining the parameters/inputs that this neuron accepts
• neuronExtensionOutputs: An array of output definitions, each with:
  • id: A unique UUID for the output
  • key: A unique key identifier (e.g., "IDENTIFICATION_SUCCESS")
  • label: A human-readable label for the output

Note: An error output (FAILED_TO_EXECUTE) is automatically created for all Generic Neurons, even if you don't specify it during registration. This serves as a fallback when the neuron cannot process the request or when no output is selected in the response.

Registration Example

curl --location 'https://api-bot.talqui.chat/tenants/<tenantID>/neurons/extensions' \
--header 'Authorization: Bearer <YOUR_AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "neuronExtensionLabel": "Validate User",
    "neuronExtensionDescription": "Validate if user is able to access a resource",
    "neuronExtensionEndpoint": "https://talquitesting-free.webhookcatcher.com/webhook",
    "neuronExtensionIcon": "identification",
    "neuronExtensionSchema": {
        "$schema": "http://json-schema.org/draft-07/schema#",
        "type": "object",
        "properties": {
            "contactGroup": {
                "type": "string",
                "default": "admins"
            },
            "contactDocument": {
                "type": "string"
            }
        },
        "required": [
            "contactGroup",
            "contactDocument"
        ]
    },
    "neuronExtensionOutputs": [
        {
            "id": "0abe4b5e-7600-4ba0-a6fa-89d95ce34e7e", // random and unique UUID
            "key": "IDENTIFICATION_SUCCESS",
            "label": "Identified"
        },
        {
            "id": "aa9ecfed-0af5-452b-a860-ae33bb81d3f2", // random and unique UUID
            "key": "IDENTIFICATION_ERROR",
            "label": "Not identified"
        }
    ]
}'

This request will produce the following experience at the flow builder:

Defining Custom Parameters with JSON Schema

When registering a Generic Neuron, you can define custom parameters that will be available as inputs in the BotBuilder editor. These parameters are defined using JSON Schema, which allows you to specify:

• Parameter types (string, number, boolean, etc.)
• Required vs optional parameters
• Default values
• Validation rules

To create a JSON Schema for your neuron's parameters, you can use an online JSON Schema generator. These tools help you build the schema structure visually and ensure it follows the correct format.

Tip: When testing your Generic Neuron during development, you can use online webhook services to receive and inspect the requests being sent to your endpoint. This allows you to verify that parameters are being sent correctly and test your integration logic before deploying to production.

Once registered, the Generic Neuron appears in the BotBuilder's block library and can be used in flow designs just like any other block. However, unlike standard blocks, Generic Neurons can have as many outputs as necessary, allowing developers to create complex routing logic that evaluates API responses granularly and routes conversations to different paths based on specific response characteristics.

Request Format

When a Generic Neuron executes in a conversation flow, Talqui sends a POST request to the endpoint you specified during registration. Understanding the request format is essential for implementing your integration correctly.

Request Method and Headers

All Generic Neuron requests are sent using the POST method. The request includes the following headers:

• Content-Type: application/json
• user-agent: Talqui (Neuron PluginGeneric) v1.0, Neuron <neuronExtensionLabel>

The user-agent header includes the label you specified during registration, allowing you to identify which Generic Neuron is making the request. This is particularly useful if you have multiple Generic Neurons pointing to the same endpoint.

Request Payload

The request body contains three main sections:

{
  "message": "Here is a request from Talqui Chat to custom made extension [<neuronExtensionLabel>]",
  "params": {
    // Parameters configured in the BotBuilder editor
    // These correspond to the inputs defined in your neuronExtensionSchema
  },
  "metadata": {
    "sessionID": "<sessionID>",
    "tenantID": "<tenantID>",
    "contactID": "<contactID>"
  }
}

• message: A descriptive message indicating the request origin
• params: An object containing all the parameters configured in the BotBuilder editor when the neuron was added to the flow. These parameters can include:
  • Static values entered during flow design
  • Variables from conversation context (using {{ variableName }} syntax)
  • Session-scoped variables (using {{ meta.variableName }} syntax)
  • Contact-scoped variables (using {{ meta.variableName }} syntax)
• metadata: Contains identifiers that allow you to access additional information:
  • sessionID: Unique identifier for the current conversation session
  • tenantID: Your tenant identifier
  • contactID: Unique identifier for the contact/user in the conversation

Accessing Additional Data

If your Generic Neuron needs to retrieve additional information about the session, tenant, or contact, you can use Talqui's REST API with the identifiers provided in the metadata object. The REST API allows you to:

• Read session variables and state
• Access contact information and contact-scoped variables
• Retrieve tenant-specific configuration
• Perform other operations based on your integration needs

For detailed information about available REST API endpoints and how to access session, contact, and tenant data, refer to the REST API documentation.

Request Timeout

Generic Neuron requests have a timeout of 20 seconds (20,000 milliseconds). If your endpoint does not respond within this timeframe, the request will be considered failed and the conversation flow will route through the error output (FAILED_TO_EXECUTE).

Response Format

Your Generic Neuron endpoint must return a valid JSON object. The response format determines both which output path the conversation will follow and which variables will be stored in the conversation context.

Output Selection

The most important aspect of the Generic Neuron response is indicating which output path the conversation should follow. This is done by including an outputID field in your response:

{
  "outputID": "<uuid-of-the-output>"
}

The outputID must match one of the UUIDs you specified in the neuronExtensionOutputs array during registration. If your response includes a valid outputID, the conversation will route to that specific output path.

Important: If your response does not include an outputID, or if the outputID doesn't match any registered output, the conversation will automatically route to the error output (FAILED_TO_EXECUTE), which is always available as a fallback.

Returning Variables: sessionMeta and contactMeta

Similar to the HTTP Neuron, Generic Neurons can return variables that will be stored in the conversation context. The response JSON can contain two optional properties:

• sessionMeta: Variables stored in the session context (specific to the current conversation session)
• contactMeta: Variables stored in the contact context (persists across all conversations with a specific contact)

Each of these properties can contain up to 20 variables. Variables returned in these properties will be made available to subsequent blocks in the conversation flow and can be accessed using the {{ meta.variableName }} syntax.

Variable Flattening

If you return nested objects within sessionMeta or contactMeta, they will be automatically flattened (planified) and saved as flat objects using dot notation as separators. For example:

Your API Response:

{
  "outputID": "0abe4b5e-7600-4ba0-a6fa-89d95ce34e7e",
  "sessionMeta": {
    "user": {
      "name": "John",
      "account": {
        "id": "12345"
      }
    }
  }
}

Stored Variables:

• meta.user.name = "John"
• meta.user.account.id = "12345"

This flattening process allows you to return complex nested structures while making them easily accessible in subsequent blocks through simple dot notation.

Complete Response Example

{
  "outputID": "0abe4b5e-7600-4ba0-a6fa-89d95ce34e7e",
  "sessionMeta": {
    "userId": "12345",
    "status": "verified"
  },
  "contactMeta": {
    "lastVerification": "2026-01-31T10:00:00Z"
  }
}

Dynamic Outputs

The key advantage of Generic Neurons over the standard HTTP Neuron is the ability to define multiple dynamic outputs. Unlike the HTTP Neuron's binary success/failure model, Generic Neurons allow you to create as many outputs as needed, each representing a different business logic scenario or response state.

Output selection is controlled entirely by your API response through the outputID field. This gives you complete flexibility to implement complex routing logic based on:

• Business logic states (e.g., "user verified", "user not found", "insufficient permissions")
• Data validation results (e.g., "valid", "invalid format", "missing required field")
• Process outcomes (e.g., "payment successful", "insufficient funds", "card declined")
• Any custom conditions relevant to your integration

This allows developers to create sophisticated integration patterns where a single API call can result in multiple possible conversation paths, each handling a different scenario appropriately. For example, a user validation Generic Neuron might have outputs for "verified", "not found", "requires additional information", and "account locked", each routing to different conversation flows that provide appropriate user feedback and next steps.

Use Cases

Generic Neurons are particularly useful when integrating with APIs that have complex response patterns or when building chatbots that need to handle multiple business logic scenarios. Common use cases include:

• Payment Processing: Handling various payment states (success, declined, insufficient funds, etc.)
• User Authentication: Differentiating between successful login, invalid credentials, account locked, etc.
• Data Retrieval: Handling cases where data exists, doesn't exist, requires permissions, etc.
• Multi-step Processes: APIs that return different states indicating progress through a workflow

For simpler integrations where a binary success/failure model is sufficient, the standard HTTP Neuron remains the recommended approach due to its simplicity and ease of configuration.