> 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/ja/api-integration/conversations-and-messages.md). # 対話とメッセージの作成 API で会話を作成してメッセージを送信し、Webhook で Agent の返信を受信する連携フローです。フィールドの定義は API ドキュメントを参照してください。 API による会話の連携は、まず会話を作成して会話 ID を取得し、その会話にメッセージを送信するという 2 つのステップで行います。Agent の返信は Webhook で送信されます。このページではフローと注意事項を説明します。各フィールドの型と必須条件は API ドキュメントに従ってください。 ## 会話の作成 新しい会話を作成します。 **エンドポイント：** `https://api.maiagent.ai/api/v1/conversations/` **リクエストメソッド：** `POST` **リクエストヘッダー：** ``` Authorization: Api-Key <ご利用の API キー> Content-Type: application/json ``` **リクエスト内容：** `webChat` は必須です（Web Chat ID：管理画面の カスタマーサポートの会話 → 会話プラットフォーム → 該当 Agent の API プラットフォームを編集 → 連携とログイン → Webhook 設定 の最下部にある API 情報 カードからコピーします。ユーザーマニュアルの[会話プラットフォームの基本設定](https://docs.maiagent.ai/build/conversation-settings/platform-settings/basic-settings#web-chat-id)を参照してください。`GET /api/v1/web-chats/` でも取得できます）。会話を特定の訪問者に紐付ける場合は、`contact` も指定します（連絡先 ID。同じ会話プラットフォームに属している必要があります。取得方法は[連絡先の ID 情報の同期とトークン更新](/tech/ja/serve/contacts/contact-credentials-sync.md)を参照してください）。`contact` を指定しない場合、会話の連絡先は API キーを所有するユーザーとなり、同じキーで作成した会話はすべてこの連絡先に紐付きます。フィールドの定義は API ドキュメントの[新しい会話の作成](https://docs.maiagent.ai/api/api-reference/dui-hua-he-xun-xi#conversations-create)を参照してください。 **リクエスト例：** ```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）を保存してください。会話内のすべてのメッセージを取得する場合や、メッセージの Webhook がどの会話に属するかを識別する場合に、この ID を使用します。Webhook の設定に必要な会話プラットフォーム ID は `inbox.id` にあります。レスポンスのフィールドは API ドキュメントの[新しい会話の作成](https://docs.maiagent.ai/api/api-reference/dui-hua-he-xun-xi#conversations-create)を参照してください。 *** ## メッセージの送信 新しいメッセージを作成します **エンドポイント：** `https://api.maiagent.ai/api/v1/messages/` **リクエストメソッド：** `POST` **リクエストヘッダー：** ``` Authorization: Api-Key ご利用の API キー Content-Type: application/json ``` **リクエスト内容：** `conversation`（会話 ID）は必須です。メッセージのテキストは `content` に、添付ファイルは `attachments`（デフォルトは空の配列）に指定します。フィールドの定義は API ドキュメントの[メッセージの送信（作成）](https://docs.maiagent.ai/api/api-reference/dui-hua-he-xun-xi#messages-create)を参照してください。 添付ファイルのオブジェクトは事前に作成してから指定する必要があります。作成方法は [Presigned ファイルアップロード方式：メッセージ添付ファイルの作成](/tech/ja/api-integration/api_knowledge.md#message-attachments)を参照してください。添付ファイルの作成時に返されたオブジェクト（`type`、`filename`、`file`）をそのまま `attachments` に入れます。 **リクエスト例：** 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" } ] }' ``` **レスポンス形式：** レスポンスを受信すると、メッセージの作成が成功したことを示します。レスポンスには作成したメッセージが含まれますが、Agent の返信は含まれません。返信は Webhook で送信されます。[Webhook](/tech/ja/serve/webhook.md)を参照してください。レスポンスのフィールドは API ドキュメントの[メッセージの送信（作成）](https://docs.maiagent.ai/api/api-reference/dui-hua-he-xun-xi#messages-create)を参照してください。 **レスポンス例：** ```json { "id": "2491074a-6d23-4289-af45-caa12531420e", "conversation": "8e44604a-8278-4c96-96b5-3e5a0548d738", "sender": { "id": "f45d5b80-d44a-416e-885a-d720e2f7cb5b", "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": [] } ``` ### メッセージの種類 * `incoming`: 受信したメッセージです * `outgoing`: 送信したメッセージです ### メッセージ内容の画像 `content` はプレーンテキストです。プラットフォームはそのまま保存し、含まれる URL を解析しません。会話に画像を表示する方法は 2 つあります。 | 方法 | 用途 | 説明 | | --------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `attachments` | ユーザーが Agent の画像認識用に画像をアップロードし、ファイルとして保存する場合です | プラットフォームが保存と有効期限の管理を行う、正式にサポートされている方法です。作成方法は [Presigned ファイルアップロード方式](/tech/ja/api-integration/api_knowledge.md#message-attachments)を参照してください | | Markdown の画像構文 `![説明](https://…)` | Agent の返信やツールの結果で外部画像を「表示」する場合です | Web Chat と MaiGPT はメッセージを Markdown で描画します。ブラウザーがその URL から直接画像を取得し、URL（クエリ文字列を含む）はそのまま保持されます | Markdown の画像を使用する際は、以下の点に注意してください。 * 画像は**ユーザーのブラウザー**が読み込みます。URL は認証なしでインターネットからアクセスできる必要があります。プラットフォームが代わりにダウンロードしたり、コピーを保存したりすることはありません。 * 署名付きで有効期限のある URL（Azure SAS、S3 presigned など）は、メッセージに記載した後は更新されません。期限が切れると、過去のメッセージ内の画像を表示できなくなります。長期間閲覧できるようにするには、期限のない URL を提供するか、ご利用のシステムで固定 URL を提供してリダイレクトしてください。 * Markdown 構文を使用し、HTML タグに依存しないでください。HTML の処理はフロントエンドのレンダラーによって異なり、契約の対象外です。 * レスポンスの引用ノードにある `imageUrl` はナレッジベースの段落の画像であり、メッセージ内容の画像とは関係ありません。 * カスタム API ツールが画像 URL を返す際の 2 段階のフローは、[API ツールエンジニアリングガイド：モデルへのレスポンスの返し方](/tech/ja/api-integration/api-tool-engineering-guide.md#response-to-model)を参照してください。 *** ## メッセージのフィードバック メッセージのレスポンスにある `feedback` は読み取り専用です。フィードバックがない場合は `null`、ある場合は `{"id": "…", "type": "like", "suggestion": "…", "updatedAt": "…"}` というオブジェクトになります。メッセージ作成リクエストは `feedback` を受け付けません。AI の返信に高評価または低評価を付けるには、専用のエンドポイントを使用します。 ```http POST /api/v1/messages/{messagePk}/feedback/ Authorization: Api-Key <ご利用の API キー> Content-Type: application/json {"type": "dislike", "suggestion": "回答に返品期限が記載されていません"} ``` * `type` は必須で、`like` または `dislike` のみを受け付けます。`suggestion` は任意で、空の文字列も指定できます。 * 更新には `PATCH /api/v1/messages/{messagePk}/feedback/{id}/`、取り消しには `DELETE` を使用します。`{id}` はフィードバックオブジェクトの `id` です。 * フィードバックは AgentOps の会話記録に表示されます。フィールドは API ドキュメントの[メッセージのフィードバックの作成](https://docs.maiagent.ai/api/api-reference/dui-hua-he-xun-xi#messages-feedback-create)を参照してください。 ## 会話の削除 `DELETE /api/v1/conversations/{id}/` は通常の会話を削除し、成功すると `204` を返します。これは論理削除です。会話は一覧と検索結果から消え、継続できなくなりますが、プラットフォームは監査用にデータを保持します。会話の添付ファイルも削除する場合は、別途[会話添付ファイル管理 API](/tech/ja/api-integration/endpoint-behaviors/conversation-attachments.md)を呼び出してください。API ドキュメントの[会話の削除](https://docs.maiagent.ai/api/api-reference/dui-hua-he-xun-xi#conversations-destroy)を参照してください。 ### 引用ノードのページ番号フィールド Agent の返信の `citationNodes[]` の各要素には、`chatbotTextNode`（引用された段落）が含まれます。そのページ番号フィールドは以下のとおりです。 | フィールド | 意味 | | --------------------- | ------------------------------------------------------------------------ | | `pageStart`、`pageEnd` | 元のドキュメント内での段落の開始ページと終了ページです。**1 から数えます**。段落が複数ページにまたがらない場合は、両方とも同じ値になります | | `pageNumber` | `pageStart` と同じ値です。既存の連携との互換性のために保持されています | ページ番号が付くのは、パーサーが実際のページに対応付けられるドキュメント（主に PDF、および PDF として解析される Office ドキュメント）のみです。`.txt`、`.md`、CSV／Excel、HTML、クローラーで取り込んだ Web ページ、音声の文字起こしなど、ページ区切りのないソースでは、この 3 つのフィールドはすべて `null` になります（フィールドは省略されず、常に含まれます）。引用を表示する際は、まず `null` かどうかを確認してから「N ページ」というテキストや `#page=N` を付けたファイルリンクを作成してください。[ナレッジベース検索 API](/tech/ja/api-integration/knowledge-base-api.md#search-response) が返す段落にも、同じフィールドとルールが適用されます。 --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.maiagent.ai/tech/ja/api-integration/conversations-and-messages.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.