Public documentation

Create, setup and edit bots

This guide explains how to create a bot, configure languages and text direction, build a flow with nodes, validate user inputs (email/phone/etc.), and publish a public chat link.

Key features

• Visual flow builder + templates
• Multi-language + RTL/LTR
• Input validation (Email/Phone/Regex) + Validate node
• Knowledge Base (RAG) + optional AI answer mode
• Webhooks node (integrations) + email actions
• AI Response node + Generate flow using AI (plan-based)
• Public share URL + themes (plan-based)
• REST API (plan-based) + AI usage analytics

Where to find things

• Dashboard → Bots / API key
• Bot → Settings (languages, themes, integrations)
• Bot → Builder (nodes + validations)
• Billing (plan + AI usage)

1) Create a bot

Open Dashboard.
Click Create Bot.
Give it a name (required) and click Save.

Tip: Bot name is trimmed and cannot be empty/whitespace.

2) Setup & settings

Open Bot → Settings to configure:

Default language (example: en, he, ar)
Supported languages (CSV, used by public chat selector)
Text direction (auto, ltr, rtl)
Public theme (dark/light/blue/green/yellow/orange/silver)
Multi-session (each visitor gets a separate session)
Send bot Q/A results on session end:
- Email (optional): attach uploaded files and/or attach a JSON file with the full session results (including base64 file content when available)
- Client API (webhook): POST JSON to your endpoint
- SFTP: upload a .json file to your SFTP server

Note: supported languages are normalized, deduped, and the default language is ensured.

3) Builder (nodes)

Use the builder to add nodes and connect them into a conversation flow.

Common nodes

• Bot Message
• Ask Question
• Buttons
• Condition
• Validate Input
• Send Email / Webhook

Best practices

• Keep a clear happy-path
• Validate before actions (email/webhook)
• Add fallback message for invalid inputs

4) Input validations (email / phone / etc.)

You can validate user answers using:

Ask Question input type

Choose type: Email, Phone, Contact, Number, Integer, Date, Url, or Regex.

Regex checks use a short timeout to prevent slow patterns.

Validate Input node

Validate the previous answer and route: valid → continue, invalid → show error and ask again.

5) Knowledge Base (RAG)

Upload documents to your bot Knowledge Base and use a KB node (or KB-enabled node) to answer using your content.

Large text is chunked safely for stable retrieval.

6) Publish & share

Use the bot share token to open a public chat page. You can enable multi-session if your plan supports it.

Public chat URL format: /PublicBot/Chat/{token}

7) API (bot management + web sessions + WhatsApp)

If your plan includes API access, you can manage bots via REST. You’ll find your API key in Dashboard → API.

Flow JSON structure

The API accepts the flow as a JSON object (flow) or as a string (flowJson). When you send flow, the server stores it as flowJson.

{
  "version": "1.0",
  "timestamp": "2026-02-25T10:21:41.683Z",
  "nodes": [
    { "id": 1, "type": "start", "x": 50, "y": 50, "data": { }, "outputs": [] }
  ],
  "edges": [
    { "from": 1, "to": 2, "handle": null }
  ]
}

Tip: text fields like message/text/bot_answer can be either a string ("Hello") or a localized dictionary ({ "en": "Hello", "he": "שלום" }). The runtime picks the current language and falls back to the first non-empty value.

Endpoints

GET    /api/bots
GET    /api/bots/{id}
POST   /api/bots
PUT    /api/bots/{id}
DELETE /api/bots/{id}

GET    /api/bots/{id}/flow
PUT    /api/bots/{id}/flow
GET    /api/bots/{id}/settings
PUT    /api/bots/{id}/settings
GET    /api/bots/{id}/shares
POST   /api/bots/{id}/shares
DELETE /api/bots/{id}/shares/{shareId}

POST   /api/bots/{id}/web/sessions
GET    /api/bots/{id}/web/sessions/{sessionId}
POST   /api/bots/{id}/web/sessions/{sessionId}/messages
POST   /api/bots/{id}/web/sessions/{sessionId}/upload
POST   /api/bots/{id}/web/sessions/{sessionId}/signature

POST   /api/bots/{id}/whatsapp/test
GET    /api/whatsapp/webhook
GET    /api/whatsapp/phones
POST   /api/whatsapp/phones/sync
PUT    /api/whatsapp/phones/{id}/inbound-bot
GET    /api/whatsapp/templates
POST   /api/whatsapp/templates
POST   /api/whatsapp/templates/refresh-all

GET    /api/files
GET    /api/files/{id}
POST   /api/files
DELETE /api/files/{id}

Header: X-Api-Key: YOUR_KEY

Create bot with flow (recommended)

Send flow as an object (no escaping). The server stores it as flowJson.

POST /api/bots
X-Api-Key: YOUR_KEY
Content-Type: application/json

{
  "name": "Loan Assistant",
  "description": "Bot + flow created via API",
  "flow": {
    "version": "1.0",
    "timestamp": "2026-02-25T10:21:41.683Z",
    "nodes": [
      { "id": 1, "type": "start", "x": 50, "y": 50, "data": { "bot_answer": "Hello! What is your name?" }, "outputs": [] },
      { "id": 2, "type": "question_node", "x": 260, "y": 50, "data": { "text": { "en": "What is your name?" }, "variable": "name", "type": "Text", "bot_answer": { "en": "Nice to meet you {{name}}" } }, "outputs": [] }
    ],
    "edges": [ { "from": 1, "to": 2, "handle": null } ]
  }
}

Update bot flow only

PUT /api/bots/123/flow
X-Api-Key: YOUR_KEY
Content-Type: application/json

{
  "flow": {
    "version": "1.0",
    "timestamp": "2026-02-25T10:21:41.683Z",
    "nodes": [ { "id": 1, "type": "start", "x": 50, "y": 50, "data": { } } ],
    "edges": []
  }
}

The API returns 403 if your plan blocks nodes used in the flow.

cURL example

curl -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"My Bot","flow":{"version":"1.0","nodes":[{"id":1,"type":"start","x":50,"y":50,"data":{}}],"edges":[]}}' \
  https://YOUR_HOST/api/bots

8) Node types reference

These are the supported node types for Flow JSON (UI builder and API). Each node is stored as: { id, type, x, y, data, outputs }. You connect nodes using edges.

Edge handles

• Default edge: handle = null
• Condition: handle = "true" or "false"
• Buttons / Quiz: handle = option text (exact match)
• Validate Input: handle = "valid" or "invalid"

start

Entry point. Usually 1 start node.

{
  "type": "start",
  "data": {
    "trigger_type": "On Open",
    "keyword": "",
    "bot_answer": { "en": "Hello!" }
  }
}

bot_message

Sends a message and continues.

{
  "type": "bot_message",
  "data": {
    "message": { "en": "Welcome" },
    "footer": "",
    "preview_url": "True",
    "bot_answer": ""
  }
}

bot_answer

Simple message node (legacy-compatible).

{
  "type": "bot_answer",
  "data": {
    "bot_answer": { "en": "Thanks!" }
  }
}

question_node

Asks user input and saves it into a variable.

{
  "type": "question_node",
  "data": {
    "text": { "en": "What is your name?" },
    "variable": "name",
    "type": "Text",
    "pattern": "",
    "bot_answer": { "en": "Nice to meet you {{name}}" }
  }
}

Input types: Text, Email, Phone, Contact, Number, Integer, Date, Url, Regex.

buttons_node

Shows clickable buttons and routes by selected label.

{
  "type": "buttons_node",
  "data": {
    "text": { "en": "Choose:" },
    "buttons": "Yes,No",
    "footer": "",
    "bot_answer": ""
  }
}

Create edges with handle "Yes" and "No".

quiz_node

Multiple-choice question. Routes by selected option.

{
  "type": "quiz_node",
  "data": {
    "question": { "en": "Pick one" },
    "options": "A,B,C",
    "correct_answer": "",
    "allow_multiple": "False",
    "bot_answer": ""
  }
}

condition

Evaluates a variable and routes to true/false edges.

{
  "type": "condition",
  "data": {
    "variable": "user_reply",
    "operator": "contains",
    "value": "hello",
    "bot_answer": ""
  }
}

Operators: equals, contains, greater_than.

validate_input

Validates a variable and routes valid/invalid.

{
  "type": "validate_input",
  "data": {
    "mode": "Email",
    "source_variable": "email",
    "pattern": "",
    "save_to_variable": "validation_ok",
    "bot_answer": ""
  }
}

Create edges with handle "valid" and "invalid".

knowledge_base

Retrieves KB text, optional AI answer mode (plan-based).

{
  "type": "knowledge_base",
  "data": {
    "query": "",
    "top_k": "3",
    "mode": "extract",
    "reply": "{{kb_answer}}",
    "save_to_variable": "kb_answer",
    "prompt": "Answer using ONLY context.",
    "model": "gpt-4o-mini",
    "bot_answer": ""
  }
}

ai_handler

Calls OpenAI and sends the response (plan-based).

{
  "type": "ai_handler",
  "data": {
    "prompt": { "en": "You are helpful. Reply to: {{user_reply}}" },
    "model": "gpt-4o-mini",
    "temperature": "0.7",
    "max_output_tokens": "1024",
    "save_to_variable": "ai_text",
    "bot_answer": ""
  }
}

send_email

Sends an email (plan-based). Use templates: {{name}}.

{
  "type": "send_email",
  "data": {
    "to": "[email protected]",
    "subject": "Hello",
    "body": "Name: {{name}}",
    "bot_answer": ""
  }
}

webhook

Calls an HTTP endpoint (plan-based). Can save response.

{
  "type": "webhook",
  "data": {
    "url": "https://api.example.com/hook",
    "method": "POST",
    "body": "{\"name\":\"{{name}}\"}",
    "request_headers": { "Authorization": "Bearer {{api_token}}" },
    "request_query": { "source": "botnet" },
    "body_map": { "name": "{{name}}", "email": "{{email}}" },
    "response_map": { "id": "webhook_id", "status": "webhook_status" },
    "save_to_variable": "webhook_response",
    "bot_answer": ""
  }
}

signature_pad

Collect a drawn signature (saved as PNG) and store the file path in a variable.

{
  "type": "signature_pad",
  "data": {
    "variable": "signature",
    "text": { "en": "Please sign below." },
    "required": "true",
    "width": "420",
    "height": "180",
    "pen_color": "#111827",
    "background_color": "#ffffff",
    "line_width": "2",
    "clear_label": "Clear",
    "submit_label": "Submit",
    "skip_label": "Skip",
    "bot_answer": { "en": "Thanks for signing!" }
  }
}

The public chat shows a signature canvas. The saved variables include signature_path and _last_signature_path.

file_upload

Asks user to upload a file (plan-based if enabled).

{
  "type": "file_upload",
  "data": {
    "variable": "user_document",
    "allowed_types": ".pdf,.jpg,.png",
    "max_size": "5",
    "bot_answer": ""
  }
}

send_files

Sends one or more files from your global storage as inline file cards.

{
  "type": "send_files",
  "data": {
    "file_ids": "1,2",
    "bot_answer": { "en": "Download your files:" }
  }
}

File ids come from Dashboard → Files. The public chat will show a card with Download button for each file.

human_handoff

Marks handoff to a human (placeholder behavior).

{
  "type": "human_handoff",
  "data": { }
}

end_flow

Ends the conversation.

{
  "type": "end_flow",
  "data": {
    "outcome": "resolved",
    "closing_note": "",
    "bot_answer": { "en": "Goodbye" }
  }
}

Variables you can use in templates: any variable saved by a question node (example: name), plus runtime helpers like user_reply / _last_user_message, and status variables like email_last_status, webhook_last_error.

Troubleshooting

If your public chat doesn’t show a language selector, check Supported languages has 2+ values.
If a regex seems slow, simplify it; the server enforces a small timeout for safety.
If you updated your plan and nodes are hidden, existing flows still run; you may not be able to add new plan-gated nodes.