# Create Conversations and Messages

## Create Conversation

Create a new conversation.

**Endpoint:** [`https://api.maiagent.ai/api/v1/conversations`](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

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

**Request Example:**

```python
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.

```json
{
    "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:**

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

**Request Parameter Description:**

<table><thead><tr><th width="279">Parameter Name</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>conversation</td><td>string</td><td>Yes</td><td>Conversation unique identifier</td></tr><tr><td>content</td><td>string</td><td>Yes</td><td>Message content to send</td></tr><tr><td>attachments</td><td>array</td><td>No</td><td>Attachments array, defaults to empty array []</td></tr></tbody></table>

#### **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

```python
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

```bash
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

```json
{
    "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:**

```python
{
    "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**

<table><thead><tr><th width="209">Field Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>Message unique identifier (UUID)</td></tr><tr><td>conversation</td><td>string</td><td>Conversation unique identifier (UUID)</td></tr><tr><td>sender</td><td>object</td><td>Sender information object</td></tr><tr><td><a href="http://sender.id/">sender.id</a></td><td>number</td><td>Sender unique identifier</td></tr><tr><td><a href="http://sender.name/">sender.name</a></td><td>string</td><td>Sender name</td></tr><tr><td>sender.avatar</td><td>string</td><td>Sender avatar URL</td></tr><tr><td>type</td><td>string</td><td>Message type (incoming/outgoing)</td></tr><tr><td>content</td><td>string</td><td>Message content</td></tr><tr><td>feedback</td><td>object</td><td>null</td></tr><tr><td>createdAt</td><td>string</td><td>Message creation timestamp</td></tr><tr><td>attachments</td><td>array</td><td>Attachments list</td></tr><tr><td>citations</td><td>array</td><td>Citation sources list</td></tr><tr><td>citationNodes</td><td>array</td><td>Citation nodes list</td></tr></tbody></table>

### Message Type Description

* `incoming`: Received messages
* `outgoing`: Sent messages