Chatbot API Documentation

Integration with the chatbot API is a process consisting of several key stages that will enable smooth connection of your application with our system.

1. Configuration and Authentication - preparing the chatbot in the ChatbotAssistant panel and obtaining the API key.
2. Understanding the Workflow - familiarizing yourself with the asynchronous communication model based on webhooks.
3. Endpoint Implementation - using the API to create sessions and send messages.
4. Response Handling - creating a webhook endpoint to receive and verify responses from the chatbot.
5. Applying Best Practices - implementing recommendations for security, performance, and error handling.

All API requests require authentication using an API key. The key can be found and generated in API settings.

Authentication Header

The API key should be passed in the HTTP header X-API-Key:

API Key Management

You can manage your API keys in the admin panel:

1. Generating new API keys
2. Revoking access for compromised keys

In this section, you will learn how to create and configure a new chatbot on the ChatbotAssistant platform based on our API.

Configuration Steps:

1. On the side menu, find and click the section Create Chatbot, select the option Manual Configuration, or go to the section Dashboard, then select Create New Chatbot
2. In the chatbot creation panel, in the section Select Chatbot Features check the option API Integration
3. You can also check the feature Website Widget during configuration API Integration
4. Fill out the chatbot creation form by entering the following information:
   • Chatbot Name - enter the chatbot name that users will see, e.g. Customer Support
   • Description (optional) - will help you find the right chatbot
   • Company Information - enter detailed information about your company, products, services, prices, opening hours, etc. The more information you provide, the better the chatbot will respond to customer questions.
   • Allowed Domains (for website widget option) - provide your website domain, e.g. example.com (without https://). If you have more than one domain or subdomain, enter all of them separated by commas. (NOT RECOMMENDED) Leave the field empty to allow all domains.
5. At the bottom of the form, you will see a section called API Configuration, where you must provide the address Webhook URL of your page. This is the address where chatbot responses will be sent in API mode
6. After filling in all the fields necessary for the chatbot to function, click the button Create Chatbot
7. Now it will be possible to obtain Webhook Secret. To find the secret, go to the section Dashboard and find the chatbot created in the previous steps
8. You will find the webhook secret in the section Options, then Webhook Settings or by clicking the button Edit and going to the bottom of the page

Generating a New Webhook Secret:

At any time you can generate a new webhook secret. Just:

1. Go to the section Dashboard, find the specific chatbot, click Options, then Webhook Settings.
2. Under the section Webhook Secret check the box Generate new webhook secret and confirm the operation with the button Save Changes.
3. After saving the changes, a new webhook secret will be automatically generated and visible in the webhook settings panel.

Webhook Configuration

The webhook URL must meet the following requirements:

• Must use HTTPS protocol
• Must be accessible from the internet (cannot be a private address)
• Must respond with 200 OK code to POST requests
• Should handle signature headers for verification

The API enables integration of the chatbot with your application or system. A typical workflow looks as follows:

1. Authentication - using the API key in the request header
2. Create Chat Session - initiating a new conversation with the chatbot
3. Sending User Messages - passing the message content to the chatbot
4. Receiving Chatbot Response via Webhook - processing the asynchronous response

All requests and responses use JSON format.

Data Flow Diagram

The chatbot API provides the following main endpoints:

Below you will find detailed specifications for each endpoint, along with request and response examples.

After the message is processed by the chatbot, the response will be sent to the configured webhook URL. The webhook will receive the following data format:

Webhook Data Format

{
  "id": 457,
  "role": "assistant",
  "content": "Good morning! How can I help?",
  "timestamp": "2026-04-10T15:23:45.123456",
  "session_token": "abc123def456",
  "chatbot_id": 123,
  "webhook_data": {
    "conversation_id": "conv-456",
    "department": "sales",
    "message_reference": "msg-789",
    "context": "homepage",
    "custom_field": "value"
  }
}

Webhook Response Structure:

Webhook Headers

The webhook contains the following headers that can be used to verify the source:

Example Webhook Handling Implementation

const express = require('express');
const bodyParser = require('body-parser');
const crypto = require('crypto');

const app = express();
const PORT = 3000;
const WEBHOOK_SECRET = 'secret123'; // from the admin panel

// Middleware for parsing JSON
app.use(bodyParser.json());

// Webhook endpoint
app.post('/webhooks/chatbot', (req, res) => {
  const timestamp = req.headers['x-signature-timestamp'];
  const signature = req.headers['x-signature-hash'];
  const payload = JSON.stringify(req.body);

  // Signature verification
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  if (signature !== expectedSignature) {
    console.error('Invalid webhook signature');
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Message processing
  const { id, role, content, session_token, webhook_data } = req.body;

  console.log(`Received message from chatbot: ${content}`);
  console.log(`Webhook Data:`, webhook_data);

  // Process the message here...

  // Confirmation of receipt
  res.status(200).json({ success: true });
});

app.listen(PORT, () => {
  console.log(`Webhook server running on port ${PORT}`);
});

from flask import Flask, request, jsonify
import hmac
import hashlib
import json

app = Flask(__name__)
WEBHOOK_SECRET = 'secret123'  # from admin panel

@app.route('/webhooks/chatbot', methods=['POST'])
def chatbot_webhook():
    # Get data and headers
    timestamp = request.headers.get('X-Signature-Timestamp')
    signature = request.headers.get('X-Signature-Hash')
    payload = request.data.decode('utf-8')

    # Signature verification
    expected_signature = hmac.new(
        WEBHOOK_SECRET.encode(),
        f"{timestamp}.{payload}".encode(),
        hashlib.sha256
    ).hexdigest()

    # Check signature
    if not hmac.compare_digest(expected_signature, signature):
        return jsonify({'error': 'Invalid signature'}), 401

    # Data processing
    data = request.json
    message_id = data.get('id')
    content = data.get('content')
    session_token = data.get('session_token')
    webhook_data = data.get('webhook_data', {})

    print(f"Received message from chatbot: {content}")
    print(f"Webhook data: {webhook_data}")

    # Message processing here...

    # Confirmation of receipt
    return jsonify({'success': True})

if __name__ == '__main__':
    app.run(port=5000, debug=True)

<?php
// Get data from request
$payload = file_get_contents('php://input');
$data = json_decode($payload, true);

// Get headers
$timestamp = $_SERVER['HTTP_X_SIGNATURE_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_SIGNATURE_HASH'] ?? '';

// Webhook secret from admin panel
$webhookSecret = 'secret123';

// Signature verification
$expectedSignature = hash_hmac('sha256', $timestamp . '.' . $payload, $webhookSecret);

if (!hash_equals($expectedSignature, $signature)) {
    header('HTTP/1.1 401 Unauthorized');
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

// Data processing
$messageId = $data['id'] ?? null;
$content = $data['content'] ?? '';
$sessionToken = $data['session_token'] ?? '';
$webhookData = $data['webhook_data'] ?? [];

// Logging
error_log("Received message from chatbot: " . $content);
error_log("Webhook data: " . json_encode($webhookData));

// Process the message here...

// Confirmation of receipt
header('Content-Typee: application/json');
echo json_encode(['success' => true]);
?>

To ensure security and verify that the webhook comes from our system, we recommend checking the signature headers:

• X-Signature-Timestamp - timestamp in Unix format
• X-Signature-Hash - HMAC-SHA256 signature

Verification Algorithm

The signature verification algorithm consists of the following steps:

1. Retrieve headers X-Signature-Timestamp and X-Signature-Hash from the request
2. Retrieve the request body as a raw string (payload)
3. Combine timestamp and payload, separating them with a dot: {timestamp}.{payload}
4. Calculate HMAC-SHA256 of the combined string, using the webhook secret as the key
5. Compare the calculated HMAC with the header X-Signature-Hash, using secure string comparison

Signature Verification Code Example (Python)

import hmac
import hashlib

def verify_webhook(request, webhook_secret):
    timestamp = request.headers.get('X-Signature-Timestamp')
    signature = request.headers.get('X-Signature-Hash')
    payload = request.body  # As a JSON string

    expected_signature = hmac.new(
        webhook_secret.encode(),
        f"{timestamp}.{payload}".encode(),
        digestmod=hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(expected_signature, signature)

Signature Verification Code Example (Node.js)

const crypto = require('crypto');

function verifyWebhook(req, webhookSecret) {
  const timestamp = req.headers['x-signature-timestamp'];
  const signature = req.headers['x-signature-hash'];
  const payload = JSON.stringify(req.body);

  const expectedSignature = crypto
    .createHmac('sha256', webhookSecret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(expectedSignature, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

Obtaining the Webhook Secret

The webhook secret used for signature verification can be obtained in two ways:

1. It is returned during session creation in the JSON response in the webhook.secret field
2. It can be found in the admin panel in the chatbot settings

You can pass any data in the parameter webhook_data, which will be returned in the webhook response. This is useful for:

• Identifying which conversation the response relates to
• Tracking business context (e.g. department, product category)
• Routing responses to appropriate systems or users
• Passing additional metadata to your application

How It Works

Webhook Data can be passed both during session creation and with each message sent:

• Data passed during session creation - will be attached to all webhook responses for that session
• Data passed during message sending - will replace session data only for the response to this specific message

Use Case Examples

1. Tracking Conversation Source

{
  "webhook_data": {
    "source": "landing_page",
    "campaign": "spring_sale_2026",
    "referrer": "google"
  }
}

2. Passing User Data

{
  "webhook_data": {
    "user_id": "u-123456",
    "user_type": "registered",
    "account_level": "premium"
  }
}

3. CRM System Integration

{
  "webhook_data": {
    "crm_ticket_id": "T-78901",
    "customer_segment": "enterprise",
    "priority": "high"
  }
}

The API may return the following HTTP error codes:

Error Response Format

In case of an error, the API will return a JSON response with the following structure:

{
  "success": false,
  "error": "Error description",
  "code": "ERROR_CODE" // Optional error code
}

Detailed Error Codes

When integrating with the chatbot API, it is worth following these best practices:

Security

1. Verify session identifiers

   Store session identifiers in a secure location and verify they belong to the appropriate user.

2. Always verify webhook signatures

   Webhook signatures ensure that data comes from our system and has not been modified.

3. Use HTTPS

   All communications with the API should be conducted through HTTPS to ensure data encryption.

4. Rotate API keys regularly

   We recommend periodic API key rotation to minimize the risk of unauthorized access.

Performance and Reliability

1. Monitor API Usage

   Track API usage to avoid exceeding limits and identify usage patterns.

2. Optimize webhooks

   Ensure your webhook server responds quickly to avoid timeouts. We recommend delegating heavy operations to asynchronous tasks.

Session Management

1. Use unique client identifiers

   Parameter client_id helps in tracking sessions and troubleshooting.

2. Store conversation context

   If necessary, save the conversation history on your side to maintain context, even if the session expires.

Integration

1. Use webhook_data

   Parameter webhook_data allows passing business context and facilitates integration of responses with your system.

2. Test in Development Environment

   Always test integration in a development environment before going to production.

Rate limiting is a mechanism that limits the number of API requests one user can make in a given time period. This protects the system from excessive load and ensures fair resource utilization for all API users.

How Rate Limiting Works:

• Limit per User: Each user has their own limit (not shared with others)
• Time Window: 60 seconds
• Automatic Reset: Counter resets every minute
• Configurable Limit: Each user can have a different limit set by the administrator

What This Means for API Requests:

When a user reaches their request limit within a minute, the API will return an error 429 Too Many Requests. The response to error 429 will include information about the time after which the request can be retried.

Example Response When Limit Exceeded:

{
      "success": false,
      "error": "Rate limit exceeded",
      "code": "RATE_LIMIT_EXCEEDED",
      "retry_after": 45
    }

Field retry_after indicates the number of seconds after which the request can be retried.

Handling Rate Limiting in Code:

We recommend implementing a retry mechanism in case of receiving error 429:

async function apiRequestWithRetry(url, options, maxRetries = 3) {
      for (let attempt = 0; attempt <= maxRetries; attempt++) {
        try {
          const response = await fetch(url, options);
          
          if (response.status === 429) {
            const data = await response.json();
            const retryAfter = data.retry_after || 60;
            
            if (attempt < maxRetries) {
              console.log(`Rate limit hit, retrying after ${retryAfter} seconds...`);
              await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
              continue;
            }
            throw new Error('Rate limit exceeded, max retries reached');
          }
          
          return response;
        } catch (error) {
          if (attempt === maxRetries) throw error;
        }
      }
    }

import time
    import requests
    from requests.exceptions import RequestException
    
    def api_request_with_retry(url, headers, data, max_retries=3):
        for attempt in range(max_retries + 1):
            try:
                response = requests.post(url, headers=headers, json=data)
                
                if response.status_code == 429:
                    retry_after = response.json().get('retry_after', 60)
                    
                    if attempt < max_retries:
                        print(f"Rate limit hit, retrying after {retry_after} seconds...")
                        time.sleep(retry_after)
                        continue
                    raise Exception('Rate limit exceeded, max retries reached')
                
                return response
                
            except RequestException as e:
                if attempt == max_retries:
                    raise e

<?php
    function apiRequestWithRetry($url, $headers, $data, $maxRetries = 3) {
        for ($attempt = 0; $attempt <= $maxRetries; $attempt++) {
            $ch = curl_init();
            curl_setopt($ch, CURLOPT_URL, $url);
            curl_setopt($ch, CURLOPT_POST, true);
            curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
            curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            
            $response = curl_exec($ch);
            $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
            curl_close($ch);
            
            if ($httpCode === 429) {
                $responseData = json_decode($response, true);
                $retryAfter = $responseData['retry_after'] ?? 60;
                
                if ($attempt < $maxRetries) {
                    error_log("Rate limit hit, retrying after {$retryAfter} seconds...");
                    sleep($retryAfter);
                    continue;
                }
                throw new Exception('Rate limit exceeded, max retries reached');
            }
            
            return $response;
        }
    }
    ?>

Increasing Rate Limiting Limits:

If the standard rate limiting limits are not sufficient for your use case (e.g. for very high-traffic integrations or specialized applications), you can request an increase.