Skip to main content

Feature Description｜Contact Field Definitions and Matching Logic

  • Updated

    # Feature Overview

    MAAC lets brands create and update contacts in multiple ways, and matches against existing data based on a specified "Key value" to automatically determine whether to create a new contact or update existing fields. This article explains:

    • The content and format supported by each contact field
    • The matching logic of the Key value (matching basis)
    • The update behavior of each field
    • The non-updatable fields of each channel (LINE UID, WA Mobile, Email…)
    • Email / WhatsApp contact status, reachability, and irreversible update rules
    • The definition and application of bound contacts
    • Common errors and reasons for update failures
    • Identity conflict detection: how the system avoids incorrect merging when Customer IDs are inconsistent
    • The purpose and update logic of system-maintained fields (such as last_message_time)

    # Matching Logic

    When importing or creating contact data, you need to select a Key value as the matching basis.

    • If the Key value matches → update the existing contact
    • If it cannot be matched → create a new contact Profile / no contact update is made
    Key value Applies to Matching logic Notes
    line_uid LINE contacts Full match by LINE UID LINE UID is a non-editable field
    customer_id Cross-channel contacts Matches the brand's custom unique identifier Can only update the basic data of channel contacts
    phone

    WhatsApp contacts

    SMS contacts

    or contacts that have a phone field

    		 Matches the phone number
    email EDM contacts Full match by Email EDM Email is a non-editable field

    Important: the sending key values of each channel's contacts cannot be updated:

    • LINE contacts: LINE UID
    • WhatsApp contacts: WhatsApp mobile
    • Email contacts: Email
    • Other contacts: phone

    If the CSV provides a value for this field, the system ignores it and will not update it.

    📌 We recommend exporting your data once before importing to confirm whether the Key values are consistent, in order to avoid creating duplicate contacts.

    Identity Conflict Detection (Inconsistent Customer ID) 🆕

    📌 Identity conflict detection is only enabled when Customer ID is set as a Unify Key
    Customer ID behaves differently depending on whether it is set as a Unify Key:
    • Set as a Unify Key: Customer ID participates in Identity Integration and triggers the conflict protection described below when it is inconsistent.
    • Not set as a Unify Key: Customer ID is treated as an ordinary contact field and is directly updated / synchronized to the latest value; the system does not perform identity conflict detection.

    Under the above conditions, when the system matches multiple contacts that may belong to the same person (for example, unified as the same person by Email or phone), but these contacts carry different Customer IDs, then to avoid incorrectly merging different people, the system does not merge these contacts automatically and marks them as an "identity conflict".

    • When matching Customer IDs, the system ignores letter case and leading/trailing whitespace.
    • When a conflict occurs, the related contacts each remain independent contacts and are not merged into one.
    • You can see the conflict prompt on the Unified Contact Profile, and you can download the conflict list from Export in the contact list to clean it up.

    How to resolve a conflict:

    1. Confirm whether these contacts truly belong to the same person.
    2. Correct the wrong Customer ID, or add the correct identifying data.
    3. Re-import these contacts so the system runs Identity Integration again (integration runs in the background; return to confirm the result after it is complete).

    👉 To download the conflict list, see: How to Export Contacts and the Data Mapping Table; to re-import after correction, see: Tutorial | Import and Update Contact Data in MAAC.

    Field Display of Unified Contacts 🆕

    When multiple channel contacts of the same person are unified into one Unified Contact, the fields shown on the Unified Contact Profile (such as display name, birthday, gender, custom fields, and tags) are aggregated from the data of each channel contact under that person, and for the same field, the most recently updated value takes precedence.

    Identifying data specific to each channel, such as phone and Email, is kept at the channel level and is not overwritten across the values of other channel contacts because of unification.

    👉 For the full explanation of each section of the Unified Contact Profile, see: Tutorial | Unified Contact Profile and Splitting Contacts.

    # Email Contact Subscription Status Logic

    In addition to being identified by email as the primary key, whether an Email contact can be sent to normally in automated journeys or other Email features also depends on the subscription status messaging_status.

    Status display Definition Sendable
    Subscribed The contact agrees to receive Email, and the email status is normal. Yes
    Unsubscribed The contact has actively clicked unsubscribe; Email should no longer be sent. No

    ⚠️ Once an Email status is unsubscribed, it is subject to an "irreversible" restriction: you cannot change a contact whose status is "Unsubscribed" or "system-blocked" back to "Subscribed" via CSV import. If the CSV attempts to reset it, the system will ignore that status update.
    ＊ However, you can change a "Subscribed" contact to an "Unsubscribed" contact via CSV import, to achieve the effect of cleaning the list.

    👉 For detailed import rules, see: Tutorial｜How to Enable the Email Channel and Import Contacts and Tutorial | Import and Update Contact Data in MAAC

    # Contact Field Support Overview

    Basic fields

    Field name Description Importable Updatable Notes
    phone Phone ✅ Yes Used as a matching Key; avoid sharing across multiple records
    customer_id Brand-defined identifier ✅ Yes Recommended for CRM use
    email Email ✅ Not updatable
    (Email contact key value)    		 Identifies Email contacts; read together with subscription status
    name Display name ✅ Yes Overwrites if a value is present
    note Note ✅ Yes Overwrites if a value is present
    tags Contact tags ✅ Yes Tags are merged, not overwritten

    📌 In addition to the basic fields above, brands can create "Custom Fields"; see the Custom Fields section below

    Channel contact sending Key values (not updatable)

    Field Channel Rule
    line_uid LINE The unique identifier bound to LINE; not updatable
    WhatsApp_mobile WhatsApp

    Used as the primary key when importing WA contacts; not updatable

    • The status field (opted_in / not_subscribed / opted_out) is required
    email EDM Used as the primary key when importing Email contacts; not updatable; whether it can be sent to also depends on subscription status
    phone (SMS) SMS The primary key of SMS contacts; can be used as a Key, but cannot be overwritten by a customer_id update

    System-maintained fields

    The following fields are written and updated automatically by the system. Brands cannot modify them manually, nor can they overwrite them via CSV import or API.

    Field name Description Data type Write / clear timing Purpose and notes
    last_message_time
    (last message time)     		Records the time the contact last sent a message on each channel (LINE / WhatsApp) DateTime (UTC)

    Write: automatically updated each time the contact sends a message
    Clear:

    • LINE: cleared when the contact unfollows
    • WhatsApp: cleared when the contact opts out
    		 Used to determine the "first message" trigger in automated journeys — when this field is empty (NULL), the system determines that message to be the "first message".

    📌 This field is system-maintained and cannot be modified manually by the brand.
    📌 Additional notes
    After a contact unfollows on LINE or opts out on WhatsApp, last_message_time is cleared. If that contact later re-follows (LINE re-follow) or re-subscribes (WhatsApp re-opt-in), their first message sent afterward will again be treated as the "first message" and can re-trigger the corresponding automated journey.

    👉 For detailed automated journey trigger logic, see: Feature Description｜Omnichannel Customer Journey

    # Custom Fields

    In addition to the basic fields above, brands can create "Custom Fields" through the Admin Center to integrate structured CRM data into MAAC contacts.

    📕 Read first: Tutorial｜MAAC × CAAC Cross-Product Custom Field Setup (creating and managing fields in the Admin Center)

    Supported data types

    Data type Description Use case
    Text Free-form text input Membership tier, preferred product category
    Number Numeric format, supports greater-than/less-than comparison Reward points, number of purchases, purchase amount
    Date Date only (YYYY-MM-DD), without time Birthday, membership anniversary, contract expiry date
    DateTime Accurate to the second, stored internally as UTC+0, and automatically converted to the organization's time zone in the interface Appointment expiry time, limited-time coupon expiration time

    Viewing and manually editing custom fields

    Enter any contact's page and you can find the "Custom Fields" section. Click "🔒 Edit" to manually update custom field values, then click "Save" to synchronize them to the CDH.

    • Fields are ordered by creation time
    • If a field is archived in the Admin Center, it will not be displayed in the MAAC interface

    How custom fields are modified

    The system supports four modification methods to keep your list up to date at all times:

    Update method How it works
    Automatic sync (API) If your company has integrated an external CRM, the data updates automatically at any time, ensuring you see the latest status. For details, see this API documentation.
    Bulk CSV import Suitable for marketers' monthly reconciliations, or for batch-uploading offline event lists for updates. 👉 Tutorial | Import and Update Contact Data in MAAC
    Manual editing You can modify field content directly on the contact page (as described in the "Viewing and manually editing" section above).
    Journey automatic update In an automated journey, you can use the "Update Attribute" action node to automatically write or clear custom field values. 👉 Feature Description｜Customer Journey
    ⚠️ Notes
    If you "Archive" a custom field in the Admin Center, that field will be hidden from the MAAC contact interface, and the system will stop reading and writing it. After unarchiving, the historical data is fully restored.

    👉 For more applications of custom fields in journeys and contacts, see: Tutorial｜Using Cross-Product Custom Fields in MAAC

    # Field Update Behavior and Notes

    Behavior How the system handles it
    Has a new value Overwrites the original value
    Field is empty Skips it; does not overwrite
    Multiple tags Merges them; does not clear existing tags
    Wrong CSV field name Skips that field
    Updating a non-updatable field (such as line_uid, email, WA mobile) Will be ignored
    Updating an Email contact's status to Subscribed (when the original status is Unsubscribed / system-blocked) The system ignores that status update; it only updates the other updatable fields
    Attempting to modify a system-maintained field (such as last_message_time) via CSV or API The system ignores it; this field is only written and cleared automatically by the system

    # What Is a "Bound Contact"?

    In MAAC, if a contact's data includes the customer_id field, that contact is a "bound contact". This means the contact has completed identification binding with the brand's own system (such as a membership system or CRM) and can serve as a target for further integration and personalized applications.

    Use cases:

    • Personalized Rich Menu
      Display exclusive content for bound contacts; for example, show "Join Membership" for unbound users, and "Check Order" or "Membership Points" for bound users.

    • Differentiated auto-reply messages
      You can set conditions in auto-replies to send different messages to bound contacts, such as VIP-exclusive offers or birthday greetings.

    • Integrating membership system data
      When data is returned via API or Webhook, you can integrate it through customer_id to ensure identity consistency.

    📌 Tip
    If your brand has a membership program or loyalty program, or you want to enable further personalized campaigns and marketing automation, we recommend binding customer_id first.

    📌 If you have already enabled the Email channel, we also recommend going to Customer Data Hub (CDH) and setting Email as a Unify Key. This allows LINE and Email contacts to be unified more accurately, avoiding duplicate triggering or duplicate communication in cross-channel journeys.

    # FAQs

    Q1: Which field should I choose as the matching basis?

    A: Choose the most representative Key value based on the source of the imported data:
    - LINE webhook → use line_uid
    - CRM system data → use customer_id
    - Phone list → use phone, but confirm there are no duplicate phones

    Q2: I import data using phone as the key value — which contact will be updated?

    A: If multiple contacts in the system use the same phone, the system will update the one that was created later.
    We recommend using line_uid or customer_id instead to avoid incorrect updates.

    Q3: Can external_member_id be used to import or update?

    A: No. This field is only for exporting and looking up the UID mapping; it cannot be used as an import field.

    Q4: Can the last_message_time field be modified manually?

    A: No. last_message_time is a system-maintained field, automatically updated by the system each time the contact sends a message on LINE or WhatsApp. Brands cannot modify this field via CSV import, API, or manual editing. This field is mainly used for the "first message" trigger determination in automated journeys.

    Related Articles

    Related articles