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:

The "Web Chat ID" should be obtained from the bottom of the AI assistant detail 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:

If used for integrating messages, simply record the "ID". The conversation "ID" can retrieve all messages in the conversation and can be used to know which conversation a message webhook belongs to via the "conversation ID."

{
    "id": "string",                    // Unique conversation identifier, UUID format
    "contact": {
        "id": "string",                // Unique contact identifier, UUID format
        "name": "string",              // Contact name
        "avatar": "string",            // Avatar URL
        "createdAt": "string"          // Creation timestamp, in milliseconds
    },
    "inbox": {
        "id": "string",                // Unique inbox identifier, UUID format
        "name": "string",              // Inbox name
        "channelType": "string"        // Channel type, e.g.: "web"
    },
    "title": "string",                 // Conversation title
    "lastMessage": null,               // Last message, may be null
    "lastMessageCreatedAt": "string",  // Last message creation timestamp
    "unreadMessagesCount": number,     // Unread messages count
    "autoReplyEnabled": boolean,       // Whether auto-reply is enabled
    "isAutoReplyNow": boolean,         // Whether auto-reply is currently active
    "lastReadAt": null,                // Last read time, may 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 explanations:

Parameter name	Type	Required	Description
conversation	string	Yes	Unique identifier of the conversation
content	string	Yes	The message content to send
attachments	array	No	Attachments array, defaults to an empty array []

Attachment object field descriptions

Attachment field name	Type	Required	Description
id	string	Yes	Unique identifier of the attachment
type	string	Yes	Type of the attachment
filename	string	Yes	Filename of the attachment
file	string	Yes	URL of the attachment

Request example:

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": "URL of the attachment file"
            }
        ]
    }
)

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": "URL of the attachment file"
        }
    ]
}'

Response format:

Receiving a response means the message was created successfully. The created message will be provided via Webhook; please refer to the Webhook section.

{
    "id": "string",                    // Unique message identifier, UUID format
    "conversation": "string",          // Unique conversation 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, may be null
    "createdAt": "string",             // Creation timestamp, in milliseconds
    "attachments": [],                 // Attachments array
    "citations": [],                   // Citations array
    "citationNodes": []                // Citation nodes array
}

Response example:

{
    "id": "2491074a-6d23-4289-af45-caa12531420e",
    "conversation": "8e44604a-8278-4c96-96b5-3e5a0548d738",
    "sender": {
        "id": 324816370485542537671391323877394598747,
        "name": "AI Intelligent Customer Service",
        "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 descriptions

Field name	Type	Description
id	string	Unique message identifier (UUID)
conversation	string	Unique conversation identifier (UUID)
sender	object	Sender information object
sender.id	number	Unique sender 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	List of attachments
citations	array	List of citation source documents
citationNodes	array	List of citation source nodes

Message type descriptions

• incoming: Received message

• outgoing: Sent message