REST API

Use the REST API to send messages to your chatbot and receive AI-generated replies programmatically. This is ideal for building custom chat interfaces, backend integrations, or automated workflows.

The REST API uses domain-based authentication. Requests are validated against the chatbot's configured Allowed Domains. Ensure your request originates from an allowed domain, or the API will return a 403 error.

For AI Team Wiki chatbots with protected access, include the X-Wiki-Auth header with the wiki authentication token.

Chat Endpoint

Send a Message

POST https://webchatagent.com/api/chat

Headers:

Header	Required	Description
`Content-Type`	Yes	Must be `application/json`
`X-Chat-Session-Id`	No	Session ID for conversation continuity. Omit for new conversations; the server returns a session ID in the response headers.

Request Body:

Field	Type	Required	Description
`message`	string	Yes	The user's message. Maximum 700 characters.
`chatbotId`	string	Yes	Your chatbot's UUID. Found in the chatbot settings.

Example Request:

{
  "message": "What are your business hours?",
  "chatbotId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Response:

Field	Type	Description
`reply`	string	The AI-generated response (may contain HTML formatting).
`sources`	array	Array of sources used to generate the answer.
`mode`	string	Current conversation mode: `bot` (AI handling) or `human` (live agent).
`status`	string	Live chat session status: `waiting`, `open`, or `closed`. Only present when Live Chat is active.

Sources Array Structure:

Each source object has:

Field	Type	Description
`type`	string	Source type: `web` (website page) or `product` (product data).
`source`	string	For `web`: the page URL. For `product`: the product identifier.
`data`	object	Additional data (only for `product` type). Contains `id`, `dataType`, `format`, `data`, and `sourceUrl`.

Example Response:

{
  "reply": "Our business hours are Monday to Friday, 9 AM to 5 PM CET.",
  "sources": [
    {
      "type": "web",
      "source": "https://example.com/contact"
    }
  ],
  "mode": "bot"
}

Chat History

Retrieve the message history for a specific session.

GET https://webchatagent.com/api/chat/history

Query Parameters:

Parameter	Type	Required	Description
`chatbotId`	string (UUID)	Yes	Your chatbot's ID.
`sessionId`	string (UUID)	Yes	The session ID to retrieve history for.

Response:

{
  "messages": [
    {
      "id": "msg_123",
      "sender": "user",
      "role": "user",
      "isAgent": false,
      "text": "What are your hours?",
      "sources": [],
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "msg_124",
      "sender": "assistant",
      "role": "assistant",
      "isAgent": false,
      "text": "Our hours are Monday to Friday, 9 AM to 5 PM.",
      "sources": [{ "type": "web", "source": "https://example.com/contact" }],
      "createdAt": "2025-01-15T10:30:01Z"
    }
  ]
}

Session Info

Retrieve metadata for one or more sessions.

GET https://webchatagent.com/api/chat/sessions

Query Parameters:

Parameter	Type	Required	Description
`chatbotId`	string (UUID)	Yes	Your chatbot's ID.
`sessionIds`	string	Yes	Comma-separated session IDs (max 5).

Response:

{
  "sessions": [
    {
      "sessionId": "sess_abc123",
      "messageCount": 12,
      "lastActivity": "2025-01-15T10:35:00Z"
    }
  ]
}

Delete Session

Delete a specific chat session and all its messages.

DELETE https://webchatagent.com/api/chat/session

Headers:

Header	Required	Description
`X-Chat-Session-Id`	Yes	The session ID to delete.

Response:

{ "success": true }

Error Handling

All errors return a JSON response with an error message in the reply field:

Status Code	Description
`400`	Invalid request body, missing fields, empty message, or message exceeds 700 characters.
`403`	Domain not allowed, wiki authentication failed, or plan restrictions.
`404`	Chatbot not found.
`429`	Rate limit exceeded or plan message quota reached.
`502`	AI provider (LLM) error.

Error Response Format:

{
  "reply": "Error description as HTML message",
  "sources": []
}

Rate Limit Details (429):

{
  "reply": "Rate limit exceeded",
  "sources": [],
  "data": {
    "code": "RATE_LIMIT",
    "details": "Too many requests",
    "suggestion": "Please wait before sending another message"
  }
}

Rate Limiting

Scope	Limit
Per session	10 requests per minute
Per IP address	15 requests per minute

Code Examples

cURL

# Send a message
curl -X POST https://webchatagent.com/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What products do you offer?",
    "chatbotId": "YOUR_CHATBOT_ID"
  }'

# Continue a conversation (with session ID)
curl -X POST https://webchatagent.com/api/chat \
  -H "Content-Type: application/json" \
  -H "X-Chat-Session-Id: SESSION_ID_FROM_FIRST_RESPONSE" \
  -d '{
    "message": "Tell me more about the premium plan",
    "chatbotId": "YOUR_CHATBOT_ID"
  }'

JavaScript / TypeScript

async function chat(message, chatbotId, sessionId = null) {
  const headers = { 'Content-Type': 'application/json' };
  if (sessionId) {
    headers['X-Chat-Session-Id'] = sessionId;
  }

  const response = await fetch('https://webchatagent.com/api/chat', {
    method: 'POST',
    headers,
    body: JSON.stringify({ message, chatbotId })
  });

  const data = await response.json();
  const newSessionId = response.headers.get('X-Chat-Session-Id');

  return { ...data, sessionId: newSessionId || sessionId };
}

// Usage
const result = await chat('Hello!', 'YOUR_CHATBOT_ID');
console.log(result.reply);

// Continue conversation
const followUp = await chat('Tell me more', 'YOUR_CHATBOT_ID', result.sessionId);
console.log(followUp.reply);

Python

import requests

CHATBOT_ID = "YOUR_CHATBOT_ID"
BASE_URL = "https://webchatagent.com/api/chat"

# Send first message
response = requests.post(BASE_URL, json={
    "message": "What are your business hours?",
    "chatbotId": CHATBOT_ID
})

data = response.json()
session_id = response.headers.get("X-Chat-Session-Id")
print(f"Reply: {data['reply']}")
print(f"Sources: {data['sources']}")

# Continue conversation
response = requests.post(BASE_URL, 
    json={"message": "And on weekends?", "chatbotId": CHATBOT_ID},
    headers={"X-Chat-Session-Id": session_id}
)
print(f"Reply: {response.json()['reply']}")

PHP

<?php
$chatbotId = 'YOUR_CHATBOT_ID';
$baseUrl = 'https://webchatagent.com/api/chat';

$ch = curl_init($baseUrl);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS => json_encode([
        'message' => 'What are your business hours?',
        'chatbotId' => $chatbotId,
    ]),
    CURLOPT_HEADER => true,
]);

$response = curl_exec($ch);
$headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$headers = substr($response, 0, $headerSize);
$body = json_decode(substr($response, $headerSize), true);

echo "Reply: " . $body['reply'] . PHP_EOL;

// Extract session ID from headers for follow-up messages
preg_match('/X-Chat-Session-Id:\s*(.+)/i', $headers, $matches);
$sessionId = trim($matches[1] ?? '');

curl_close($ch);