会話とメッセージの作成

会話の作成

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

エンドポイント： https://api.maiagent.ai/api/v1/conversations

リクエストメソッド： POST

リクエストヘッダー：

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

リクエスト内容：

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

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

リクエスト例：

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 がどの会話内のものかを判別することもできます。

{
    "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

リクエスト内容：

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

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

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

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

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

リクエスト例：

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 例

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 の章をご参照ください

{
    "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": []                // 引用ノード配列
}

レスポンス例：

{
    "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": []
}

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

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

メッセージの種類の説明

• incoming: 受信したメッセージ

• outgoing: 送信したメッセージ