註冊/登入

Contact introduction and integration

What is a contact?

Core definition

A Contact is an important information carrier in MaiAgent. It allows businesses to synchronize customer data with MaiAgent services, enabling precise permission management and personalized services to ensure individualized conversation experiences.

The contact operates as shown below:

MaiAgent can use the contact information in MaiAgent that corresponds to the customer’s business client data. When integrating with the MaiAgent API, by passing the corresponding contact ID, it can correctly retrieve that consumer’s past memory information and permission management content, rather than unrelated information or permission settings of other consumers.

Contact integration flow

System architecture overview

  • Business system: Main system, responsible for user management and Web Chat integration

  • MaiAgent: Service provider that offers Web Chat functionality

  • Communication protocol: RESTful API

Integration process

Step 1: User identity check

The business system needs to check whether the current user has already registered a Contact in the MaiAgent system.

Step 2: Create or update Contact

Decide whether to create a new contact based on the result of Step 1

Create new contact
Update existing contact

Applicable scenarios

First visit and there is no corresponding Contact in the business system, for example: 1. The user interacts with the business via Web Chat for the first time 2. A visitor becomes an official member of the business and a dedicated contact must be created to ensure conversations and permissions from the visitor period are not shared

When a member modifies name, email, phone number, etc. in the business system, the MaiAgent contact information should be synchronized and updated to ensure personalized content in subsequent conversations is correct. When there are changes to permissions or account status for a business member, the contact information should also be updated to ensure Web Chat permissions map correctly.

API endpoints

POST /api/contacts/ In addition to using the API, you can also usethe graphical interface to create contacts

PUT /api/contacts/{contact_id}/

Functions

Used to create a new contact mapping to ensure smooth personalized conversation services

Update existing contact data, such as: Query Metadata permission management, updated member information, etc.

Parameters

You need to provide the name of the contact to be created (name). If there is no corresponding member data, it defaults to "Anonymous" (e.g., web visitor).

You need to provide contact_id

Responses

Returns the newly created contact_id

Returns a confirmation message for a successful update

For detailed schema content, please refer to 🌐 API Docs - Contacts↗

the graphical interface to create contacts

  1. Enter the contact management interface

  1. Click "Add Contact"

Contacts page

After clicking, the following page will appear:

Contact edit page

Add the contact name and specify the conversation platform to create the contact information. You can click the copy button to copy the contact ID (used as the Web Chat initialization parameter ContactId).

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

👉 Learn about Query Metadata

Processing logic:

  • The business system needs to properly store the returned contact_id(when creating)

  • It is recommended to associate contact_id with the business system’s user ID for linked storage

  • When updating, you need to provide the existing contact_id

Step 3: Initialize Web Chat

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

Please refer to 🌐Web Chat Initialization↗, to perform Web Chat initialization

Usage instructions

Businesses can freely set what data the contact can view based on different conversation needs. The Contact conversation permission feature is mainly used in the following scenarios:

  • Internal business permission management: Manage the conversation permission scope of different users through Contact settings

  • Web Chat embedding: When Web Chat is embedded into the business website and there is no MaiAgent member data, the business can achieve conversation permission management through contact integration settings

  • Skip member creation: Conversation platform users do not need to register on the MaiAgent platform. They can skip creating MaiAgent members and role assignments, and directly manage conversation permissions via Contact ID

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

Implementation recommendations

  1. It is recommended to create a Contact ID management table in the business system, including:

    • Business user ID

    • MaiAgent Contact ID

      Helps correctly link business user data with MaiAgent contacts when establishing connections with MaiAgent

    • Creation time

    • Last updated time

  2. Implement idempotency checks, to avoid creating duplicate Contacts

  3. Create a logging mechanism, to track API call status

  4. Consider implementing asynchronous processing, to improve user experience by executing multiple requests for the above Contact-related APIs and other system APIs concurrently, reducing user wait time

PreviousWeb Chat initializationNextDifference between Role and Contact

Last updated

Was this helpful?