Properties are key-value pairs designed to store data about licenses, chats, threads, and other resources in the LiveChat ecosystem. You can use properties as a simple tool for storing a piece of data or as the core mechanism of your entire application. This article explains the nature of properties and how to configure them, equipping you with the knowledge to develop more powerful LiveChat integrations.
The nature of LiveChat properties
One way of thinking about properties is as key-value data storage with a configurable data type, domain, and access.
Each property configuration belongs to the Client ID (an ID given to each application with the App Authorization block, created in the Developer Console) that registered the property. In other words, properties are registered per Client ID, not per license.
Take a look at the general property format and compare it with a sample property below it.
{
"properties": {
"<namespace>": {
"<property_name>": "<property_value>",
"<property_name>": "<property_value>"
}
}
}
{
"properties": {
"8680835d93aebaec23f6d911ec9c4530": {
"string_property": "string value",
"int_property": 12
}
}
}
Properties are grouped in namespaces, which helps to distinguish which Client ID a property belongs to. This is because namespaces take their names after the Client ID that owns a given property (also referred to as the owner Client ID, the owner application, or simply the owner).
đĄ Make sure you understand the difference between property configuration and property value. Client IDs own property configurations, which you can think of as a template or definition. Property value is the data assigned to a particular property. In other words, itâs your stored value.
Property type, location, and domain
When creating a new property, the owner can configure its type, domain, and access. In the example above, we have two properties grouped in the 8680835d93aebaec23f6d911ec9c4530 namespace: a string property and an integer one. Other possible types include Boolean and tokenized string.
The Configuration API v3.3+ allows for creating properties in five locations: license, chat, thread, group, and event. One property can exist in multiple locations, which is illustrated in the example below. The string_property
exists in threads and chats. (For a detailed explanation of the access
object, see Property access.)
{
"string_property": {
"type": "string",
"description": "",
"access": {
"thread": {
"agent": ["read", "write"],
"customer": ["read"]
},
"chat": {
"agent": ["write"],
"customer": ["read", "write"]
}
}
}
}
As for the property domain, itâs a set of values a property can take. You can define those values explicitly in an array or provide a range of values.
Read more about:
Private vs. public properties
Properties can be private or public. For most app ideas, using private properties will be sufficient, and thereâll be no need to reach for public properties. Public properties will come in handy when building advanced solutions in which applications exchange information via properties.
In order to better understand the differences between private and public properties, take a look at the comparison below.
Private properties
- Only the owner Client ID can access a private property.
- Itâs possible to deregister a private property.
- The owner Client ID can publish a private property so that other integrations can access it too.
Public properties
- Public properties can be accessed not only by the owner Client ID but also by other integrations as well.
- They cannot be deregistered.
- Itâs impossible to unpublish public properties. Property publication is irreversible.
Property access
This topic troubles a lot of developers, so we decided to give it an entire section.
Let us start with private properties. Our sample property, string_property
, exists in two locations: thread and chat. In each location, access for agents and customers is configured separately, and in this case, differently. (Compare agent and customer arrays in the example below.)
{
"string_property": {
"type": "string",
"description": "",
"access": {
"thread": {
"agent": ["read", "write"],
"customer": ["read"]
},
"chat": {
"agent": ["write"],
"customer": ["read", "write"]
}
}
}
}
The access
object in private properties allows you to define a specific, rather granular access configuration according to your applicationâs functionality. So far so good.
Things get a bit more complicated when publishing a property. As youâll remember, private properties can only be accessed by their owner Client ID, while public properties can be accessed by other Client IDs as well. When publishing a property, you need to specify what kind of access other Client IDs will have to your property. You can do that with the access_type
parameter.
Take a look at the payload of a sample call to Publish Property:
{
"name": "string_property",
"owner_client_id": "8680835d93aebaec23f6d911ec9c4530",
"access_type": ["read"]
}
As you can see, the access_type
param isnât as granular as the access
one in private properties. On the contrary, access_type
is an array with only two possible values: read
and write
. The payload above tells you that Client IDs other than the owner will only have the read
access. But you might wonder who will be able to read the property: agents, customers, or both? And in which locations? For that info, you need to refer back to the property configuration, more specifically, to the access
object.
Here you can use a simple trick. Try to mask the access
object with the access_type
one and see what overlaps.
"access_type": ["read"]
"access": {
"thread": {
"agent": ["read", "write"],
"customer": ["read"]
},
"chat": {
"agent": ["write"],
"customer": ["read","write"]
}
}
What overlaps is the read
access, which means that, with the access_type
parameter, other Client IDs wonât have the write
access â neither will agents or customers, in either threads or chats. The owner Client ID, however, can access the string_property
according to the rules defined by the configuration of the access
object, which includes some write
permissions.
đĄ When considering public property access, always keep in mind that it dictates the rules of access for Client IDs other than the owner.
Dos and donâts
Properties come in handy when you want to store some additional data, such as license configuration or information about consent given by users.
However, make sure you donât use them to store the following:
- session data (use
session_fields
instead) - temporary data
- sensitive data (tokens, passwords)</br> This is especially the case for frontend apps. Itâs safer for backend apps, but not every developer wants LiveChat to store passwords/tokens in our databases. But still, itâs not something we recommend.
- GDPR data
Property configuration
Letâs put theory into practice. Imagine we want to develop an app that forwards chats with a note explaining the reason for the transfer. Weâll create a chat property for storing such notes.
Registering a property
Weâll begin by registering a property named âtransfer_noteâ, of type string
. Itâll be in the chat location. Agents need to be able to read and edit the note; hence we need to define both read and write access. We donât need to include customer access as notes will only be visible to agents.
curl -X POST 'https://api.livechatinc.com/v3.3/configuration/action/register_property' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YjIzODI0NDgtOGY5NC00OTZlLThiN2QtODAyZDI3ZDZjMDQyOmRhbDpIVE14R1ZmZFJNeHlnWmlqUEs3RTQ3YmtkWjA=' \
-d '{
"name": "transsfer_note",
"owner_client_id": "8680835d93aebaec23f6d911ec9c4530",
"type": "string",
"access": {
"chat": {
"agent": ["read", "write"]
}
}
}'
đĄ Notice Basic Auth in the request. Registering a property is a one-time action; properties are registered per Client ID (not per license), which makes it a perfect use case for authorizing with a Personal Access Token (PAT) instead of Bearer.
Listing properties
Now letâs verify that the registration was successful. To do that, weâll call List Properties:
curl -X POST 'https://api.livechatinc.com/v3.3/configuration/action/list_properties' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YjIzODI0NDgtOGY5NC00OTZlLThiN2QtODAyZDI3ZDZjMDQyOmRhbDpIVE14R1ZmZFJNeHlnWmlqUEs3RTQ3YmtkWjA=' \
-d '{
"owner_client_id": "8680835d93aebaec23f6d911ec9c4530"
}'
List Properties returned:
{
"transsfer_note": {
"type": "string",
"description": "",
"access": {
"chat": {
"agent": ["read"]
}
}
}
}
The registration was successful, but as you might have already noticed, the property name contains a typo. Since it is still a private property, we can call Unregister Property on it and register it with the correct name.
Unregistering a property
The only two params we need to provide in the Unregister Property request are owner_client_id
and the property name
. Weâre still using PATs as the authorization method.
curl -X POST 'https://api.livechatinc.com/v3.3/configuration/action/unregister_property' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YjIzODI0NDgtOGY5NC00OTZlLThiN2QtODAyZDI3ZDZjMDQyOmRhbDpIVE14R1ZmZFJNeHlnWmlqUEs3RTQ3YmtkWjA=' \
-d '{
"name": "transsfer_note",
"owner_client_id": "8680835d93aebaec23f6d911ec9c4530"
}'
After the successful âunregistration,â we can register the property again. Technically, we didnât have to âunregisterâ the property because transsfer_note
and transfer_note
are two separate entities (due to the name difference), but itâs better to keep things clean.
We could end our work here, but imagine we want to develop another application that would read the transfer_note
property and display the values on a custom chart in the Report section of the LiveChat Application. Two individual applications, installed by users separately, but built in a way that allows for app communication.
Publishing a property
Since both our applications will have different Client IDs, we need to make transfer_note
public in order to make it accessible by the reporting app. In our case, the read
access will be enough â the reporting app wonât modify the values in any way.
Notice Basic Auth yet again.
curl -X POST 'https://api.livechatinc.com/v3.3/configuration/action/publish_property' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic YjIzODI0NDgtOGY5NC00OTZlLThiN2QtODAyZDI3ZDZjMDQyOmRhbDpIVE14R1ZmZFJNeHlnWmlqUEs3RTQ3YmtkWjA=' \
-d '{
"name": "transfer_note",
"owner_client_id": "8680835d93aebaec23f6d911ec9c4530",
"access_type": ["read"]
}'
Updating a Property (Value)
To finish off, let us mock a situation in which a chat property value is updated. This would occur when agents edit their reason for the chat transfer. To implement the mechanism by which a chat property value is updated, we need to use the Update Chat Properties method from the Agent Chat API. This API contains methods for updating and deleting chat-related resources: chats, threads, and events. To update group or license properties, youâd have to use the Configuration API.
To update our property, we need to specify whose chat property weâre updating (hence id
in the payload below). As for authorization, since this call will fire multiple times for different licenses, weâll use the Bearer Token obtained from the agent installing and authorizing the app. You can use an Implicit grant or Authorization Code Grant as the authorization flow.
curl -X POST \
https://api.livechatinc.com/v3.3/agent/action/update_chat_properties \
-H 'Authorization: Bearer <your_access_token>' \
-H 'Content-Type: application/json' \
-d '{
"id": "Q1VZR7AJCE",
"properties": {
"8680835d93aebaec23f6d911ec9c4530": {
"transfer_note": "Technical question"
}
}
}'
Take this idea even further
Did you like this app idea? Feel free to turn it into a functioning solution, or come up with an original idea. Also, you can always check our App ideas section for inspiration.
Don't feel like coding? Try building blocks
Instead of registering the properties manually, you also can use our intuitive Property building block in the Developer Console. We'll register your properties under the hood, and you can enjoy a seamless process packed into user-friendly components. Our property configurator allows for the same core functionalities as manual registration, so if you prefer to add properties via interface, this building block is definitely something you'll enjoy.
Get started with building apps
Selling apps on the LiveChat Marketplace is an excellent way of generating passive income. Here are some resources that will help you get going with app development:
- đ Building LiveChat apps. A basic tutorial that will be helpful if youâre new to the LiveChat Platform.
- đ„ Authorization for web and server-side apps.
- đŁ Join our community for developers on Discord. Itâs where you can find inspiration, ask community members for help, and exchange knowledge.