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

{
  "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,
  "panel_config": {
    "sections": [
      {
        "id": "customer",
        "label": "Customer Info",
        "columns": 1,
        "collapsible": true,
        "default_collapsed": false,
        "order": 1,
        "fields": [
          {"key": "rating", "label": "Rating", "order": 1},
          {"key": "comment", "label": "Comment", "order": 2}
        ]
      }
    ]
  },
  "steps": [
    {
      "step_name": "rating",
      "step_order": 1,
      "message": "How would you rate your experience?",
      "message_type": "buttons",
      "input_type": "select",
      "buttons": [
        {"id": "excellent", "title": "Excellent"},
        {"id": "good", "title": "Good"},
        {"id": "poor", "title": "Poor"}
      ],
      "store_as": "rating"
    },
    {
      "step_name": "comment",
      "step_order": 2,
      "message": "Any additional comments?",
      "message_type": "text",
      "input_type": "text",
      "store_as": "comment"
    },
    {
      "step_name": "transfer",
      "step_order": 3,
      "message": "Connecting you with our team...",
      "message_type": "transfer",
      "transfer_config": {
        "team_id": "uuid",
        "notes": "Rating: {{rating}}"
      }
    }
  ]
}

Step Message Types

Type	Description
`text`	Send a static text message
`buttons`	Send message with interactive buttons
`api_fetch`	Fetch message content from external API
`whatsapp_flow`	Trigger a native WhatsApp Flow
`transfer`	Transfer conversation to agent/team and end flow

Transfer Step Configuration

The transfer message type ends the flow and creates an agent transfer:

{
  "message_type": "transfer",
  "message": "Connecting you with our support team...",
  "transfer_config": {
    "team_id": "uuid",
    "notes": "From flow: {{variable_name}}"
  }
}

Field	Description
`team_id`	Target team UUID (omit for general 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"
  }
}