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 and usage statistics.

GET /api/chatbot/settings

Response

{
  "status": "success",
  "data": {
    "settings": {
      "enabled": true,
      "greeting_message": "Hello! Welcome to our support. How can I help you?",
      "greeting_buttons": [
        {"id": "track_order", "title": "Track Order"},
        {"id": "speak_agent", "title": "Speak to Agent"}
      ],
      "fallback_message": "Sorry, I didn't understand that. Please try again.",
      "fallback_buttons": [
        {"id": "main_menu", "title": "Main Menu"}
      ],
      "session_timeout_minutes": 30,
      "business_hours_enabled": false,
      "business_hours": [],
      "out_of_hours_message": "We are currently closed.",
      "allow_automated_outside_hours": true,
      "allow_agent_queue_pickup": true,
      "assign_to_same_agent": true,
      "agent_current_conversation_only": false,
      "ai_enabled": true,
      "ai_provider": "openai",
      "ai_model": "gpt-4o-mini",
      "ai_max_tokens": 500,
      "ai_system_prompt": "You are a helpful customer service assistant...",
      "sla_enabled": false,
      "sla_response_minutes": 15,
      "sla_resolution_minutes": 60,
      "sla_escalation_minutes": 30,
      "sla_auto_close_hours": 24,
      "sla_auto_close_message": "Ticket closed automatically.",
      "sla_warning_message": "Are you still there?",
      "sla_escalation_notify_ids": [],
      "client_reminder_enabled": false,
      "client_reminder_minutes": 5,
      "client_reminder_message": "Reminder: please reply.",
      "client_auto_close_minutes": 10,
      "client_auto_close_message": "Session closed due to inactivity."
    },
    "stats": {
      "total_sessions": 120,
      "active_sessions": 5,
      "messages_handled": 1450,
      "ai_responses": 950,
      "agent_transfers": 15,
      "keywords_count": 8,
      "flows_count": 3,
      "ai_contexts_count": 2
    }
  }
}

Update Settings

Update chatbot settings.

PUT /api/chatbot/settings

Request Body

Supports updating any of the settings fields shown above.

{
  "enabled": true,
  "ai_enabled": true,
  "ai_provider": "openai",
  "ai_model": "gpt-4o-mini",
  "ai_system_prompt": "You are a helpful assistant for our e-commerce store...",
  "greeting_message": "Welcome! How can I assist you today?"
}

Keyword Rules

List Rules

GET /api/chatbot/keywords

Query Parameters

Parameter	Type	Description
page	integer	Page number (default: 1)
limit	integer	Items per page (default: 20)
search	string	Search rule name or keywords

Response

{
  "status": "success",
  "data": {
    "rules": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Greeting Response",
        "keywords": ["hello", "hi", "hey"],
        "match_type": "contains",
        "response_type": "text",
        "response_content": "Hello! How can I help you today?",
        "priority": 10,
        "enabled": true,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

Create Rule

POST /api/chatbot/keywords

Request Body

{
  "name": "Business Hours",
  "keywords": ["hours", "open", "when"],
  "match_type": "contains",
  "response_type": "text",
  "response_content": "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

Query Parameters

Parameter	Type	Description
page	integer	Page number
limit	integer	Items per page
search	string	Search name, content, or keywords

Response

{
  "status": "success",
  "data": {
    "contexts": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Product Catalog",
        "context_type": "static",
        "trigger_keywords": ["product", "price", "buy"],
        "static_content": "Our products include...",
        "enabled": true,
        "priority": 10,
        "created_at": "2024-01-01T00:00:00Z",
        "updated_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

Create Context

POST /api/chatbot/ai-contexts

Request Body

{
  "name": "Shipping Policy",
  "trigger_keywords": ["shipping", "delivery", "track"],
  "context_type": "static",
  "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

Query Parameters

Parameter	Type	Description
page	integer	Page number
limit	integer	Items per page
search	string	Search name, description, or keywords

Response

{
  "status": "success",
  "data": {
    "flows": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Feedback Collection",
        "description": "Flow to collect customer feedback",
        "trigger_keywords": ["feedback", "review"],
        "enabled": true,
        "created_at": "2024-01-01T00:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 20
  }
}

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.

{
  "name": "Feedback Collection",
  "description": "Flow to collect customer feedback",
  "trigger_keywords": ["feedback", "review"],
  "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": "880e8400-e29b-41d4-a716-446655440000",
          "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

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 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)

Update Flow

PUT /api/chatbot/flows/{id}

Delete Flow

DELETE /api/chatbot/flows/{id}

Agent Transfers

Agent transfers manage the transition from the automated chatbot to human support agents.

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
limit	integer	Pagination limit
offset	integer	Pagination offset
include	string	Relations to load (e.g. contact,agent,team or all)

Response

{
  "status": "success",
  "data": {
    "transfers": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "contact_id": "660e8400-e29b-41d4-a716-446655440000",
        "contact_name": "John Doe",
        "phone_number": "+1234567890",
        "whatsapp_account": "default_account",
        "status": "active",
        "source": "flow",
        "agent_id": null,
        "agent_name": null,
        "team_id": "880e8400-e29b-41d4-a716-446655440000",
        "team_name": "Sales Team",
        "notes": "Interested in enterprise plan",
        "transferred_at": "2024-01-01T12:00:00Z"
      }
    ],
    "general_queue_count": 3,
    "team_queue_counts": {
      "880e8400-e29b-41d4-a716-446655440000": 5
    },
    "total_count": 8,
    "limit": 100,
    "offset": 0
  }
}

Create Transfer

Manually transfer a conversation to a human agent or team.

POST /api/chatbot/transfers

Request Body

{
  "contact_id": "660e8400-e29b-41d4-a716-446655440000",
  "whatsapp_account": "default_account",
  "team_id": "880e8400-e29b-41d4-a716-446655440000",
  "notes": "Customer requested human support",
  "source": "manual"
}

Pick Next Transfer

Pick the next unassigned transfer from the queue (self-assignment).

POST /api/chatbot/transfers/pick

Query Parameters

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

Response

{
  "status": "success",
  "data": {
    "message": "Transfer picked successfully",
    "transfer": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "contact_id": "660e8400-e29b-41d4-a716-446655440000",
      "phone_number": "+1234567890",
      "whatsapp_account": "default_account",
      "status": "active",
      "source": "flow",
      "notes": "Interested in enterprise plan",
      "transferred_at": "2024-01-01T12:00:00Z",
      "agent_id": "770e8400-e29b-41d4-a716-446655440000",
      "agent_name": "Jane Smith"
    }
  }
}

Assign Transfer

Assign a transfer to a specific agent, or unassign (returning it to the queue).

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

Request Body

{
  "agent_id": "770e8400-e29b-41d4-a716-446655440000",
  "team_id": "880e8400-e29b-41d4-a716-446655440000"
}

Note

Pass agent_id as null or an empty string to unassign the transfer.

Response

{
  "status": "success",
  "data": {
    "message": "Transfer assigned successfully",
    "agent_id": "770e8400-e29b-41d4-a716-446655440000"
  }
}

Resume from Transfer

End human agent interaction and resume chatbot processing.

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

Response

{
  "status": "success",
  "data": {
    "message": "Transfer resumed, chatbot is now active for this contact"
  }
}

Sessions

List Sessions

View active chatbot sessions (primarily for debugging).

GET /api/chatbot/sessions

Query Parameters

Parameter	Type	Description
status	string	Filter sessions by status: active, completed, cancelled, timeout

Get Session

Get details of a specific session.

GET /api/chatbot/sessions/{id}

Response

{
  "status": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "contact_id": "660e8400-e29b-41d4-a716-446655440000",
    "current_flow_id": "770e8400-e29b-41d4-a716-446655440000",
    "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.