Contact Introduction and Integration

What is Contact?

Core Definition

Contact is an important information carrier in MaiAgent that allows enterprises to synchronize customer data with MaiAgent services, enabling precise permission management and personalized services to ensure personalized conversation services.

The Contact operation works as follows:

Enterprise Integration for External Consumer Use

Enterprise Integration for Internal Employee Use

Through the contact information corresponding to the customer's enterprise data in MaiAgent, when integrating with MaiAgent API, MaiAgent can correctly trace back the past memory information and permission management content related to that consumer by passing the corresponding contact ID, rather than irrelevant information or permission settings of other consumers.

Contact Integration Flow

System Architecture Overview

• Enterprise System: Main system responsible for user management and Web Chat integration

• MaiAgent: Service provider for Web Chat functionality

• Communication Protocol: RESTful API

Integration Process

Step 1: User Identity Check

Enterprise system needs to check if the current user has already registered a Contact in the MaiAgent system.

Step 2: Create or Update Contact

Based on Step 1 results, decide whether to create a new contact

	Create New Contact	Update Existing Contact
Use Cases	First visit with no corresponding Contact in enterprise system, such as: 1. User's first interaction via Web Chat 2. Visitor becomes official enterprise member, requiring dedicated contact to ensure separation of visitor period conversations and permissions	When members modify name, email, phone, etc. in enterprise system, MaiAgent contact info needs updating to ensure correct personalization in subsequent conversations When enterprise member permissions or account status changes, contact info should be updated to ensure correct Web Chat permissions
API Endpoint	POST /api/contacts/ Besides API, can also use graphical interface to create contacts	PUT /api/contacts/{contact_id}/
Function	Create new contact mapping to ensure smooth personalized conversation service	Update existing contact data, e.g.: Query Metadata permissions, updated member data
Parameters	Must provide contact name to create, defaults to "Anonymous" if no member data exists (e.g. website visitors)	Must provide contact_id
Response	Returns newly created contact_id	Returns update success confirmation

For detailed schema content, refer to 🌐 API Documentation-Contact↗

Creating Contact via Graphical Interface

1. Enter Contact Management Interface

1. Click "Add Contact"

Contact Page

The following page will appear:

Contact Edit Page

After adding contact name and specifying conversation platform, contact information can be created. Click the copy button to copy the Contact ID (used as Web Chat initialization parameter ContactId)

---

The identity information set for Contact will be used to generate corresponding query_metadata condition combinations during queries

👉 Learn about Query Metadata

Processing Logic:

• Enterprise system needs to properly store returned contact_id (during Create)

• Recommend associating contact_id with enterprise system user ID

• Update requires existing contact_id in URL path

Step 3: Initialize Web Chat

Add the Contact ID obtained in Step 2 to Web Chat initialization parameters and execute initialization script.

Please refer to 🌐Web Chat Initialization↗ for Web Chat initialization

Usage Guide

Enterprises can freely set permissions such as viewable data for contacts based on different conversation needs. Contact conversation permission features are mainly used in these scenarios:

• Enterprise Internal Permission Management: Manage conversation permission scope for different users through Contact settings

• Web Chat Embedding: When Web Chat is embedded in enterprise website, without MaiAgent member data, enterprises can achieve conversation permission management through contact integration settings

• Skip Member Creation: Conversation platform users don't need to register on MaiAgent platform, can bypass MaiAgent member creation and role assignment, directly manage conversation permissions through Contact ID

This feature is especially suitable for enterprise application scenarios requiring fine-grained permission control.

Implementation Recommendations

1. Recommend creating Contact ID management table in enterprise system, including:

   • Enterprise user ID

   • MaiAgent Contact ID Helps correctly link enterprise user data with MaiAgent contacts when connecting with MaiAgent

   • Creation time

   • Last update time

2. Implement idempotency checks to avoid duplicate Contact creation

3. Establish logging mechanism to track API call status

4. Consider implementing asynchronous processing to improve user experience, executing multiple requests simultaneously for Contact-related APIs and other system APIs to reduce user wait time