> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/tech/maiagent-tech-ja/api-integration/dui-hua-yu-xun-xi.md).

# 会話とメッセージの作成

## 会話の作成

新しい会話を作成します。

**エンドポイント：** [`https://api.maiagent.ai/api/v1/conversations`](https://api.maiagent.ai/api/v1/conversations/)

**リクエストメソッド：** `POST`

**リクエストヘッダー：**

```
Authorization: Api-Key <お客様のAPIキー>
Content-Type: application/json
```

**リクエスト内容：**

「Web Chat ID」は「AIアシスタント」の詳細ページ最下部から取得してください

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

**リクエスト例：**

```python
import requests

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

**レスポンス内容：**

メッセージ連携に使用する場合は、「ID」を控えておくだけで十分です。会話「ID」を使用すると、その会話内のすべてのメッセージを取得できるほか、「会話 ID」によって現在のメッセージ Webhook がどの会話内のものかを判別することもできます。

```json
{
    "id": "string",                    // 会話の一意の識別子、UUID 形式
    "contact": {
        "id": "string",                // 連絡先の一意の識別子、UUID 形式
        "name": "string",              // 連絡先の名前
        "avatar": "string",            // プロフィール画像の URL
        "createdAt": "string"          // 作成タイムスタンプ、ミリ秒単位
    },
    "inbox": {
        "id": "string",                // 受信トレイの一意の識別子、UUID 形式
        "name": "string",              // 受信トレイの名前
        "channelType": "string"        // チャネルの種類、例："web"
    },
    "title": "string",                 // 会話のタイトル
    "lastMessage": null,               // 最後のメッセージ、null の場合あり
    "lastMessageCreatedAt": "string",  // 最後のメッセージの作成タイムスタンプ
    "unreadMessagesCount": number,     // 未読メッセージ数
    "autoReplyEnabled": boolean,       // 自動返信が有効かどうか
    "isAutoReplyNow": boolean,         // 現在自動返信中かどうか
    "lastReadAt": null,                // 最終既読時刻、null の場合あり
    "createdAt": "string"              // 会話の作成タイムスタンプ
}
```

***

## メッセージの送信

新しいメッセージを作成します

**エンドポイント：** `https://api.maiagent.ai/api/v1/messages/`

**リクエストメソッド：** `POST`

**リクエストヘッダー：**

```
Authorization: Api-Key お客様のAPIキー
Content-Type: application/json
```

**リクエスト内容：**

```json
{
    "conversation": "string",   // 会話 ID、必須
    "content": "string",        // メッセージ内容、必須
    "attachments": [            // 添付ファイル配列、任意
        // 添付ファイルオブジェクトのリスト
    ]
}
```

**リクエストパラメータの説明：**

<table><thead><tr><th width="279">パラメータ名</th><th>種類</th><th>必須</th><th>説明</th></tr></thead><tbody><tr><td>conversation</td><td>string</td><td>はい</td><td>会話の一意の識別子</td></tr><tr><td>content</td><td>string</td><td>はい</td><td>送信するメッセージの内容</td></tr><tr><td>attachments</td><td>array</td><td>いいえ</td><td>添付ファイル配列、デフォルトは空の配列 []</td></tr></tbody></table>

#### **添付ファイルオブジェクトのフィールド説明**

| 添付ファイルのフィールド名 | 種類     | 必須 | 説明            |
| ------------- | ------ | -- | ------------- |
| id            | string | はい | 添付ファイルの一意の識別子 |
| type          | string | はい | 添付ファイルの種類     |
| filename      | string | はい | 添付ファイルのファイル名  |
| file          | string | はい | 添付ファイルのURL    |

**リクエスト例：**

Python 例

```python
import requests

response = requests.post(
    url='<https://api.maiagent.ai/api/v1/messages/>',
    headers={
        'Authorization': 'Api-Key お客様のAPIキー'
    },
    json={
        'conversation': '会話ID',
        'content': 'メッセージ内容',
        'attachments': [
            {
                "id": "添付ファイルID",
                "type": "添付ファイルの種類",
                "filename": "添付ファイル名",
                "file": "添付ファイルの URL"
            }
        ]
    }
)

```

cURL 例

```bash
curl -X POST '<https://api.maiagent.ai/api/v1/messages/>' \\
-H 'Authorization: Api-Key お客様のAPIキー' \\
-H 'Content-Type: application/json' \\
-d '{
    "conversation": "会話ID",
    "content": "メッセージ内容",
    "attachments": [
        {
            "id": "添付ファイルID",
            "type": "添付ファイルの種類",
            "filename": "添付ファイル名",
            "file": "添付ファイルの URL"
        }
    ]
}'

```

**レスポンス形式：**

レスポンスを受信した場合、メッセージが正常に作成されたことを意味します。返信メッセージは Webhook 形式で提供されますので、Webhook の章をご参照ください

```json
{
    "id": "string",                    // メッセージの一意の識別子、UUID 形式
    "conversation": "string",          // 会話の一意の識別子、UUID 形式
    "sender": {
        "id": number,                  // 送信者 ID
        "name": "string",              // 送信者名
        "avatar": "string"             // 送信者のアバター URL
    },
    "type": "string",                  // メッセージの種類、例："incoming"
    "content": "string",               // メッセージ内容
    "feedback": null,                  // メッセージのフィードバック、null の場合あり
    "createdAt": "string",             // 作成タイムスタンプ、ミリ秒単位
    "attachments": [],                 // 添付ファイル配列
    "citations": [],                   // 引用元配列
    "citationNodes": []                // 引用ノード配列
}

```

**レスポンス例：**

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

**レスポンスフィールドの説明**

<table><thead><tr><th width="209">フィールド名</th><th>種類</th><th>説明</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>メッセージの一意の識別子 (UUID)</td></tr><tr><td>conversation</td><td>string</td><td>会話の一意の識別子 (UUID)</td></tr><tr><td>sender</td><td>object</td><td>送信者情報オブジェクト</td></tr><tr><td><a href="http://sender.id/">sender.id</a></td><td>number</td><td>送信者の一意の識別子</td></tr><tr><td><a href="http://sender.name/">sender.name</a></td><td>string</td><td>送信者名</td></tr><tr><td>sender.avatar</td><td>string</td><td>送信者のアバター URL</td></tr><tr><td>type</td><td>string</td><td>メッセージの種類 (incoming/outgoing)</td></tr><tr><td>content</td><td>string</td><td>メッセージ内容</td></tr><tr><td>feedback</td><td>object</td><td>null</td></tr><tr><td>createdAt</td><td>string</td><td>メッセージの作成タイムスタンプ</td></tr><tr><td>attachments</td><td>array</td><td>添付ファイルのリスト</td></tr><tr><td>citations</td><td>array</td><td>引用元ドキュメントのリスト</td></tr><tr><td>citationNodes</td><td>array</td><td>引用元ノードのリスト</td></tr></tbody></table>

### メッセージの種類の説明

* `incoming`: 受信したメッセージ
* `outgoing`: 送信したメッセージ


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.maiagent.ai/tech/maiagent-tech-ja/api-integration/dui-hua-yu-xun-xi.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.