Ctrlk
註冊/登入
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

コンタクトとは？

基本的な定義

コンタクト（Contact）は MaiAgent における重要な情報の担い手であり、企業が顧客データを MaiAgent サービスと同期させることを可能にします。これにより、正確な権限管理とパーソナライズされたサービスを実現し、個別化された対話サービスを確保します。

コンタクトの動作の仕組みは以下の図のとおりです。

MaiAgent は、当該顧客の MaiAgent 内における企業の顧客データに対応したコンタクト情報（Contact）を通じて、MaiAgent API を連携する際に対応するコンタクト ID を受け渡すことで、その消費者に関する過去の記憶情報や権限管理の内容を正しく遡って参照できます。これにより、他の消費者の無関係な情報や権限設定が参照されることはありません。

コンタクト連携フロー

システムアーキテクチャの概要

  • 企業システム：メインシステムであり、ユーザー管理と Web Chat の統合を担当します

  • MaiAgent：Web Chat 機能を提供するサービス側です

  • 通信プロトコル：RESTful API

連携フロー

ステップ 1：ユーザー身元の確認

企業システムは、現在のユーザーが MaiAgent システム内で既に Contact として登録されているかどうかを確認する必要があります。

ステップ 2：Contact の作成または更新

ステップ 1 の結果に基づき、新規コンタクトを作成するかどうかを決定します。

新規コンタクトの作成
既存コンタクトの更新

適用される状況

初回訪問であり、企業システム内にまだ対応する Contact がない場合。例： 1. ユーザーが初めて Web Chat を通じて企業とやり取りする場合 2. 訪問者が企業の正式な会員へと移行し、訪問者時代の対話や権限を共有しないよう専用のコンタクトを作成する必要がある場合

会員が企業システム内で氏名、Email、携帯電話番号などの情報を変更し、以降の対話でパーソナライズされた内容が正しく反映されるよう MaiAgent のコンタクト情報を同期して更新する必要がある場合。 企業会員において権限やアカウント状態の変更があった場合も、Web Chat の権限が正しく対応するようコンタクト情報を更新する必要があります

API エンドポイント

POST /api/contacts/ API を使用するほか、グラフィカルインターフェースでコンタクトを作成することもできます

PUT /api/contacts/{contact_id}/

機能

新しいコンタクトを作成して対応付けに使用し、パーソナライズされた対話サービスをスムーズにします

既存コンタクトのデータを更新します。例：Query Metadata の権限管理、更新された会員データなど

パラメータ

作成するコンタクトの名前 (name) を指定する必要があります。対応する会員データがない場合はデフォルトで「匿名」となります (例：ウェブ訪問者)

contact_id を指定する必要があります

レスポンス

新しく作成された contact_id を返却します

更新成功の確認メッセージを返却します

詳細な schema の内容は 🌐 API ドキュメント-コンタクト↗ を参照してください

グラフィカルインターフェースでコンタクトを作成

  1. コンタクト管理画面に入ります

  1. 「コンタクトを追加」をクリックします

コンタクトページ

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

コンタクト編集ページ

コンタクトの氏名を追加し、対話プラットフォームを指定するとコンタクト情報を作成できます。コピーボタンをクリックすると、コンタクト ID (Web Chat の初期化パラメータ ContactId) をコピーできます。

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

👉 Query Metadata について理解する

処理ロジック：

  • 企業システムは、返却された contact_id（Create 時）を適切に保存する必要があります

  • contact_id を企業システムのユーザー ID と関連付けて保存することを推奨します

  • Update 時には、URL パスに既存の contact_id を指定する必要があります

ステップ 3：Web Chat の初期化

ステップ 2 で取得した Contact ID を Web Chat の初期化に渡すパラメータに追加し、初期化スクリプトを実行します。

🌐Web Chat の初期化↗ を参照して、Web Chat の初期化を行ってください。

利用方法の説明

企業はさまざまな対話ニーズに応じて、当該コンタクトが閲覧できるデータなどの権限を自由に設定できます。Contact の対話権限機能は、主に以下のシーンで利用されます。

  • 企業内部の権限管理：Contact 設定を通じて、異なるユーザーの対話権限の範囲を管理します

  • Web Chat の埋め込み：Web Chat を企業のウェブサイトに埋め込んだ後、MaiAgent の会員データがない状況でも、企業は contact の連携設定を通じて対話の権限管理を実現できます

  • 会員作成のスキップ：対話プラットフォームのユーザーは MaiAgent プラットフォームに登録する必要がなく、MaiAgent メンバーの作成や役割の割り当てを省略して、Contact ID を通じて直接対話権限を管理できます

この機能は、きめ細かな権限制御を必要とする企業のアプリケーションシーンに特に適しています。

実装上の推奨事項

  1. 企業システム内に Contact ID 管理表を作成することを推奨します。以下を含みます：

    • 企業ユーザー ID

    • MaiAgent Contact ID

      MaiAgent と接続を確立する際に、企業ユーザーデータと MaiAgent のコンタクトを正しく紐付けるのに役立ちます

    • 作成日時

    • 最終更新日時

  2. 冪等性チェックを実装し、Contact の重複作成を回避します

  3. ログ記録の仕組みを構築し、API 呼び出しの状況を追跡します

  4. 非同期処理の実装を検討し、ユーザー体験を向上させます。上記の Contact 関連 API とシステムの他の API を同時に複数のリクエストとして実行することで、ユーザーの待ち時間を削減します

PreviousWeb Chat SDK 操作コマンドNextロール（Role）と連絡先（Contact）の違い

Last updated

Was this helpful?