Chatbot

Overview

The Chatbot API allows you to configure automated responses, keyword rules, conversation flows, and AI-powered responses.

Chatbot Settings

Get Settings

Retrieve current chatbot settings.

GET /api/chatbot/settings

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "account_id": "uuid",
    "chatbot_enabled": true,
    "ai_enabled": true,
    "ai_provider": "openai",
    "ai_model": "gpt-4o-mini",
    "ai_temperature": 0.7,
    "ai_max_tokens": 500,
    "system_prompt": "You are a helpful customer service assistant...",
    "greeting_message": "Hello! Welcome to our support. How can I help you?",
    "greeting_buttons": [
      {"title": "Track Order"},
      {"title": "Product Info"},
      {"title": "Speak to Agent"}
    ],
    "fallback_message": "Sorry, I didn't understand that. Please try again.",
    "fallback_buttons": [
      {"title": "Main Menu"},
      {"title": "Speak to Agent"}
    ],
    "transfer_keywords": ["agent", "human", "help"],
    "business_hours_enabled": false
  }
}

Button Configuration

Both greeting_buttons and fallback_buttons support WhatsApp interactive buttons:

| Button Count | Display Type | |--------------|--------------| | 1-3 buttons | Quick reply buttons | | 4-10 buttons | List menu |

Each button requires only:

• title: Display text (max 20 characters)

The id is auto-generated by the system.

Update Settings

Update chatbot settings.

PUT /api/chatbot/settings

Request Body

{
  "chatbot_enabled": true,
  "ai_enabled": true,
  "ai_provider": "anthropic",
  "ai_model": "claude-3-5-sonnet-latest",
  "ai_temperature": 0.7,
  "system_prompt": "You are a helpful assistant for our e-commerce store...",
  "greeting_message": "Welcome! How can I assist you today?",
  "greeting_buttons": [
    {"title": "My Orders"},
    {"title": "Get Support"}
  ],
  "fallback_message": "I'm not sure I understand. Please choose an option:",
  "fallback_buttons": [
    {"title": "Main Menu"}
  ]
}

Keyword Rules

List Rules

GET /api/chatbot/keywords

Response

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "Greeting Response",
        "keywords": ["hello", "hi", "hey"],
        "match_type": "contains",
        "response_type": "text",
        "response": "Hello! How can I help you today?",
        "priority": 10,
        "enabled": true
      }
    ]
  }
}

Create Rule

POST /api/chatbot/keywords

Request Body

{
  "name": "Business Hours",
  "keywords": ["hours", "open", "when"],
  "match_type": "contains",
  "response_type": "text",
  "response": "We're open Monday-Friday, 9 AM to 6 PM EST.",
  "priority": 5,
  "enabled": true
}

Match Types

| Type | Description | |------|-------------| | exact | Message must match keyword exactly | | contains | Message contains the keyword | | starts_with | Message starts with the keyword | | regex | Regular expression pattern match |

Update Rule

PUT /api/chatbot/keywords/{id}

Delete Rule

DELETE /api/chatbot/keywords/{id}

AI Contexts

AI Contexts provide additional knowledge to the AI for specific topics.

List Contexts

GET /api/chatbot/ai-contexts

Response

{
  "status": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "Product Catalog",
        "trigger_keywords": ["product", "price", "buy"],
        "context_type": "static",
        "content": "Our products include...",
        "priority": 10,
        "enabled": true
      }
    ]
  }
}

Create Context

POST /api/chatbot/ai-contexts

Request Body

{
  "name": "Shipping Policy",
  "trigger_keywords": ["shipping", "delivery", "track"],
  "context_type": "static",
  "content": "We offer free shipping on orders over $50. Standard delivery takes 3-5 business days...",
  "priority": 5,
  "enabled": true
}

Context Types

| Type | Description | |------|-------------| | static | Fixed text content | | api | Fetched from external API |

Update Context

PUT /api/chatbot/ai-contexts/{id}

Delete Context

DELETE /api/chatbot/ai-contexts/{id}

Conversation Flows

List Flows

GET /api/chatbot/flows

Create Flow

POST /api/chatbot/flows

Request Body

Flows are stored as a graph: nodes (each with an id, type, and type-specific config) connected by edges labelled with the outcome they handle. Execution starts at entry_node and walks edges until a node yields (waiting on user input) or terminates.

{
  "name": "Feedback Collection",
  "trigger_keywords": ["feedback", "review"],
  "initial_message": "Hi! I'd like to collect your feedback.",
  "completion_message": "Thank you for your feedback!",
  "enabled": true,
  "graph": {
    "version": 2,
    "entry_node": "rating",
    "nodes": [
      {
        "id": "rating",
        "type": "buttons",
        "label": "Ask for rating",
        "position": {"x": 0, "y": 0},
        "config": {
          "body": "How would you rate your experience?",
          "buttons": [
            {"id": "excellent", "title": "Excellent"},
            {"id": "good", "title": "Good"},
            {"id": "poor", "title": "Poor"}
          ]
        }
      },
      {
        "id": "comment",
        "type": "prompt",
        "label": "Collect comment",
        "position": {"x": 250, "y": 0},
        "config": {
          "body": "Any additional comments?",
          "store_as": "comment"
        }
      },
      {
        "id": "handoff",
        "type": "transfer",
        "label": "Transfer to team",
        "position": {"x": 500, "y": 0},
        "config": {
          "body": "Connecting you with our team…",
          "team_id": "<uuid>",
          "notes": "Rating: {{rating}}"
        }
      }
    ],
    "edges": [
      {"from": "rating", "to": "comment", "condition": "button:excellent"},
      {"from": "rating", "to": "comment", "condition": "button:good"},
      {"from": "rating", "to": "handoff", "condition": "button:poor"},
      {"from": "comment", "to": "handoff", "condition": "default"}
    ]
  }
}

Node Types

Every node has the shape { "id", "type", "label", "position", "config" }. The config schema depends on type.

| Type | Purpose | Key config fields | Outgoing edge conditions | |------|---------|-------------------|--------------------------| | message | Send a templated text message. | message | default | | prompt | Send a question; wait for and validate a reply. | body, store_as, validation_regex, validation_error, max_retries | default, max_retries | | buttons | Interactive reply buttons. | body, buttons: [{id,title}] | button:<id> per button | | api_call | HTTP request with response capture + optional templated reply. | url, method, headers, body, response_mapping, message_template | http:2xx, http:non2xx | | condition | Boolean expression branch (expr-lang syntax) over session data. | expression | true, false | | timing | Business-hours routing. | schedule: [{day,enabled,start_time,end_time}] | in_hours, out_of_hours | | whatsapp_flow | Send a native WhatsApp Flow form. | flow_id, header, body, cta | default | | transfer | Hand off to a team / queue and end the session. | body, team_id, notes | (terminal) | | goto_flow | Jump to another flow in the same org/account. | flow_id | (handled internally) | | webhook | Fire-and-forget HTTP call; result ignored. | url, method, headers, body | default | | end | Optionally send a final message and terminate. | message | (terminal) |

Edge resolution

For a node N that produces outcome O, the runtime picks the first edge in edges where from == N.id && condition == O. If no exact match exists it falls back to a condition: "default" edge. With no match at all the session terminates as completed.

Transfer Node Configuration

A transfer node ends the flow and creates an agent transfer:

{
  "id": "handoff",
  "type": "transfer",
  "config": {
    "body": "Connecting you with our support team…",
    "team_id": "<uuid>",
    "notes": "From flow: {{variable_name}}"
  }
}

| Field | Description | |-------|-------------| | body | Optional message sent to the user before handoff (templated). | | team_id | Target team UUID. Omit or set to "_general" for the shared queue. | | notes | Internal notes for agents (supports {{variable}} placeholders). |

Panel Configuration

Configure which session variables are displayed in the Contact Info Panel:

{
  "panel_config": {
    "sections": [
      {
        "id": "section-1",
        "label": "Customer Info",
        "columns": 1,
        "collapsible": true,
        "default_collapsed": false,
        "order": 1,
        "fields": [
          {"key": "customer_name", "label": "Name", "order": 1, "display_type": "text"},
          {"key": "status", "label": "Status", "order": 2, "display_type": "badge", "color": "success"}
        ]
      }
    ]
  }
}

Section Properties

| Field | Type | Description | |-------|------|-------------| | id | string | Unique section identifier | | label | string | Display label for the section | | columns | number | Layout columns (1 or 2) | | collapsible | boolean | Allow section to be collapsed | | default_collapsed | boolean | Start section in collapsed state | | order | number | Section display order | | fields | array | Fields to display in this section |

Field Properties

| Field | Type | Description | |-------|------|-------------| | key | string | Session variable name (from store_as or response mapping) | | label | string | Display label for the field | | order | number | Field display order within section | | display_type | string | How to render the value: text (default), badge, or tag | | color | string | Color for badge/tag: default, success, warning, error, or info |

Agent Transfers

List Transfers

Get agent transfer requests.

GET /api/chatbot/transfers

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | status | string | Filter by status: active or resumed | | team_id | string | Filter by team ID, or general for general queue |

Response

{
  "status": "success",
  "data": {
    "transfers": [
      {
        "id": "uuid",
        "contact_id": "uuid",
        "contact_name": "John Doe",
        "phone_number": "1234567890",
        "status": "active",
        "source": "flow",
        "agent_id": null,
        "agent_name": null,
        "team_id": "uuid",
        "team_name": "Sales Team",
        "notes": "Interested in enterprise plan",
        "transferred_at": "2024-01-01T12:00:00Z"
      }
    ],
    "general_queue_count": 3,
    "team_queue_counts": {
      "team-uuid-1": 5,
      "team-uuid-2": 2
    }
  }
}

Create Transfer

Manually transfer a conversation to a human agent or team.

POST /api/chatbot/transfers

Request Body

{
  "contact_id": "uuid",
  "team_id": "uuid",
  "notes": "Customer requested human support"
}

| Field | Type | Required | Description | |-------|------|----------|-------------| | contact_id | uuid | Yes | The contact to transfer | | team_id | uuid | No | Target team (omit for general queue) | | notes | string | No | Internal notes for agents |

Pick Next Transfer

Pick the next unassigned transfer from the queue.

POST /api/chatbot/transfers/pickup

Query Parameters

| Parameter | Type | Description | |-----------|------|-------------| | team_id | string | Pick from specific team, or general for general queue only |

Assign Transfer

Assign a transfer to a specific agent.

PUT /api/chatbot/transfers/{id}/assign

Request Body

{
  "agent_id": "uuid"
}

Resume from Transfer

Resume chatbot after human agent completes interaction.

PUT /api/chatbot/transfers/{id}/resume

Sessions

List Sessions

View active chatbot sessions (for debugging).

GET /api/chatbot/sessions

Get Session

Get details of a specific session.

GET /api/chatbot/sessions/{id}

Response

{
  "status": "success",
  "data": {
    "id": "uuid",
    "contact_id": "uuid",
    "current_flow_id": "uuid",
    "current_step": "rating",
    "variables": {
      "name": "John"
    },
    "started_at": "2024-01-01T12:00:00Z",
    "last_activity": "2024-01-01T12:05:00Z"
  }
}

Tip

Use the Sessions API to debug chatbot interactions and understand the conversation state.