Create Conversations and Messages

Create Conversation

Create a new conversation.

Endpoint: https://api.maiagent.ai/api/v1/conversations

Request Method: POST

Request Headers:

Authorization: Api-Key <Your API Key>
Content-Type: application/json

Request Body:

Get "Web Chat ID" from the bottom of the "AI Assistant" details page

{
    "webChat": "String"  // Web Chat ID
}

Request Example:

import requests

response = requests.post(
    url='https://api.maiagent.ai/api/v1/conversations/',
    headers={
        'Authorization': 'Api-Key <Your API Key>'
    },
    json={
        'webChat': 'Your Web Chat ID'
    }
)

Response Body:

For message integration, you only need to record the "ID". The conversation "ID" can retrieve all messages in the conversation and can be used to identify which conversation the current message Webhook belongs to.

{
    "id": "string",                    // Conversation unique identifier, UUID format
    "contact": {
        "id": "string",                // Contact unique identifier, UUID format
        "name": "string",              // Contact name
        "avatar": "string",            // Avatar URL
        "createdAt": "string"          // Creation timestamp in milliseconds
    },
    "inbox": {
        "id": "string",                // Inbox unique identifier, UUID format
        "name": "string",              // Inbox name
        "channelType": "string"        // Channel type, e.g.: "web"
    },
    "title": "string",                 // Conversation title
    "lastMessage": null,               // Last message, can be null
    "lastMessageCreatedAt": "string",  // Last message creation timestamp
    "unreadMessagesCount": number,     // Unread message count
    "autoReplyEnabled": boolean,       // Whether auto-reply is enabled
    "isAutoReplyNow": boolean,         // Whether currently auto-replying
    "lastReadAt": null,                // Last read time, can be null
    "createdAt": "string"              // Conversation creation timestamp
}

---

Send Message

Create a new message

Endpoint: https://api.maiagent.ai/api/v1/messages/

Request Method: POST

Request Headers:

Authorization: Api-Key Your API Key
Content-Type: application/json

Request Body:

{
    "conversation": "string",   // Conversation ID, required
    "content": "string",        // Message content, required
    "attachments": [            // Attachments array, optional
        // List of attachment objects
    ]
}

Request Parameter Description:

Parameter Name	Type	Required	Description
conversation	string	Yes	Conversation unique identifier
content	string	Yes	Message content to send
attachments	array	No	Attachments array, defaults to empty array []

Attachment Object Field Description

Attachment Field	Type	Required	Description
id	string	Yes	Attachment unique identifier
type	string	Yes	Attachment type
filename	string	Yes	Attachment filename
file	string	Yes	Attachment URL

Request Examples:

Python Example

import requests

response = requests.post(
    url='<https://api.maiagent.ai/api/v1/messages/>',
    headers={
        'Authorization': 'Api-Key Your API Key'
    },
    json={
        'conversation': 'Conversation ID',
        'content': 'Message content',
        'attachments': [
            {
                "id": "Attachment ID",
                "type": "Attachment type",
                "filename": "Attachment filename",
                "file": "Attachment file URL"
            }
        ]
    }
)

cURL Example

curl -X POST '<https://api.maiagent.ai/api/v1/messages/>' \\
-H 'Authorization: Api-Key Your API Key' \\
-H 'Content-Type: application/json' \\
-d '{
    "conversation": "Conversation ID",
    "content": "Message content",
    "attachments": [
        {
            "id": "Attachment ID",
            "type": "Attachment type", 
            "filename": "Attachment filename",
            "file": "Attachment file URL"
        }
    ]
}'

Response Format:

Receiving a response indicates successful message creation. Reply messages will be provided via Webhook, please refer to the Webhook section

{
    "id": "string",                    // Message unique identifier, UUID format
    "conversation": "string",          // Conversation unique identifier, UUID format
    "sender": {
        "id": number,                  // Sender ID
        "name": "string",              // Sender name
        "avatar": "string"             // Sender avatar URL
    },
    "type": "string",                  // Message type, e.g.: "incoming"
    "content": "string",               // Message content
    "feedback": null,                  // Message feedback, can be null
    "createdAt": "string",             // Creation timestamp in milliseconds
    "attachments": [],                 // Attachments array
    "citations": [],                   // Citation sources array
    "citationNodes": []                // Citation nodes array
}

Response Example:

{
    "id": "2491074a-6d23-4289-af45-caa12531420e",
    "conversation": "8e44604a-8278-4c96-96b5-3e5a0548d738",
    "sender": {
        "id": 324816370485542537671391323877394598747,
        "name": "AI Assistant",
        "avatar": "https://whizchat-media-prod-django.playma.app/media/users/user/bb5f49ef-31ae-4ccf-bc0e-6fe8c5001721.png"
    },
    "type": "incoming",
    "content": "Hello",
    "feedback": null,
    "createdAt": "1732495353000",
    "attachments": [],
    "citations": [],
    "citationNodes": []
}

Response Field Description

Field Name	Type	Description
id	string	Message unique identifier (UUID)
conversation	string	Conversation unique identifier (UUID)
sender	object	Sender information object
sender.id	number	Sender unique identifier
sender.name	string	Sender name
sender.avatar	string	Sender avatar URL
type	string	Message type (incoming/outgoing)
content	string	Message content
feedback	object	null
createdAt	string	Message creation timestamp
attachments	array	Attachments list
citations	array	Citation sources list
citationNodes	array	Citation nodes list

Message Type Description

• incoming: Received messages

• outgoing: Sent messages