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.