Triggers

Chat Hook

Open in ChatGPT Open in Claude

Triggers when the host page calls manager.sendHook() via the FlowHunt JS API. Use {ChatHook.hook_name} to branch on the event name in your flow logic.

Category: Triggers · Plans: Trial, Starter, Pro, Premium, Enterprise · Type: ChatHook · Trigger

Inputs#

FieldTypeRequiredDefaultWhat it does
Validate Payload SchemaYes/NoNoOffWhen enabled, the incoming payload must match the JSON Schema defined below.
JSON SchemaTextNo—JSON Schema for payload validation. Only used when ‘Validate Payload Schema’ is enabled.

%!s()#

Chat Hook JS API#

The Chat Hook trigger fires inside a running chat session whenever your host page calls manager.sendHook() from the FlowHunt JS API. It is the bridge from host-page events into an already-running conversation.

One trigger per flow#

Add a single Chat Hook node to your flow. It fires for every sendHook() call, regardless of the name the caller passed. You branch on the name inside your flow logic (system prompt, conditional step, tool routing, etc.) using the hook_name output — see the example below.

Quick start#

1. Wire it in the JS API#

html
<script
  src="https://cdn.flowhunt.io/chatbot/v1/loader.js"
  id="fh-chatbot-script"
></script>
<script>
  const manager = window.FHChatbot.initChatbot({
    chatbotId: "YOUR_CHATBOT_ID",
    workspaceId: "YOUR_WORKSPACE_ID",
  });

  // Scenario 1 — keep context variables fresh (no trigger fired)
  // `current_page_url` is the canonical session variable the backend
  // populates at session creation; updating it here keeps the same key
  // fresh as the user navigates.
  window.addEventListener("hashchange", () => {
    manager.updateFlowVariables({
      current_page_url: window.location.href,
      screen_name: document.title,
    });
  });

  // Scenario 2 — fire the Chat Hook trigger with a named event + payload
  window.addEventListener("hashchange", () => {
    manager.sendHook("screen_changed", {
      url: window.location.href,
      screen_name: document.title,
    });
  });
</script>

2. Branch on hook_name inside your flow#

The trigger’s outputs are hook_name, payload, and flow_variables. In your Generator / Prompt node, reference them directly:

text
If {ChatHook.hook_name} is "screen_changed", briefly summarise the page at
{ChatHook.payload.url}. If it is "user_action", acknowledge the action and
update memory. Otherwise, continue the conversation normally.

For more complex routing, wire a conditional step on {ChatHook.hook_name} and split into multiple downstream branches.

What sendHook() sends#

FieldValue
hook_nameFirst argument. A label for your flow to branch on — no backend validation of the value itself.
payloadSecond argument. Any JSON object. Validated against this node’s schema if enabled below.
flow_variablesOptional third argument: variables merged into session context before the trigger fires.

Outputs available downstream#

OutputDescription
{hook_name}The name the caller passed to sendHook()
{payload}JSON-stringified payload from the host page
{flow_variables}Merged session variables at invocation time

Payload schema validation#

Turn Validate Payload Schema on to validate payloads during ChatHook step execution. Define a standard JSON Schema in the JSON Schema field; schema validation failures surface as flow error events on the session’s event stream. External $ref references are not permitted.

updateFlowVariables() — variables only, no trigger#

js
// Silently updates session context without firing the Chat Hook node.
// Use `current_page_url` to stay in sync with the variable the backend
// populates at session creation (`init_variables`), so the flow's
// system prompt can always read {flow_variables.current_page_url}.
manager.updateFlowVariables({ current_page_url: window.location.href });

Use this when you only want to keep variables in sync without running any flow logic. The update persists on the session and is visible to the next user message (via {flow_variables.*}) or the next Chat Hook fire.

%!s()#

JSON Schema for Webhook Body Validation#

For full documentation, see the JSON Schema Reference.

Basic Object Schema#

Validate that the body is an object with specific properties:

json
{
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "age": {"type": "integer"}
  },
  "required": ["name"]
}

String with Constraints#

json
{
  "type": "object",
  "properties": {
    "email": {"type": "string", "format": "email"},
    "code": {"type": "string", "minLength": 3, "maxLength": 10}
  }
}

Enum Values#

Restrict a field to specific values:

json
{
  "type": "object",
  "properties": {
    "status": {"type": "string", "enum": ["active", "inactive", "pending"]}
  }
}

Nested Objects#

json
{
  "type": "object",
  "properties": {
    "user": {
      "type": "object",
      "properties": {
        "name": {"type": "string"},
        "address": {
          "type": "object",
          "properties": {
            "city": {"type": "string"},
            "zip": {"type": "string"}
          }
        }
      }
    }
  }
}

Arrays#

json
{
  "type": "object",
  "properties": {
    "tags": {
      "type": "array",
      "items": {"type": "string"},
      "minItems": 1
    }
  }
}

Supported Types#

  • string – text values (supports format: email, uri, date-time, etc.)
  • integer – whole numbers
  • number – any numeric value
  • boolean – true or false
  • array – list of items
  • object – nested key-value pairs
  • null – null value

Empty Schema#

Leave empty to accept any request body without validation.

Outputs#

OutputType
Hook NameAny
PayloadAny
Flow VariablesAny