Conversation Widget

Get a specific Web Chat

GET /api/web-chats/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this web chat.

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/web-chats/550e8400-e29b-41d4-a716-446655440000/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please make sure to replace YOUR_API_KEY and verify the request data before execution.

JavaScript

const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/web-chats/550e8400-e29b-41d4-a716-446655440000/", config)
  .then(response => {
    console.log('Successfully retrieved response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred with the request:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/web-chats/550e8400-e29b-41d4-a716-446655440000/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("Successfully retrieved response:")
    print(response.json())
except Exception as e:
    print("An error occurred during the request:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = 'https://api.maiagent.ai/api/web-chats/550e8400-e29b-41d4-a716-446655440000/';
    $response = $client->get("https://api.maiagent.ai/api/web-chats/550e8400-e29b-41d4-a716-446655440000/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Successfully retrieved response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>

Response Body

Status Code: 200

Response Schema Example

{
  "id": string (uuid)
  "name": string
  "avatar"?: string (uri) // optional
  "logo"?: string (uri) // optional
  "description"?: string // optional
  "cover"?: string (uri) // optional
  "backUrl"?: string // optional
  "isActive"?: boolean // optional
  "enableSpeech": boolean
  "displayGreeting": string
  "displayConversationStarters": [
    string
  ]
  "theme": {
  {
    "primaryColor"?: string // optional
    "navbarTextColor"?: string // optional
    "conversationBackgroundColor"?: string // optional
    "chatbotMessageTextColor"?: string // optional
    "userMessageTextColor"?: string // optional
    "chatbotMessageBackgroundColor"?: string // optional
    "userMessageBackgroundColor"?: string // optional
    "chatbotMessageBackgroundShadowEnabled"?: boolean // optional
    "userMessageBackgroundShadowEnabled"?: boolean // optional
  }
  }
  "darkTheme": {
  {
    "primaryColor"?: string // optional
    "navbarTextColor"?: string // optional
    "conversationBackgroundColor"?: string // optional
    "chatbotMessageTextColor"?: string // optional
    "userMessageTextColor"?: string // optional
    "chatbotMessageBackgroundColor"?: string // optional
    "userMessageBackgroundColor"?: string // optional
    "chatbotMessageBackgroundShadowEnabled"?: boolean // optional
    "userMessageBackgroundShadowEnabled"?: boolean // optional
  }
  }
  "enableFileUpload"?: boolean // optional
  "enableDisplayCitations"?: boolean // optional
  "enableDisplayToolResults"?: boolean // optional
  "enableShareConversation"?: boolean // optional
  "enableLocation"?: boolean // optional
  "enableShowPoweredBy"?: boolean // optional
  "poweredByLogo"?: string (uri) // optional
  "enableAnonymous"?: boolean // optional
  "accessType": 
  {
  }
  "enableThemeModeToggle"?: boolean // optional
  "defaultThemeMode"?:  // optional
  {
  }
  "enableDownloadCitations"?: boolean // optional
  "customDomain"?:  // optional
  {
    "id": string (uuid)
    "domain": string
    "status": 
    {
    }
  }
  "enableDisplayChatbotAvatar"?: boolean // optional
  "enableDisplayChatbotName"?: boolean // optional
  "inbox": object
}

Response Example Value

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Test doc",
  "avatar": "https://example.com/static/images/default-chatbot-avatar.png",
  "logo": null,
  "description": "",
  "cover": null,
  "backUrl": "",
  "isActive": true,
  "enableSpeech": false,
  "displayGreeting": null,
  "displayConversationStarters": [],
  "theme": {
    "primaryColor": "#3854d8",
    "dialogColor": "#ddeaf6",
    "navbarTextColor": "#ffffff"
  },
  "enableFileUpload": true,
  "enableDisplayCitations": true,
  "enableShareConversation": false,
  "enableLocation": false,
  "enableShowPoweredBy": true,
  "poweredByLogo": null,
  "accessType": "web",
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Test doc",
    "signAuth": {
      "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
      "signSource": {
        "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "accessType": "keycloak"
      },
      "signParams": {
        "keycloak": {
          "url": "example.com",
          "realm": "example",
          "clientId": "example"
        }
      }
    }
  }
}

---

Get LLM Usage Statistics

GET /api/chatbots/{chatbotPk}/llm-usage-statistics/

Parameters

Parameter Name	Required	Type	Description
chatbotPk	✅	string	A UUID string identifying this Chatbot ID
endDate	❌	string	End date, format: YYYY-MM-DD
startDate	✅	string	Start date, format: YYYY-MM-DD
timeGranularity	✅	string	Time granularity (day/month)

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day", config)
  .then(response => {
    console.log('Successfully retrieved response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred with the request:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("Successfully got response:")
    print(response.json())
except Exception as e:
    print("Request failed:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/llm-usage-statistics/?endDate=example&startDate=example&timeGranularity=day", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response retrieved successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Error during request: ' . $e->getMessage();
}
?>

Response Body

Status Code: 200

Response Schema Example

[
  {
    "chatbotId": string (uuid)
    "wordsCount"?: integer (int64) // Optional
    "llmModelId": string
    "llmModelName": string
    "llmModelProvider": string
    "date": string (date)
    "totalWordsCount": integer // Calculate the total word count for a specific date and organization
    "llmDetails": [ // Get all model records for the same date and organization
      object
    ]
  }
]

Response Example Value

[
  [
    {
      "totalWordsCount": 511,
      "month": "2025-03-01",
      "llmDetails": [
        {
          "chatbotId": "5b646600-f6e0-4f07-aec7-0207a26c0a9b",
          "wordsCount": 511,
          "llmModelId": "d4282719-f50e-4a82-88d0-953e202a3383",
          "llmModelName": "GPT-4o-2024-08-06",
          "llmModelProvider": "openai"
        }
      ]
    }
  ]
]

Status Code: 400

Response Schema Example

{
  "detail"?: string // Optional
  "valid_types"?: [ // Optional
    string
  ]
}

Response Example Value

[
  [
    {
      "totalWordsCount": 511,
      "month": "2025-03-01",
      "llmDetails": [
        {
          "chatbotId": "5b646600-f6e0-4f07-aec7-0207a26c0a9b",
          "wordsCount": 511,
          "llmModelId": "d4282719-f50e-4a82-88d0-953e202a3383",
          "llmModelName": "GPT-4o-2024-08-06",
          "llmModelProvider": "openai"
        }
      ]
    }
  ]
]

---

Get AI Assistant Statistics

GET /api/chatbots/{chatbotPk}/statistics/

Parameters

Parameter Name	Required	Type	Description
chatbotPk	✅	string	A UUID string identifying this Chatbot ID
datetimeFrom	❌	string	Start time
datetimeTo	❌	string	End time
timeGranularity	❌	string	Time granularity (hour/day/month)

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?datetimeFrom=example&datetimeTo=example&timeGranularity=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY'
  }
};

axios.get("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?datetimeFrom=example&datetimeTo=example&timeGranularity=example", config)
  .then(response => {
    console.log('Successfully received response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred with the request:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?datetimeFrom=example&datetimeTo=example&timeGranularity=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("Successfully retrieved response:")
    print(response.json())
except Exception as e:
    print("An error occurred with the request:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/statistics/?datetimeFrom=example&datetimeTo=example&timeGranularity=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Successfully received response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'An error occurred with the request: ' . $e->getMessage();
}
?>

Response Body

Status Code: 200

Response Schema Example

[
  {
    "datetime": string (timestamp)
    "messagesCount"?: integer // Optional
    "conversationsCount"?: integer // Optional
    "avgMessagesPerConversation": number (double)
    "avgLikesPerFeedback": number (double)
  }
]

Response Example Value

[
  {
    "datetime": "Response String",
    "messagesCount": 456,
    "conversationsCount": 456,
    "avgMessagesPerConversation": 456,
    "avgLikesPerFeedback": 456
  }
]

---

Enable or Disable Evaluation for a Specific AI Assistant

PATCH /api/chatbots/{id}/enable-evaluation/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this Chatbot.

Request Body

Request Parameters

Field	Type	Required	Description
enableEvaluation	boolean	No

Request Structure Example

{
  "enableEvaluation"?: boolean // Optional
}

Request Example Value

{
  "enableEvaluation": true
}

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X PATCH "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enableEvaluation": true
  }'

# Please replace YOUR_API_KEY and verify the request data before execution.

JavaScript

const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
};

// Request payload
const data = {
    "enableEvaluation": true
  };

axios.patch("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/", data, config)
  .then(response => {
    console.log('Successfully received response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred with the request:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request payload
data = {
      "enableEvaluation": true
    }

response = requests.patch(url, json=data, headers=headers)
try:
    print("Successfully got response:")
    print(response.json())
except Exception as e:
    print("Request failed:", e)

PHP

<?php
require 'vendor/autoload.php';

$client = new GuzzleHttp\Client();

try {
    $response = $client->patch("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/enable-evaluation/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "enableEvaluation": true
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Response received successfully:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>

Response Body

Status Code: 200

Response Schema Example

{
  "enableEvaluation"?: boolean // Optional
}

Response Example Value

{
  "enableEvaluation": false
}

---