連絡先（Contact）の紹介と連携

コンタクトとは？

コンタクト（Contact）は「AI アシスタントと対話するエンドユーザー」を表します。企業が自社システムのユーザーを MaiAgent のコンタクトに紐付けることで、AI は「誰が質問しているか」を識別できるようになります。これにより、その人の対話履歴と権限設定を正しく参照でき、他のユーザーのものと混同することがありません。

コンタクトは MaiAgent のアカウントを必要としません（これがメンバー／ロールとの最大の違いです）。ユーザーがその存在を意識することもありません——コンタクトは、お客様のシステムと MaiAgent の間の ID マッピングです。

コンタクトに紐付けられる情報

データ

用途

詳細説明

基本情報（name、email、avatar）

管理画面のコンタクト一覧と対話履歴に表示されます

本ページ下部の API 説明

カスタム属性（metadata）

部署、会員ランクなどの背景情報。AI が読み取り、回答に反映します

コンタクト ID 同期と Token 更新

クエリメタデータ（query_metadata）

該当ユーザーが検索可能なナレッジベース／ドキュメント／タグの範囲を制限します

ナレッジ管理権限（Query Metadata）

MCP／API ツール認証情報

AI が該当ユーザーの ID と権限で外部ツールを呼び出せるようにします

コンタクト ID 同期と Token 更新

対話履歴

デバイスをまたいで対話を継続できます

フロントエンドで contactId を渡すだけで有効になります

コンタクトの作成・同期方法は 3 通り

方法

適したケース

説明

ID 同期 API（setup-contact-credentials）

ユーザーログイン時の同期、ツール認証情報のバインド、既存システムからの一括補完作成

冪等（同一 sourceId で重複作成されません）、API Key 不要。Web Chat フロントエンドの auth が自動呼び出しするバージョンも含まれます。ほとんどの連携シナリオではこの方法を推奨します。詳細はコンタクト ID 同期と Token 更新をご覧ください

コンタクト API（POST /api/v1/contacts/）

バックエンドでコンタクトのライフサイクルを完全に制御したい場合、作成時に query_metadata を設定する必要がある場合

API Key が必要です。更新には PATCH /api/v1/contacts/{contact_id}/ を使用します（送信されたフィールドのみ更新されます）。スキーマは API ドキュメント-コンタクトをご参照ください

一括インポート（Excel）

既存システムとの初回連携時に、大量のユーザーを一括で補完作成する場合

上限 10,000 行。query_metadata と API ツール認証情報を同時に設定できます。下記の説明をご覧ください

管理画面（GUI）

少量のコンタクトを手動で管理する場合

下記の操作説明をご覧ください

4 通りの方法で作成されるコンタクトは同一のものであり、併用が可能です（例：初回連携時は一括インポート、日常のログイン時は ID 同期 API を使用）。

連携フロー

3 つのステップ：

対応を確認：企業システムの user ID で会員情報を検索し、MaiAgent の contact_id が既に存在するかを確認します
作成または更新：存在しなければ作成し（contact_id を保存）、ユーザーが氏名／Email を変更した場合や権限が変更された場合は、コンタクト情報を同期更新します（PATCH /api/v1/contacts/{contact_id}/）。これにより、以降の対話でのパーソナライズされたコンテンツと権限が正確に反映されます
Web Chat を初期化：フロントエンドの config に contactId を設定します。詳細は Web Chat 埋め込みと SDK をご覧ください

「ユーザーが企業システムにログインする際に、コンタクトを同期作成し Token 認証情報を更新する」シナリオ（例：AI がユーザーの権限で MCP ツールを呼び出す場合）については、コンタクト ID 同期と Token 更新をご参照ください。1 回の呼び出しでコンタクトの作成と認証情報のバインドを同時に完了できます。

コンタクトの一括インポート（Excel）

既存システムとの初回連携時に、Excel で大量のコンタクトを一括作成（または更新）できます：

テンプレートのダウンロード

GET /api/v1/contacts/bulk-import-template/ で Excel テンプレート（ヘッダー行とサンプル行を含む）をダウンロードします。

データの入力

フィールド

必須

説明

Name(required)

✅

コンタクトの表示名

Email(required)

✅

マッチングキーの一つ（大文字・小文字を区別しません）

Phone Number

電話番号

Source ID(required)

✅

企業システムのユーザー識別コード、マッチングキーの一つ。推測困難な値を使用してください（ID 同期 API のセキュリティに関する注意事項と同様）

Query Metadata

JSON オブジェクト。コンタクトのナレッジ検索範囲に書き込まれます。空白セル＝既存の値を保持。フォーマットは JSON フォーマットガイドをご参照ください

API Credentials

JSON 配列 [{"tool": "<ツール ID>", "headers": {...}}]。API ツール認証情報をバインドします。空白＝既存の認証情報を保持

アップロードしてインポート

POST /api/v1/contacts/bulk-import/（multipart/form-data、Authorization: Api-Key 認証、コンタクト API と同様）：

file：入力済みの .xlsx（上限 10 MB、10,000 行）
inboxes：受信トレイの UUID リスト——インポートされる各コンタクトの受信トレイセットは、このリストで丸ごと置き換えられます。その後 Web Chat のログイン同期を行う場合は、対応する Web Chat の受信トレイが含まれていることを確認してください

レスポンス：{ "created": N, "updated": M }

インポートのマッチングと更新ルール：

（Source ID、Email）をキーとして upsert を実行します。既存のコンタクトに一致した場合は氏名／電話番号／Query Metadata を更新し（空白セルは変更しません）、一致しなかった場合は新規作成します
API Credentials は（コンタクト、ツール）をキーとして upsert を実行します。ファイルに記載されていないツールの認証情報は影響を受けません
全件が同一トランザクション内で処理されます。いずれかの行にフォーマットエラー（フィールド名の不一致、不正な JSON など）がある場合、全件が書き込まれず、エラーメッセージに行番号が表示されます

インポートでは対応関係と属性のみが作成されます。ユーザーの Token 認証情報は、ログインフローの ID 同期 API によって毎回のログイン時に更新されます。

GUI でのコンタクト作成

コンタクト管理画面に移動します

コンタクトを追加をクリックします

クリックすると以下のページが表示されます：

コンタクト名を入力し、対話プラットフォームを指定すると作成できます。作成後、コピーボタンをクリックしてコンタクト ID（Web Chat の初期化パラメータ contactId）を取得できます。

コンタクトに設定された ID 情報は、クエリ時に対応する query_metadata の条件の組み合わせを生成するために使用されます。

👉 Query Metadata について詳しく見る

実装に関する推奨事項

会員情報テーブルに対応フィールドを追加します（例：maiagent_contact_id、UUID、nullable）。作成／更新日時とともに記録し、企業の user ID と Contact ID の対応関係を追跡可能にします
冪等性を実装します：作成前に対応関係を確認するか、ID 同期 API を直接使用してください（sourceId による冪等性があり、再実行しても重複コンタクトは作成されません）
API 呼び出しログを記録します。対応関係の異常を調査する際に役立ちます
非同期呼び出し：コンタクト関連の API はログインフローの他のリクエストと並行して実行します。失敗してもユーザーのログインをブロックせず、次回のログイン時にリトライします

前へソフトウェアベンダー統合ガイド（エンドツーエンド）

次へコンタクト ID 同期とトークン更新

最終更新 14 日前

役に立ちましたか？