Conversations and Messages

Send Message (Stream)

POST /api/chatbots/{chatbotId}/completions/

Parameters

Parameter Name	Required	Type	Description
chatbotId	✅	string

Request Body

Request Parameters

Field	Type	Required	Description
conversation	string (uuid)	No	The unique identifier for the conversation. If empty, a new conversation will be created (optional).
message	object (with 5 properties: content, contentPayload, queryMetadata...)	Yes	The message content to be sent.
message.content	string	Yes	The text content of the message.
message.contentPayload	object	No	Additional payload for the message, in JSON format (optional).
message.queryMetadata	object	No	Query metadata, in JSON format (optional).
message.attachments	array[AttachmentInput]	No	A list of attachments for the message (optional).
message.sender	string (uuid)	No	The Contact ID of the sender (optional).
isStreaming	boolean	No	Whether to use streaming mode for the response. Defaults to false (optional).

Request Structure Example

{
  "conversation"?: string (uuid) // The unique identifier for the conversation. If empty, a new conversation will be created (optional).
  "message":  // The message content to be sent.
  {
    "content": string // The text content of the message.
    "contentPayload"?: object // Additional content payload for the message, in JSON format (optional).
    "queryMetadata"?: object // Query metadata, in JSON format (optional).
    "attachments"?: [ // List of attachments for the message (optional).
      {
        "id": string (uuid) // The unique identifier for the attachment.
        "type":  // Attachment type. Possible values: image, video (in development, not yet supported), audio, sticker (in development, not yet supported), other.

* `image` - Image
* `video` - Video
* `audio` - Audio
* `sticker` - Sticker
* `other` - Other
        {
        }
        "filename": string // The filename of the attachment.
        "file": string (uri) // The URL address of the attachment file.
      }
    ]
    "sender"?: string (uuid) // The Contact ID of the sender (optional).
  }
  "isStreaming"?: boolean // Whether to respond in streaming mode, defaults to false (optional).
}

Request Example Value

{
  "conversation": "550e8400-e29b-41d4-a716-446655440000",
  "message": {
    "content": "Hello! I would like to get product information.",
    "contentPayload": null,
    "queryMetadata": null,
    "attachments": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": {},
        "filename": "document.pdf",
        "file": "https://example.com/file.jpg"
      }
    ],
    "sender": "550e8400-e29b-41d4-a716-446655440000"
  },
  "isStreaming": true
}

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X POST --no-buffer "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": "550e8400-e29b-41d4-a716-446655440000",
    "message": {
      "content": "Hello! I would like to get some product information.",
      "contentPayload": null,
      "queryMetadata": null,
      "attachments": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": {},
          "filename": "document.pdf",
          "file": "https://example.com/file.jpg"
        }
      ],
      "sender": "550e8400-e29b-41d4-a716-446655440000"
    },
    "isStreaming": true
  }'

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

# Note: This API returns streaming data, which can be handled in the following ways:
# Method 1: Use jq to process each JSON data chunk
# Example: curl -X POST --no-buffer "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": "550e8400-e29b-41d4-a716-446655440000",
    "message": {
      "content": "Hello! I would like to get some product information.",
      "contentPayload": null,
      "queryMetadata": null,
      "attachments": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": {},
          "filename": "document.pdf",
          "file": "https://example.com/file.jpg"
        }
      ],
      "sender": "550e8400-e29b-41d4-a716-446655440000"
    },
    "isStreaming": true
  }' | jq -r .

# Method 2: Use a pipe to write the output to a file
# Example: curl -X POST --no-buffer "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": "550e8400-e29b-41d4-a716-446655440000",
    "message": {
      "content": "Hello! I would like to get some product information.",
      "contentPayload": null,
      "queryMetadata": null,
      "attachments": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": {},
          "filename": "document.pdf",
          "file": "https://example.com/file.jpg"
        }
      ],
      "sender": "550e8400-e29b-41d4-a716-446655440000"
    },
    "isStreaming": true
  }' > response.json

JavaScript

const axios = require('axios');

// Set request headers
const config = {
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  responseType: 'stream' // Set to streaming response mode
};

// Request payload
const data = {
    "conversation": "550e8400-e29b-41d4-a716-446655440000",
    "message": {
      "content": "Hello! I would like to know more about the product.",
      "contentPayload": null,
      "queryMetadata": null,
      "attachments": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": {},
          "filename": "document.pdf",
          "file": "https://example.com/file.jpg"
        }
      ],
      "sender": "550e8400-e29b-41d4-a716-446655440000"
    },
    "isStreaming": true
  };

axios.post("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/", data, config)
  .then(response => {
    console.log('Streaming response started:');
    
    let completeResponse = '';
    
    // Listen for data chunks
    response.data.on('data', (chunk) => {
      // Convert Buffer to string
      const chunkText = chunk.toString('utf8');
      console.log(`Received chunk: ${chunkText}`);
      
      completeResponse += chunkText;
      
      // Try to parse JSON data chunks
      try {
        // Check if it is a complete JSON object
        if (chunkText.trim().startsWith('{') && chunkText.trim().endsWith('}')) {
          const chunkData = JSON.parse(chunkText);
          console.log('Parsed chunk data:', JSON.stringify(chunkData, null, 2));
        }
      } catch (err) {
        // This might be a partial chunk that cannot be parsed as JSON
      }
    });
    
    // Handle stream end event
    response.data.on('end', () => {
      console.log('\nComplete accumulated response:');
      console.log(completeResponse);
    });
  })
  .catch(error => {
    console.error('Error occurred during streaming request:');
    console.error(error.message);
  });

Python

import requests
import json

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

# Request payload
data = {
      "conversation": "550e8400-e29b-41d4-a716-446655440000",
      "message": {
        "content": "Hello! I would like to know more about the product information.",
        "contentPayload": None,
        "queryMetadata": None,
        "attachments": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "type": {},
            "filename": "document.pdf",
            "file": "https://example.com/file.jpg"
          }
        ],
        "sender": "550e8400-e29b-41d4-a716-446655440000"
      },
      "isStreaming": True  # Enable streaming mode
    }

# Process the response using streaming
try:
    with requests.post(url, json=data, headers=headers, stream=True) as response:
        print("Streaming response reception started:")
        
        # Variable to accumulate the complete response
        complete_response = ""
        
        # Receive data chunk by chunk
        for chunk in response.iter_content(chunk_size=1024):
            if chunk:  # Filter out keep-alive new chunks
                # Try to decode
                chunk_text = chunk.decode('utf-8', errors='replace')
                print(f"Received chunk: {chunk_text}")
                
                complete_response += chunk_text
                
                # Try to parse the JSON data chunk
                try:
                    # Check if it is a complete JSON object
                    if chunk_text.strip().startswith('{') and chunk_text.strip().endswith('}'):
                        chunk_data = json.loads(chunk_text)
                        print(f"Parsed chunk data: {json.dumps(chunk_data, indent=2, ensure_ascii=False)}")
                except json.JSONDecodeError:
                    # This is a partial chunk and cannot be parsed as JSON alone
                    pass
        
        print("\nComplete accumulated response:")
        print(complete_response)
        
except Exception as e:
    print("An error occurred during the streaming request:", e)

PHP

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

$client = new GuzzleHttp\Client();

try {
    // Use streaming option
    $response = $client->post("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/completions/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "conversation": "550e8400-e29b-41d4-a716-446655440000",
            "message": {
                "content": "Hello! I would like to know more about the product information.",
                "contentPayload": null,
                "queryMetadata": null,
                "attachments": [
                    {
                        "id": "550e8400-e29b-41d4-a716-446655440000",
                        "type": {},
                        "filename": "document.pdf",
                        "file": "https://example.com/file.jpg"
                    }
                ],
                "sender": "550e8400-e29b-41d4-a716-446655440000"
            },
            "isStreaming": true
        },
        'stream' => true  // Enable streaming
    ]);
    
    echo "Stream response receiving started:\n";
    
    // Variable to accumulate the complete response
    $completeResponse = "";
    
    // Get the response body as a stream
    $body = $response->getBody();
    
    // Read the stream data chunk by chunk
    while (!$body->eof()) {
        $chunk = $body->read(1024);  // Read 1KB of data
        
        if ($chunk) {
            echo "Received chunk: " . $chunk . "\n";
            
            $completeResponse .= $chunk;
            
            // Try to parse the JSON data chunk
            if (preg_match('/^\s*{.*}\s*$/', $chunk)) {
                try {
                    // Try to parse as JSON
                    $chunkData = json_decode($chunk, true);
                    if (json_last_error() === JSON_ERROR_NONE) {
                        echo "Parsed chunk data:\n";
                        print_r($chunkData);
                    }
                } catch (Exception $parseError) {
                    // Cannot parse as JSON, might be a partial chunk
                }
            }
        }
    }
    
    echo "\nComplete accumulated response:\n";
    echo $completeResponse;
    
} catch (Exception $e) {
    echo 'Stream request error: ' . $e->getMessage();
}
?>

Response Body

Status Code	Description
200	Dialogue response content, or an event stream if streaming.
400	Request parameter error. Possible reasons include: the Contact ID does not belong to the organization.

---

Send Message (Create)

POST /api/messages/

Request Body

Request Parameters

Field	Type	Required	Description
conversation	string (uuid)	Yes
type	string	No
content	string	No
contentPayload	object	No
attachments	array[AttachmentCreateInput]	No
canvas	object	No
canvas.name	string	Yes
canvas.canvasType	object	Yes
canvas.title	string	Yes
canvas.content	string	Yes
queryMetadata	object	No

Request Structure Example

{
  "conversation": string (uuid)
  "type"?: string // Optional
  "content"?: string // Optional
  "contentPayload"?: object // Optional
  "attachments"?: [ // Optional
    {
      "type"?:  // Optional
      {
      }
      "filename": string
      "file": string (uri)
      "conversation"?: string (uuid) // Optional
    }
  ]
  "canvas"?: { // Optional
  {
    "name": string
    "canvasType": 
    {
    }
    "title": string
    "content": string
  }
  }
  "queryMetadata"?: object // Optional
}

Request Example Value

{
  "conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
  "sender": {
    "id": 2.992461161002561e+38,
    "name": "jessiekuo",
    "avatar": "https://autox-media-dev.playma.app/static/images/default-user-avatar.png"
  },
  "type": "incoming",
  "content": "This is a test message",
  "contentPayload": {
    "content": "This is a test message",
    "items": [
      {
        "type": "text",
        "text": "This is a test message",
        "startTimestamp": null,
        "citations": []
      }
    ],
    "metadata": null
  },
  "feedback": "like",
  "createdAt": "1748314926000",
  "attachments": [],
  "citations": [],
  "citationNodes": [],
  "canvas": {
    "id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
    "name": "system-architecture-diagram",
    "canvasType": "markdown",
    "title": "System Architecture Diagram",
    "content": "```mermaid\ngraph TD\n    A[User] --> B[Frontend Interface]\n    B --> C[API Layer]\n    C --> D[Database]\n```",
    "createdAt": "1748314926000"
  }
}

Code Examples

Shell/Bash

# Call API Example (Shell)
curl -X POST "https://api.maiagent.ai/api/messages/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
    "sender": {
      "id": 2.992461161002561e+38,
      "name": "jessiekuo",
      "avatar": "https://autox-media-dev.playma.app/static/images/default-user-avatar.png"
    },
    "type": "incoming",
    "content": "This is a test message",
    "contentPayload": {
      "content": "This is a test message",
      "items": [
        {
          "type": "text",
          "text": "This is a test message",
          "startTimestamp": null,
          "citations": []
        }
      ],
      "metadata": null
    },
    "feedback": "like",
    "createdAt": "1748314926000",
    "attachments": [],
    "citations": [],
    "citationNodes": [],
    "canvas": {
      "id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
      "name": "system-architecture-diagram",
      "canvasType": "markdown",
      "title": "System Architecture Diagram",
      "content": "```mermaid\ngraph TD\n    A[User] --> B[Frontend Interface]\n    B --> C[API Layer]\n    C --> D[Database]\n```",
      "createdAt": "1748314926000"
    }
  }'

# 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 = {
    "conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
    "sender": {
      "id": 2.992461161002561e+38,
      "name": "jessiekuo",
      "avatar": "https://autox-media-dev.playma.app/static/images/default-user-avatar.png"
    },
    "type": "incoming",
    "content": "This is a test message",
    "contentPayload": {
      "content": "This is a test message",
      "items": [
        {
          "type": "text",
          "text": "This is a test message",
          "startTimestamp": null,
          "citations": []
        }
      ],
      "metadata": null
    },
    "feedback": "like",
    "createdAt": "1748314926000",
    "attachments": [],
    "citations": [],
    "citationNodes": [],
    "canvas": {
      "id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
      "name": "system-architecture-diagram",
      "canvasType": "markdown",
      "title": "System Architecture Diagram",
      "content": "```mermaid\ngraph TD\n    A[User] --> B[Frontend Interface]\n    B --> C[API Layer]\n    C --> D[Database]\n```",
      "createdAt": "1748314926000"
    }
  };

axios.post("https://api.maiagent.ai/api/messages/", data, config)
  .then(response => {
    console.log('Successfully received response:');
    console.log(response.data);
  })
  .catch(error => {
    console.error('An error occurred during the request:');
    console.error(error.response?.data || error.message);
  });

Python

import requests

url = "https://api.maiagent.ai/api/messages/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request payload
data = {
      "conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
      "sender": {
        "id": 2.992461161002561e+38,
        "name": "jessiekuo",
        "avatar": "https://autox-media-dev.playma.app/static/images/default-user-avatar.png"
      },
      "type": "incoming",
      "content": "This is a test message",
      "contentPayload": {
        "content": "This is a test message",
        "items": [
          {
            "type": "text",
            "text": "This is a test message",
            "startTimestamp": null,
            "citations": []
          }
        ],
        "metadata": null
      },
      "feedback": "like",
      "createdAt": "1748314926000",
      "attachments": [],
      "citations": [],
      "citationNodes": [],
      "canvas": {
        "id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
        "name": "system-architecture-diagram",
        "canvasType": "markdown",
        "title": "System Architecture Diagram",
        "content": "```mermaid\ngraph TD\n    A[User] --> B[Frontend Interface]\n    B --> C[API Layer]\n    C --> D[Database]\n```",
        "createdAt": "1748314926000"
      }
    }

response = requests.post(url, json=data, headers=headers)
try:
    print("Successfully received 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->post("https://api.maiagent.ai/api/messages/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
            "sender": {
                "id": 2.992461161002561e+38,
                "name": "jessiekuo",
                "avatar": "https://autox-media-dev.playma.app/static/images/default-user-avatar.png"
            },
            "type": "incoming",
            "content": "This is a test message",
            "contentPayload": {
                "content": "This is a test message",
                "items": [
                    {
                        "type": "text",
                        "text": "This is a test message",
                        "startTimestamp": null,
                        "citations": []
                    }
                ],
                "metadata": null
            },
            "feedback": "like",
            "createdAt": "1748314926000",
            "attachments": [],
            "citations": [],
            "citationNodes": [],
            "canvas": {
                "id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
                "name": "system-architecture-diagram",
                "canvasType": "markdown",
                "title": "System Architecture Diagram",
                "content": "```mermaid\ngraph TD\n    A[User] --> B[Frontend Interface]\n    B --> C[API Layer]\n    C --> D[Database]\n```",
                "createdAt": "1748314926000"
            }
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Successfully received response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>

Response Body

Status Code: 201

Response Schema Example

{
  "id": string (uuid)
  "conversation": string (uuid)
  "sender": 
  {
    "id": string (uuid)
    "name": string
    "avatar": string
    "email"?: string (email) // Optional
    "phoneNumber"?: string // Optional
  }
  "type"?: string // Optional
  "content"?: string // Optional
  "contentPayload"?: object // Optional
  "feedback": 
  {
    "id": string (uuid)
    "type": 
    {
    }
    "suggestion"?: string // Optional
    "updatedAt": string (timestamp)
  }
  "createdAt": string (timestamp)
  "attachments"?: [ // Optional
    {
      "id": string (uuid)
      "type"?:  // Optional
      {
      }
      "filename": string
      "file": string (uri)
      "conversation"?: string (uuid) // Optional
    }
  ]
  "citations": [
    {
      "id": string (uuid)
      "filename": string // File name
      "file": string (uri) // File to upload
      "fileType": string
      "knowledgeBase"?:  // Optional
      {
        "id": string (uuid)
        "name": string
      }
      "size": integer
      "status": 
      {
      }
      "parser": {
      {
        "id": string (uuid)
        "name": string
        "provider": 
        {
        }
        "order"?: integer // Optional
      }
      }
      "labels"?: [ // Optional
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // Optional
      "createdAt": string (timestamp)
    }
  ]
  "citationNodes": [
    {
      "chatbotTextNode": {
      {
        "id": string (uuid)
        "charactersCount": integer
        "hitsCount": integer
        "text": string
        "updatedAt": string (timestamp)
        "filename": string
        "chatbotFile": string (uuid)
        "pageNumber": integer
      }
      }
      "score"?: number (double) // Optional
      "displayScore": integer
    }
  ]
  "canvas"?: { // Optional
  {
    "id": string (uuid)
    "name": string
    "canvasType": 
    {
    }
    "title": string
    "content": string
    "createdAt": string (timestamp)
  }
  }
  "queryMetadata"?: object // Optional
}

Response Example Value

{
  "conversation": "c96a0fb9-d106-4b16-8706-3906533bafa2",
  "sender": {
    "id": 2.992461161002561e+38,
    "name": "jessiekuo",
    "avatar": "https://autox-media-dev.playma.app/static/images/default-user-avatar.png"
  },
  "type": "incoming",
  "content": "This is a test message",
  "contentPayload": {
    "content": "This is a test message",
    "items": [
      {
        "type": "text",
        "text": "This is a test message",
        "startTimestamp": null,
        "citations": []
      }
    ],
    "metadata": null
  },
  "feedback": "like",
  "createdAt": "1748314926000",
  "attachments": [],
  "citations": [],
  "citationNodes": [],
  "canvas": {
    "id": "034eecd7-e0f4-46e9-88cb-4fefdb5b7ddd",
    "name": "system-architecture-diagram",
    "canvasType": "markdown",
    "title": "System Architecture Diagram",
    "content": "```mermaid\ngraph TD\n    A[User] --> B[Frontend Interface]\n    B --> C[API Layer]\n    C --> D[Database]\n```",
    "createdAt": "1748314926000"
  }
}

---

Create a new conversation

POST /api/conversations/

Request Body

Parameters

Field	Type	Required	Description
webChat	string (uuid)	Yes

Request Structure Example

{
  "webChat": string (uuid)
}

Request Example Value

{
  "webChat": "550e8400-e29b-41d4-a716-446655440000"
}

Code Examples

Shell/Bash

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

# 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 = {
    "webChat": "550e8400-e29b-41d4-a716-446655440000"
  };

axios.post("https://api.maiagent.ai/api/conversations/", 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/conversations/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}

# Request payload
data = {
      "webChat": "550e8400-e29b-41d4-a716-446655440000"
    }

response = requests.post(url, json=data, headers=headers)
try:
    print("Successfully received 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 = $client->post("https://api.maiagent.ai/api/conversations/", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY',
            'Content-Type' => 'application/json'
        ],
        'json' => {
            "webChat": "550e8400-e29b-41d4-a716-446655440000"
        }
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Successfully received response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>

Response Body

Status Code: 201

Response Schema Example

{
  "id": string (uuid)
  "contact": { // Lightweight Contact Serializer for Conversation List view

Only includes fields necessary for the List view, removes inboxes and mcp_credentials
to avoid N+1 query issues
  {
    "id": string (uuid)
    "name": string
    "avatar"?: string (uri) // Optional
    "sourceId"?: string // Optional
  }
  }
  "inbox": {
  {
    "id": string (uuid)
    "name": string
    "channelType": string (enum: line, telegram, web, messenger) // * `line` - LINE
* `telegram` - Telegram
* `web` - Web
* `messenger` - Messenger
    "unreadConversationsCount"?: integer // Optional
    "signAuth"?:  // Optional
    {
      "id": string (uuid)
      "signSource": string (uuid)
      "signParams": {
      {
        "keycloak": 
        {
          "clientId": string
          "url": string
          "realm": string
        }
        "line": 
        {
          "liffId": string
        }
        "ad": 
        {
          "saml": string
        }
      }
      }
    }
  }
  }
  "title": string
  "lastMessage"?: { // Optional
  {
    "id": string (uuid)
    "type"?: string // Optional
    "content"?: string // Optional
    "contentPayload"?: object // Optional
    "feedback": 
    {
      "id": string (uuid)
      "type": 
      {
      }
      "suggestion"?: string // Optional
      "updatedAt": string (timestamp)
    }
    "createdAt": string (timestamp)
    "queryMetadata"?: object // Optional
  }
  }
  "lastMessageCreatedAt": string (timestamp)
  "unreadMessagesCount": integer
  "autoReplyEnabled": boolean
  "isAutoReplyNow": boolean
  "lastReadAt": string (timestamp)
  "createdAt": string (timestamp)
  "isGroupChat": boolean
  "enableGroupMention"?: boolean // Optional
  "enableLoadingAnimation"?: boolean // Optional
  "queryMetadata"?: object // Optional
  "toolMask"?: object // Records the enabled/disabled status of each tool {tool_id: bool} (Optional)
  "llm": string (uuid)
  "ipAddress": string
  "ipRecordedAt": string (timestamp)
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response String",
    "avatar": "https://example.com/file.jpg",
    "sourceId": "Response String"
  },
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response String",
    "channelType": "line",
    "unreadConversationsCount": 456,
    "signAuth": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "signSource": "550e8400-e29b-41d4-a716-446655440000",
      "signParams": {
        "keycloak": {
          "clientId": "Response String",
          "url": "Response String",
          "realm": "Response String"
        },
        "line": {
          "liffId": "Response String"
        },
        "ad": {
          "saml": "Response String"
        }
      }
    }
  },
  "title": "Response String",
  "lastMessage": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "Response String",
    "content": "Response String",
    "contentPayload": null,
    "feedback": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": {},
      "suggestion": "Response String",
      "updatedAt": "Response String"
    },
    "createdAt": "Response String",
    "queryMetadata": null
  },
  "lastMessageCreatedAt": "Response String",
  "unreadMessagesCount": 456,
  "autoReplyEnabled": false,
  "isAutoReplyNow": false,
  "lastReadAt": "Response String",
  "createdAt": "Response String",
  "isGroupChat": false,
  "enableGroupMention": false,
  "enableLoadingAnimation": false,
  "queryMetadata": null,
  "toolMask": null,
  "llm": "550e8400-e29b-41d4-a716-446655440000",
  "ipAddress": "Response String",
  "ipRecordedAt": "Response String"
}

---

Get Message List

GET /api/messages/

Parameters

Parameter Name	Required	Type	Description
conversation	✅	string	Conversation ID
cursor	❌	string	The pagination cursor value.
pageSize	❌	integer	Number of results to return per page.

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/messages/?conversation=example&cursor=example&pageSize=1" \
  -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/messages/?conversation=example&cursor=example&pageSize=1", 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/messages/?conversation=example&cursor=example&pageSize=1"
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 = $client->get("https://api.maiagent.ai/api/messages/?conversation=example&cursor=example&pageSize=1", [
        '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

{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "conversation": string (uuid)
      "sender": 
      {
        "id": string (uuid)
        "name": string
        "avatar": string
        "email"?: string (email) // Optional
        "phoneNumber"?: string // Optional
      }
      "type"?: string // Optional
      "content"?: string // Optional
      "contentPayload"?: object // Optional
      "feedback": 
      {
        "id": string (uuid)
        "type": 
        {
        }
        "suggestion"?: string // Optional
        "updatedAt": string (timestamp)
      }
      "createdAt": string (timestamp)
      "attachments"?: [ // Optional
        {
          "id": string (uuid)
          "type"?:  // Optional
          {
          }
          "filename": string
          "file": string (uri)
          "conversation"?: string (uuid) // Optional
        }
      ]
      "citations": [
        {
          "id": string (uuid)
          "filename": string // File name
          "file": string (uri) // File to upload
          "fileType": string
          "knowledgeBase"?:  // Optional
          {
            "id": string (uuid)
            "name": string
          }
          "size": integer
          "status": 
          {
          }
          "parser": {
          {
            "id": string (uuid)
            "name": string
            "provider": 
            {
            }
            "order"?: integer // Optional
          }
          }
          "labels"?: [ // Optional
            {
              "id": string (uuid)
              "name": string
            }
          ]
          "rawUserDefineMetadata"?: object // Optional
          "createdAt": string (timestamp)
        }
      ]
      "citationNodes": [
        {
          "chatbotTextNode": {
          {
            "id": string (uuid)
            "charactersCount": integer
            "hitsCount": integer
            "text": string
            "updatedAt": string (timestamp)
            "filename": string
            "chatbotFile": string (uuid)
            "pageNumber": integer
          }
          }
          "score"?: number (double) // Optional
          "displayScore": integer
        }
      ]
      "canvas"?: { // Optional
      {
        "id": string (uuid)
        "name": string
        "canvasType": 
        {
        }
        "title": string
        "content": string
        "createdAt": string (timestamp)
      }
      }
      "queryMetadata"?: object // Optional
    }
  ]
}

Response Example Value

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "conversation": "550e8400-e29b-41d4-a716-446655440000",
      "sender": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response String",
        "avatar": "Response String",
        "email": "[e-mail]",
        "phoneNumber": "Response String"
      },
      "type": "Response String",
      "content": "Response String",
      "contentPayload": null,
      "feedback": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": {},
        "suggestion": "Response String",
        "updatedAt": "Response String"
      },
      "createdAt": "Response String",
      "attachments": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": {},
          "filename": "Response String",
          "file": "https://example.com/file.jpg",
          "conversation": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "citations": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "filename": "Response String",
          "file": "https://example.com/file.jpg",
          "fileType": "Response String",
          "knowledgeBase": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response String"
          },
          "size": 456,
          "status": {},
          "parser": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "Response String",
            "provider": {},
            "order": 456
          },
          "labels": [
            {
              "id": "550e8400-e29b-41d4-a716-446655440000",
              "name": "Response String"
            }
          ],
          "rawUserDefineMetadata": null,
          "createdAt": "Response String"
        }
      ],
      "citationNodes": [
        {
          "chatbotTextNode": {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "charactersCount": 456,
            "hitsCount": 456,
            "text": "Response String",
            "updatedAt": "Response String",
            "filename": "Response String",
            "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
            "pageNumber": 456
          },
          "score": 456,
          "displayScore": 456
        }
      ],
      "canvas": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response String",
        "canvasType": {},
        "title": "Response String",
        "content": "Response String",
        "createdAt": "Response String"
      },
      "queryMetadata": null
    }
  ]
}

---

Get a specific message

GET /api/messages/{id}/

Parameters

Parameter Name	Required	Type	Description
id	✅	string	A UUID string identifying this message.
conversation	✅	string	Conversation ID

Code Examples

Shell/Bash

# Call API Example (Shell)
curl -X GET "https://api.maiagent.ai/api/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=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/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=example", 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/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=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 during the request:", e)

PHP

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

$client = new GuzzleHttp\Client();

try {
    $response = $client->get("https://api.maiagent.ai/api/messages/550e8400-e29b-41d4-a716-446655440000/?conversation=example", [
        '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)
  "conversation": string (uuid)
  "sender": 
  {
    "id": string (uuid)
    "name": string
    "avatar": string
    "email"?: string (email) // Optional
    "phoneNumber"?: string // Optional
  }
  "type"?: string // Optional
  "content"?: string // Optional
  "contentPayload"?: object // Optional
  "feedback": 
  {
    "id": string (uuid)
    "type": 
    {
    }
    "suggestion"?: string // Optional
    "updatedAt": string (timestamp)
  }
  "createdAt": string (timestamp)
  "attachments"?: [ // Optional
    {
      "id": string (uuid)
      "type"?:  // Optional
      {
      }
      "filename": string
      "file": string (uri)
      "conversation"?: string (uuid) // Optional
    }
  ]
  "citations": [
    {
      "id": string (uuid)
      "filename": string // File name
      "file": string (uri) // File to upload
      "fileType": string
      "knowledgeBase"?:  // Optional
      {
        "id": string (uuid)
        "name": string
      }
      "size": integer
      "status": 
      {
      }
      "parser": {
      {
        "id": string (uuid)
        "name": string
        "provider": 
        {
        }
        "order"?: integer // Optional
      }
      }
      "labels"?: [ // Optional
        {
          "id": string (uuid)
          "name": string
        }
      ]
      "rawUserDefineMetadata"?: object // Optional
      "createdAt": string (timestamp)
    }
  ]
  "citationNodes": [
    {
      "chatbotTextNode": {
      {
        "id": string (uuid)
        "charactersCount": integer
        "hitsCount": integer
        "text": string
        "updatedAt": string (timestamp)
        "filename": string
        "chatbotFile": string (uuid)
        "pageNumber": integer
      }
      }
      "score"?: number (double) // Optional
      "displayScore": integer
    }
  ]
  "canvas"?: { // Optional
  {
    "id": string (uuid)
    "name": string
    "canvasType": 
    {
    }
    "title": string
    "content": string
    "createdAt": string (timestamp)
  }
  }
  "queryMetadata"?: object // Optional
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "conversation": "550e8400-e29b-41d4-a716-446655440000",
  "sender": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response String",
    "avatar": "Response String",
    "email": "[e-mail]",
    "phoneNumber": "Response String"
  },
  "type": "Response String",
  "content": "Response String",
  "contentPayload": null,
  "feedback": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": {},
    "suggestion": "Response String",
    "updatedAt": "Response String"
  },
  "createdAt": "Response String",
  "attachments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": {},
      "filename": "Response String",
      "file": "https://example.com/file.jpg",
      "conversation": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "citations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "filename": "Response String",
      "file": "https://example.com/file.jpg",
      "fileType": "Response String",
      "knowledgeBase": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response String"
      },
      "size": 456,
      "status": {},
      "parser": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response String",
        "provider": {},
        "order": 456
      },
      "labels": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "name": "Response String"
        }
      ],
      "rawUserDefineMetadata": null,
      "createdAt": "Response String"
    }
  ],
  "citationNodes": [
    {
      "chatbotTextNode": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "charactersCount": 456,
        "hitsCount": 456,
        "text": "Response String",
        "updatedAt": "Response String",
        "filename": "Response String",
        "chatbotFile": "550e8400-e29b-41d4-a716-446655440000",
        "pageNumber": 456
      },
      "score": 456,
      "displayScore": 456
    }
  ],
  "canvas": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response String",
    "canvasType": {},
    "title": "Response String",
    "content": "Response String",
    "createdAt": "Response String"
  },
  "queryMetadata": null
}

---

Get Conversation List

GET /api/conversations/

Parameters

Parameter Name	Required	Type	Description
cursor	❌	string	The pagination cursor value.
inbox	✅	string	Conversation platform ID
keyword	❌	string	Keyword search
pageSize	❌	integer	Number of results to return per page.

Code Examples

Shell/Bash

# Call API Example (Shell)
curl -X GET "https://api.maiagent.ai/api/conversations/?cursor=example&inbox=example&keyword=example&pageSize=1" \
  -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/conversations/?cursor=example&inbox=example&keyword=example&pageSize=1", 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/conversations/?cursor=example&inbox=example&keyword=example&pageSize=1"
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 = $client->get("https://api.maiagent.ai/api/conversations/?cursor=example&inbox=example&keyword=example&pageSize=1", [
        '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 'An error occurred during the request: ' . $e->getMessage();
}
?>

Response Body

Status Code: 200

Response Schema Example

{
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "contact": { // Lightweight Contact Serializer, for Conversation List view

Only includes necessary fields for List view, removes inboxes and mcp_credentials
to avoid N+1 query issues
      {
        "id": string (uuid)
        "name": string
        "avatar"?: string (uri) // Optional
        "sourceId"?: string // Optional
      }
      }
      "inbox": {
      {
        "id": string (uuid)
        "name": string
        "channelType": string (enum: line, telegram, web, messenger) // * `line` - LINE
* `telegram` - Telegram
* `web` - Web
* `messenger` - Messenger
        "unreadConversationsCount"?: integer // Optional
        "signAuth"?:  // Optional
        {
          "id": string (uuid)
          "signSource": string (uuid)
          "signParams": {
          {
            "keycloak": 
            {
              "clientId": string
              "url": string
              "realm": string
            }
            "line": 
            {
              "liffId": string
            }
            "ad": 
            {
              "saml": string
            }
          }
          }
        }
      }
      }
      "title": string
      "lastMessage"?: { // Optional
      {
        "id": string (uuid)
        "type"?: string // Optional
        "content"?: string // Optional
        "contentPayload"?: object // Optional
        "feedback": 
        {
          "id": string (uuid)
          "type": 
          {
          }
          "suggestion"?: string // Optional
          "updatedAt": string (timestamp)
        }
        "createdAt": string (timestamp)
        "queryMetadata"?: object // Optional
      }
      }
      "lastMessageCreatedAt": string (timestamp)
      "unreadMessagesCount": integer
      "autoReplyEnabled": boolean
      "isAutoReplyNow": boolean
      "lastReadAt": string (timestamp)
      "createdAt": string (timestamp)
      "isGroupChat": boolean
      "enableGroupMention"?: boolean // Optional
      "enableLoadingAnimation"?: boolean // Optional
      "queryMetadata"?: object // Optional
      "toolMask"?: object // Records the enabled/disabled status of each tool {tool_id: bool} (Optional)
      "llm": string (uuid)
      "ipAddress": string
      "ipRecordedAt": string (timestamp)
    }
  ]
}

Response Example Value

{
  "next": "http://api.example.org/accounts/?cursor=cD00ODY%3D\"",
  "previous": "http://api.example.org/accounts/?cursor=cj0xJnA9NDg3",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "contact": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response String",
        "avatar": "https://example.com/file.jpg",
        "sourceId": "Response String"
      },
      "inbox": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response String",
        "channelType": "line",
        "unreadConversationsCount": 456,
        "signAuth": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "signSource": "550e8400-e29b-41d4-a716-446655440000",
          "signParams": {
            "keycloak": {
              "clientId": "Response String",
              "url": "Response String",
              "realm": "Response String"
            },
            "line": {
              "liffId": "Response String"
            },
            "ad": {
              "saml": "Response String"
            }
          }
        }
      },
      "title": "Response String",
      "lastMessage": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": "Response String",
        "content": "Response String",
        "contentPayload": null,
        "feedback": {
          "id": "550e8400-e29b-41d4-a716-446655440000",
          "type": {},
          "suggestion": "Response String",
          "updatedAt": "Response String"
        },
        "createdAt": "Response String",
        "queryMetadata": null
      },
      "lastMessageCreatedAt": "Response String",
      "unreadMessagesCount": 456,
      "autoReplyEnabled": false,
      "isAutoReplyNow": false,
      "lastReadAt": "Response String",
      "createdAt": "Response String",
      "isGroupChat": false,
      "enableGroupMention": false,
      "enableLoadingAnimation": false,
      "queryMetadata": null,
      "toolMask": null,
      "llm": "550e8400-e29b-41d4-a716-446655440000",
      "ipAddress": "Response String",
      "ipRecordedAt": "Response String"
    }
  ]
}

---

Get a specific conversation

GET /api/conversations/{id}/

Parameters

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

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/conversations/550e8400-e29b-41d4-a716-446655440000/" \
  -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/conversations/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/conversations/550e8400-e29b-41d4-a716-446655440000/"
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/conversations/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)
  "contact": { // Lightweight Contact Serializer for Conversation List view

Only includes fields necessary for the List view, removes inboxes and mcp_credentials
to avoid N+1 query issues
  {
    "id": string (uuid)
    "name": string
    "avatar"?: string (uri) // Optional
    "sourceId"?: string // Optional
  }
  }
  "inbox": {
  {
    "id": string (uuid)
    "name": string
    "channelType": string (enum: line, telegram, web, messenger) // * `line` - LINE
* `telegram` - Telegram
* `web` - Web
* `messenger` - Messenger
    "unreadConversationsCount"?: integer // Optional
    "signAuth"?:  // Optional
    {
      "id": string (uuid)
      "signSource": string (uuid)
      "signParams": {
      {
        "keycloak": 
        {
          "clientId": string
          "url": string
          "realm": string
        }
        "line": 
        {
          "liffId": string
        }
        "ad": 
        {
          "saml": string
        }
      }
      }
    }
  }
  }
  "title": string
  "lastMessage"?: { // Optional
  {
    "id": string (uuid)
    "type"?: string // Optional
    "content"?: string // Optional
    "contentPayload"?: object // Optional
    "feedback": 
    {
      "id": string (uuid)
      "type": 
      {
      }
      "suggestion"?: string // Optional
      "updatedAt": string (timestamp)
    }
    "createdAt": string (timestamp)
    "queryMetadata"?: object // Optional
  }
  }
  "lastMessageCreatedAt": string (timestamp)
  "unreadMessagesCount": integer
  "autoReplyEnabled": boolean
  "isAutoReplyNow": boolean
  "lastReadAt": string (timestamp)
  "createdAt": string (timestamp)
  "isGroupChat": boolean
  "enableGroupMention"?: boolean // Optional
  "enableLoadingAnimation"?: boolean // Optional
  "queryMetadata"?: object // Optional
  "toolMask"?: object // Records the enabled/disabled status of each tool {tool_id: bool} (Optional)
  "llm": string (uuid)
  "ipAddress": string
  "ipRecordedAt": string (timestamp)
}

Response Example Value

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contact": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string",
    "avatar": "https://example.com/file.jpg",
    "sourceId": "Response string"
  },
  "inbox": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Response string",
    "channelType": "line",
    "unreadConversationsCount": 456,
    "signAuth": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "signSource": "550e8400-e29b-41d4-a716-446655440000",
      "signParams": {
        "keycloak": {
          "clientId": "Response string",
          "url": "Response string",
          "realm": "Response string"
        },
        "line": {
          "liffId": "Response string"
        },
        "ad": {
          "saml": "Response string"
        }
      }
    }
  },
  "title": "Response string",
  "lastMessage": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "Response string",
    "content": "Response string",
    "contentPayload": null,
    "feedback": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": {},
      "suggestion": "Response string",
      "updatedAt": "Response string"
    },
    "createdAt": "Response string",
    "queryMetadata": null
  },
  "lastMessageCreatedAt": "Response string",
  "unreadMessagesCount": 456,
  "autoReplyEnabled": false,
  "isAutoReplyNow": false,
  "lastReadAt": "Response string",
  "createdAt": "Response string",
  "isGroupChat": false,
  "enableGroupMention": false,
  "enableLoadingAnimation": false,
  "queryMetadata": null,
  "toolMask": null,
  "llm": "550e8400-e29b-41d4-a716-446655440000",
  "ipAddress": "Response string",
  "ipRecordedAt": "Response string"
}

---

Get AI Assistant Conversation Records

GET /api/chatbots/{chatbotPk}/records/

Parameters

Parameter Name	Required	Type	Description
chatbotPk	✅	string	A UUID string identifying this Chatbot ID
botMessage	❌	string	Filter for bot replies containing specific content
endDate	✅	string	End date (required, format: YYYY-MM-DD, e.g., 2025-01-31)
page	❌	integer	A page number within the paginated result set.
pageSize	❌	integer	Number of results to return per page.
startDate	✅	string	Start date (required, format: YYYY-MM-DD, e.g., 2025-01-01)
userMessage	❌	string	Filter for user messages containing specific content

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/records/?botMessage=example&endDate=example&page=1&pageSize=1&startDate=example&userMessage=example" \
  -H "Authorization: Api-Key YOUR_API_KEY"

# Please replace YOUR_API_KEY and check 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/records/?botMessage=example&endDate=example&page=1&pageSize=1&startDate=example&userMessage=example", 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/records/?botMessage=example&endDate=example&page=1&pageSize=1&startDate=example&userMessage=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 during 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/records/?botMessage=example&endDate=example&page=1&pageSize=1&startDate=example&userMessage=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 'Request failed: ' . $e->getMessage();
}
?>

Response Body

Status Code: 200

Response Schema Example

{
  "count": integer
  "next"?: string (uri) // Optional
  "previous"?: string (uri) // Optional
  "results": [
    {
      "id": string (uuid)
      "senderName": string // Returns the name of the user message sender
      "feedback": 
      {
        "id": string (uuid)
        "type": 
        {
        }
        "suggestion"?: string // Optional
        "updatedAt": string (timestamp)
      }
      "inputMessage": string
      "condenseMessage": string // The user's message, refined after synthesizing chat history and context
      "outputMessage": string
      "faithfulnessScore": number (double) // Determines if the chatbot's response aligns with the database content and avoids hallucination
      "displayFaithfulnessScore": integer
      "answerRelevancyScore": number (double) // Determines if the chatbot's response is relevant to the user's question
      "displayAnswerRelevancyScore": integer
      "contextPrecisionScore": number (double) // Determines if the chatbot's response is relevant to the reference material
      "displayContextPrecisionScore": integer
      "answerCorrectnessScore": number (double) // Determines if the chatbot's response is correct (requires a ground truth answer)
      "displayAnswerCorrectnessScore": integer
      "answerSimilarityScore": number (double) // Determines if the chatbot's response is similar to the ground truth answer
      "displayAnswerSimilarityScore": integer
      "contextRecallScore": number (double) // Determines if the chatbot's response can recall relevant information from the reference material
      "displayContextRecallScore": integer
      "replyTime": string
      "createdAt": string (timestamp)
      "error": string // Stores error messages from the execution process
      "processingTime": object // Returns time statistics for each processing stage
      "usage": object // Returns usage statistics, including word count and token count
      "citationNodes": [
        {
          "id": string
          "text": string
        }
      ]
      "context": string
    }
  ]
}

Response Example Value

{
  "count": 123,
  "next": "http://api.example.org/accounts/?page=4",
  "previous": "http://api.example.org/accounts/?page=2",
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "senderName": "Response String",
      "feedback": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "type": {},
        "suggestion": "Response String",
        "updatedAt": "Response String"
      },
      "inputMessage": "Response String",
      "condenseMessage": "Response String",
      "outputMessage": "Response String",
      "faithfulnessScore": 456,
      "displayFaithfulnessScore": 456,
      "answerRelevancyScore": 456,
      "displayAnswerRelevancyScore": 456,
      "contextPrecisionScore": 456,
      "displayContextPrecisionScore": 456,
      "answerCorrectnessScore": 456,
      "displayAnswerCorrectnessScore": 456,
      "answerSimilarityScore": 456,
      "displayAnswerSimilarityScore": 456,
      "contextRecallScore": 456,
      "displayContextRecallScore": 456,
      "replyTime": "Response String",
      "createdAt": "Response String",
      "error": "Response String",
      "processingTime": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response Example Name",
        "description": "Response Example Description"
      },
      "usage": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Response Example Name",
        "description": "Response Example Description"
      },
      "citationNodes": [
        {
          "id": "Response String",
          "text": "Response String"
        }
      ],
      "context": "Response String"
    }
  ]
}

---

Export Chat Records as Excel File

GET /api/chatbots/{chatbotPk}/records/export-excel/

Parameters

Parameter Name	Required	Type	Description
chatbotPk	✅	string	A UUID string identifying this Chatbot ID
botMessage	❌	string	Filter bot messages containing specific content
endDate	✅	string	End date (Required, format: YYYY-MM-DD, e.g., 2025-01-31)
startDate	✅	string	Start date (Required, format: YYYY-MM-DD, e.g., 2025-01-01)
userMessage	❌	string	Filter user messages containing specific content

Code Examples

Shell/Bash

# API Call Example (Shell)
curl -X GET "https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/records/export-excel/?botMessage=example&endDate=example&startDate=example&userMessage=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/records/export-excel/?botMessage=example&endDate=example&startDate=example&userMessage=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/records/export-excel/?botMessage=example&endDate=example&startDate=example&userMessage=example"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY"
}


response = requests.get(url, headers=headers)
try:
    print("Successfully received 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 = $client->get("https://api.maiagent.ai/api/chatbots/550e8400-e29b-41d4-a716-446655440000/records/export-excel/?botMessage=example&endDate=example&startDate=example&userMessage=example", [
        'headers' => [
            'Authorization' => 'Api-Key YOUR_API_KEY'
        ]
    ]);
    
    $data = json_decode($response->getBody(), true);
    echo "Successfully got response:\n";
    print_r($data);
} catch (Exception $e) {
    echo 'Request failed: ' . $e->getMessage();
}
?>

Response Body

Status Code	Description
200	Excel file download

---