A complete guide about contact properties

A contact property is a data point on your contact to let you store any information related to it. For example, the phone_number is a contact property. Some of them are default, some might be customized depending on your needs.

Each property has a:

• Name: The name of the property is something you will recognize, such as phone_number.

• Description (optional): An internal description to identify your property.

• Value: The value you want to store for each contact for the same property.

• Type: The type of value you will store (text, number, boolean, date).

Let's see an example of a few contact properties below.

As you can see, Roberto has a phone_number property of text type with the value "+353830944032".

Important: While you read "Phone number" the actual name of the property is without spaces (phone_number). Read the Important things to know section below to discover more.

Roberto has also the company_size property of number type with the value 10.

Let's discover together which property types you can track and how to better handle them.

Properties types

There are four types of properties data you can track:

• Text

  • Any strings with a max length of 128 chars

  • [eg. "Dublin", "Professional"]

  • Possible operations

    • is

    • is not

    • starts with

    • ends with

    • contains

    • does not contain

    • is set

    • is not set

• Number

  • Any Integer, Float numbers are accepted values

  • [eg. 1, 3.14, 10000, -10203]

  • Possible operations

    • equal to

    • not equal

    • less Than

    • greater than

    • is set

    • is not set

• Boolean

  • true/false, 0/1 are the only accepted values

  • [eg. true]

  • Possible operations

    • is True

    • is False

    • is set

    • is not set

• Date

  • UNIX Timestamp format only in seconds

  • [eg. 1644933485 for 2022-02-15T13:58:05.000Z]

  • Possible operations

    • is before than X days ago

    • is in the last X days

    • is before than X hours ago

    • is in the last X hours

    • is exactly X days ago

    • is before a certain date

    • is after a certain date

    • is on a certain date

    • is set

    • is not set

Important things to know

• Property names cannot have any spaces or special symbols you can only use

  • All characters from A to Z, uppercase o lowercase

  • All numbers from 0 to 9

  • _ and -

• You can start a property name with a number (eg. 2type, 1attempt)

• You cannot use any reserved name by any default property

• The properties names are difficult to read and for this reason, you will find a human-readable name in the App for example last_page_viewed_at becomes the Last page viewed at

• If the property does not exist on your Customerly project and you send it for the first time on a contact we'll set the value for that contact and for all the remaining contacts will be not set.

• If the property value exists on the customer and you send us a new value, we will override it with the new one.

Default properties

These are the default properties we handle on our end. Some of them are writable from you, others are read-only. This means that if a property is read-only you cannot change it in any way. Such as the IP address of a contact. Writable means you can modify its value.

• email

  • [text | Writable] The text property used to store the email of your contacts

  • Read/Update via Chat API, REST API, Integrations, Import

• name

  • [text | Writable] The text property to store your primary contact name

  • Read/Update via Chat API, REST API, Integrations, Import

• first_seen_at

  • [date | Writable] A dated property is updated only when the contact has been seen for the first time

  • Read/Update via Chat API, REST API, Integrations, Import

• last_page_viewed

  • [text | Writable] This field updates every time a contact visit a page with the live chat snippet. It contains the full URL of the page visited

  • Read/Update via Chat API, REST API, Integrations, Import

• last_page_viewed_at

  • [date | Writable] This property updates every time a contact visit a page with the live chat snippet installed.

  • Read/Update via Chat API, REST API, Integrations, Import

• last_activity

  • [date | Read-only] Updated every time the contact visit a page where the live chat is loaded.

  • Update only via Chat API and Integrations

  • Read via REST API, Integrations

• ip_address

  • [text | Read-only] Updated with the last IP address recognized from the device used to browse where a live chat snippet is installed

  • Update only via Chat API and Integrations

  • Read via REST API, Integrations

• timezone

  • [text | Writable] It is updated when the live chat snippet recognizes a new IP address for the contact.

• city

  • [text | Writable] We geolocate your contacts based on their IPs and update the city with a good accuracy level. Is not always 100% accurate though.

• postal_code

  • [text | Writable] We geolocate your contacts based on their IPs and update the postal_code with a good accuracy level. Is not always 100% accurate though.

• region

  • [text | Writable] We geolocate your contacts based on their IPs and update the region with a good accuracy level. Is not always 100% accurate though.

• rating

  • [number | Writable] Rating is a great opportunity to score your contacts. It can be automated with workflows or manually scored in your inbox.

• region_code

  • [text | Writable] We geolocate your contacts based on their IPs and update the region_code with a good accuracy level. Is not always 100% accurate though.

• country

  • [text | Writable] We geolocate your contacts based on their IPs and update the country with a good accuracy level. Is not always 100% accurate though.

• country_code

  • [text | Writable] We geolocate your contacts based on their IPs and update the country_code with a good accuracy level. Is not always 100% accurate though.

• isp

  • [text | Writable] We lookup for the ISP based on the IP address.

• browser_name

  • [text | Writable] The name of the browser used by the contact tracked by the live chat snippet

• browser_version

  • [text | Writable] The version of the browser used by the contact tracked by the live chat snippet

• browser_language

  • [text | Writable] This field is updated when the live chat snippet identifies your contact default primary language. The standard we use is the ISO RFC 5646.

• os

  • [text | Writable] The Operating system used by your contacts when browsing on a page with the live chat snippet

  • Eg. Macintosh, iPhone, Ubuntu, Windows

• os_version

  • [text | Writable] The Operating system version used by your contacts when browsing on a page with the live chat snippet

  • Eg. OS X Mavericks

• web_session

  • [number | Writable] Number of sessions tracked from the live chat snippet. It increments every time a user visits a new page only if the last update was at least 1 hour before.

Default marketing properties

These properties are handled on our side automatically and in some cases, you can override them.

• bounced

  • [boolean | Read-only] A property that defines the contact status if it's bounced or not in the last sendings to their email address.

• unsubscribe

  • [boolean | Read-only] A property that defines the status of the contact if they decided to unsubscribe from any of your email messages.

• spam

  • [boolean | Read-only] A property that changes based on the block/unblocks action in your inbox section.

• utm_source

  • [text | Writable] The UTM source is an URL parameter we store automatically for you when someone lands on a page with the live chat installed.

• utm_campaign

  • [text | Writable] The UTM campaign is an URL parameter we store automatically for you when someone lands on a page with the live chat installed.

• utm_medium

  • [text | Writable] The UTM medium is an URL parameter we store automatically for you when someone lands on a page with the live chat installed.

• utm_term

  • [text | Writable] The UTM term is an URL parameter we store automatically for you when someone lands on a page with the live chat installed.

• utm_content

  • [text | Writable] The UTM content is an URL parameter we store automatically for you when someone lands on a page with the live chat installed.

• referrer

  • [text | Writable] The referrer is the page or domain your contact is coming from.

Suggested marketing properties

These properties are strongly suggested to manage marketing preferences in compliance with GDPR rules.

• marketing

  • [boolean] You can use a boolean to collect consensus for your marketing communications.

• newsletter

  • [boolean] You can use a boolean to collect consensus for your newsletter communications.

• product_updates

  • [boolean] You can use a boolean to collect consensus for your product_updates communications.

• offers

  • [boolean] You can use a boolean to collect consensus for your offers communications.

Default mobile properties

When you install the Customerly SDK on your mobile apps, we are going to track automatically for you the following properties for any of your contacts using your mobile apps.

• android_app_name

  • [text | Writable] The name of the app your contact is using.

• android_app_version

  • [text | Writable] The version of the app your contact is using.

• android_device

  • [text | Writable] The android device your contact is using your app from.

• android_os_version

  • [text | Writable] The android device OS version your contact is using your app from.

• android_session

  • [number | Writable] The number of sessions from the android app

• android_last_seen_at

  • [date | Writable] The last seen date when your contact has used the mobile android app.

• ios_app_name

  • [text | Writable] The version of the app your contact is using.

• ios_app_version

  • [text | Writable] The version of the app your contact is using.

• ios_device

  • [text | Writable] The iOS device your contact is using your app from.

• ios_os_version

  • [text | Writable] The iOS version your contact is using your app from.

• ios_session

  • [number | Writable] The number of sessions from the iOS app

• ios_last_seen_at

  • [date | Writable] The last seen date when your contact has used the mobile iOS app.

These are the standard properties we track for each contact. On top of these, you might want to add your own custom properties.

Track custom properties

To track a custom property you just need to pass the information to us via:

• JS API

• REST API

• CSV/XML import

• Outbound Profiling chats messages

• data connectors (eg. Zapier, Integromat)

Find more on how to track custom properties for your contacts.