Menu
Go to Console
in Platform Updates

Properties configuration with LiveChat API v3.3+

Aleksandra Kacperczyk in Configuration API, on November 10, 2021

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.

LiveChat Properties Data Storage

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)
    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:

See other Platform Updates

Automated Accessibility Testing

As described in our recent series of blog posts, our team has been working on improving the accessibility of the Chat Widget.

Read more

[API changes] Webhook migration tool available in Developer Console

Recently, we’ve introduced important changes to the LiveChat chat webhooks.

Read more
See all updates