Intelligence

📖 How to build a chatbot with Flourish Intelligence.

Overview

The Intelligence Chatbot Lightning Web Component (LWC) implements a conversational chatbot for Salesforce.
The chatbot is driven by JSON-defined conversation "paths", where each "path step" specifies:

The messages to show (static or generated by LLMs),
Navigation rules,
Optional branching conditions, actions, or data collection steps.

Conversation Paths JSON

A chatbot’s flow is defined by an array of path steps. Example:

[
  {
    "id": "_START",
    "messages": [
      { "type": "static", "content": "Hello!" },
      { "type": "generative", "content": "Share a fun animal fact" }
    ],
    "navTarget": "continueAndLoop"
  },
  {
    "id": "continueAndLoop",
    "messages": [
      { "type": "generative", "content": "Continue the conversation and drive towards the end" }
    ],
    "navTarget": "continueAndLoop"
  }
]

Path Step Structure

Each path may contain:

Field	Type	Description
`id`	`string`	Unique identifier for the path. `_START` is the entry point.
`messages`	`array`	Messages to display. Each item has a `type` (`static` or `generative`) and `content`.
`navTarget`	`string` \| `object`	The next path’s ID, or a dynamic navigation object with `options`.
`type`	`string`	Special modes (`collectData`, `branch`, `customAction`).
`datapoints`	`array`	For `collectData` paths: specifies what to ask and store.
`branches`	`array`	For `branch` paths: conditions for choosing paths.
`buttons`	`array`	Optional buttons with labels and `navTarget`s.
`intentionalActions`	`array`	Optional intent-based routing using LLM classification.
`computeData` / `queryData`	`array`	Used to generate or query Salesforce data at runtime.

Supported Message Types

Static Messages

Directly display fixed text.

{ "type": "static", "content": "Hello, welcome to our chatbot!" }

Generative Messages

Pass content as a prompt to generateResponse (Salesforce Apex → LLM).

{ "type": "generative", "content": "Suggest a next step for the user." }

Special Path Types

`collectData`

Prompts the user for values to populate context keys.

{
  "id": "collectEmail",
  "type": "collectData",
  "datapoints": [
    { "datapoint": "email", "promptType": "static", "content": "What’s your email?" }
  ],
  "navTarget": "nextStep"
}

`branch`

Conditional navigation based on expressions in context.

{
  "id": "branchExample",
  "type": "branch",
  "branches": [
    {
      "conditions": ["{{{age}}} GTE 18"],
      "evaluationType": "and",
      "navTarget": "adultPath"
    }
  ],
  "branchDefaultNavTarget": "childPath"
}

`customAction`

Calls a function in chatWrapper (provided by host app).

{
  "id": "doSomething",
  "type": "customAction",
  "actionName": "launchSurvey",
  "properties": [
    { "id": "surveyId", "type": "static", "content": "12345" }
  ]
}

Context Handling

Stored in chatbot.context (@api context).
Updated via setContext, setContextItem, or during path execution.
Passed into message templates via {{{key}}} replacements.

Example:

{ "type": "static", "content": "Hello, {{{firstName}}}!" }

Global Paths & Safeguards

The system also supports global embeddings and flags:

Restart chat (GLOBAL_restartChat),
Request a call (GLOBAL_requestCall),
Safety overrides (GLOBAL_RED_selfharm, GLOBAL_RED_harmothers).

These are detected by embedding similarity against GLOBAL_EMBEDDINGS.

Example Usage in LWC Page

<c-chatbot chatbot-id="a01xx0000001234"
            record-id={recordId}
            runtime-context='{"someKey": "someValue"}'
            hide-footer={false}
            onflintelligence={handleChatEvents}>
</c-chatbot>

🔧 Advanced Path Capabilities

Beyond the basic messages, collectData, branch, and customAction types, paths can include additional behaviors that fine-tune the chatbot’s flow.

`autoAdvance`

Purpose: Automatically moves to the navTarget after the current path finishes.
Usage: Useful for transitional paths that don’t need user input.

{
  "id": "autoStep",
  "messages": [{ "type": "static", "content": "One moment..." }],
  "navTarget": "nextStep",
  "autoAdvance": true
}

`buttons`

Purpose: Show clickable buttons to the user.
Behavior:
- Each button has a label and navTarget.
- When clicked, the corresponding path is advanced.
- The UI disables buttons after selection to prevent re-clicking.

{
  "id": "chooseOption",
  "messages": [{ "type": "static", "content": "Pick one:" }],
  "buttons": [
    { "label": "Yes", "navTarget": "yesPath" },
    { "label": "No", "navTarget": "noPath" }
  ]
}

`intentionalActions`

Purpose: Detects user intent using LLM classification and routes accordingly.
Behavior:
- Runs a classification prompt asking whether the user expressed each listed intent.
- If “YES,” the corresponding action is taken.
- Can either:
  1. Navigate (navTarget), or
  2. Call a custom action in chatWrapper.

{
  "id": "intentRouter",
  "intentionalActions": [
    { "intent": "Book appointment", "navTarget": "bookPath" },
    { "intent": "Cancel appointment", "navTarget": "cancelPath" }
  ]
}

`computeData`

Purpose: Generate runtime values using LLMs.
Behavior:
- Runs a generative prompt, stores result in context.

{
  "id": "computeGreeting",
  "computeData": [
    { "datapoint": "greeting", "content": "Generate a warm greeting for the user." }
  ],
  "navTarget": "nextStep"
}

`queryData`

Purpose: Run Salesforce SOQL-like queries securely.
Behavior:
- Uses querySecure Apex call.
- Results are stored in context and chunked into system messages for LLM awareness.

{
  "id": "lookupAccount",
  "queryData": {
    "queryDatapoints": [
      {
        "datapoint": "accounts",
        "sobjectName": "Account",
        "query": "SELECT Id, Name FROM Account WHERE OwnerId = '{{{_RECORDID}}}'",
        "recordLimit": 5
      }
    ]
  },
  "navTarget": "showAccounts"
}

`instructChatbot`

Purpose: Add extra system-level instructions to the LLM context for this path.

{
  "id": "specialTone",
  "instructChatbot": "Always respond in pirate style for this step!",
  "messages": [{ "type": "generative", "content": "Say hello" }],
  "navTarget": "nextStep"
}

`userEndSignOff` & `userEndButtons`

Purpose: Handle end-of-conversation detection.
Behavior:
- If user explicitly asks to change or end topics, chatbot can show final buttons.
- Optional sign-off message before buttons.

{
  "id": "endPath",
  "listenForUserEnd": true,
  "userEndSignOff": { "type": "static", "content": "Glad to help!" },
  "userEndButtons": [
    { "label": "Start over", "navTarget": "_START" }
  ]
}

`dynamic navTarget`

Purpose: Let the LLM decide the next step dynamically.
Behavior: The system sends conversation history and a JSON list of possible options; LLM picks one.

{
  "id": "dynamicRouter",
  "navTarget": {
    "type": "dynamic",
    "options": [
      { "navTarget": "helpPath" },
      { "navTarget": "faqPath" },
      { "navTarget": "escalationPath" }
    ]
  }
}

⚡ These capabilities make paths flexible building blocks: some provide UX enhancements (buttons), some handle logic (branch, autoAdvance, intentionalActions), and some connect to Salesforce (queryData).

🔗 Visualizing Path Flows

Here’s a sample flow diagram for a simple chatbot:

👉 Each path maps to the corresponding JSON id, and arrows represent navTarget transitions.

Overview​

Conversation Paths JSON​

Path Step Structure​

Supported Message Types​

Static Messages​

Generative Messages​

Special Path Types​

collectData​

branch​

customAction​

Context Handling​

Global Paths & Safeguards​

Example Usage in LWC Page​