Skip to content
Docs
flero.ai

Chat trigger

The Chat trigger is a conversational entry point: each message a user types fires a workflow run, with the message and conversation history available in $trigger. Use it to build chatbots, AI agents, and interactive workflows.

When to use it

  • Internal AI assistants (HR chatbot, knowledge-base Q&A).
  • Customer support bots fronted by Flero.
  • Multi-turn workflows where each turn is its own run but they share context.

For one-shot non-conversational AI tasks (summarise this article, classify this email), prefer a regular Webhook / Schedule / Manual trigger and a single AI Agent node.

Configuration

Field Notes
Chat surface Hosted page (default, Flero hosts a chat UI), embed (snippet for your site), Slack, Microsoft Teams
Title Chat header text
Welcome message Sent automatically when a user opens a new conversation
Memory enabled Persist conversation history across messages within a session
Memory window Last N turns to include in $trigger.context
Authentication Public or Authenticated (Flero login)
Allowed origins For embed surfaces, the origins permitted to load the chat

Trigger payload

{
  "message":         "What's our refund policy?",
  "conversationId":  "<uuid>",
  "userId":          "<uuid or null>",
  "context": [
    { "role": "user",      "content": "Previous message" },
    { "role": "assistant", "content": "Previous answer" }
  ],
  "metadata": {
    "surface":  "hosted",
    "locale":   "en-GB",
    "userAgent": "..."
  }
}

context includes the last N turns. Combine with an AI Agent node's messages field to maintain coherent multi-turn conversations.

Returning a response

The workflow must produce a response that the chat surface displays. Convention:

  • The Terminal node returns an object with at least { "response": "<text to show>" }.
  • Optionally { "actions": [...], "attachments": [...] } for richer chat UIs.

If you don't use a Terminal node, the chat surface shows the output of the last node in the chain.

Memory / context

Two layers of memory:

  1. Trigger-level context ($trigger.context), Flero compiles the last N turns into the trigger payload automatically. Use this for the simple case.
  2. AI Agent memory, the AI Agent node has its own enableMemory / memoryKey settings. Pass $trigger.conversationId as the memory key for per-conversation memory.

For most chatbots, AI Agent memory keyed by conversationId is the right pattern.

Surfaces

Hosted page

A Flero-hosted URL with a clean chat UI. Best for internal tools, prototypes, and lightweight customer chats.

Embed

A JS snippet you paste into any web page. Renders as a chat widget in the corner.

Slack

Conversations happen in Slack. Configure with a Slack credential and target channels / DMs.

Microsoft Teams

Same idea, in Teams. Configure with a Teams credential.

For Slack and Teams, the trigger only fires when the bot is mentioned (e.g. @flero-bot), unless listen to all messages is enabled.

Tips & gotchas

  • Latency matters more here than in other workflows, users notice delay. Optimise heavy steps (RAG, multi-call AI chains) and consider streaming responses from the AI Agent.
  • conversationId is generated by Flero if the surface doesn't provide one. Reuse the same id for the same session to keep memory continuous.
  • Public chats can be abused. Use authentication or rate limits unless the workflow is harmless.
  • For Slack and Teams, the response must come back within ~3 seconds or the platform considers it a timeout. Use an immediate acknowledgement + later update pattern for long-running workflows.

Found something out of date? This page lives in the Flero docs content set.