Key concepts - Text Documentation

The system includes four basic types of entities — users, chats, threads, and events.

Chats consist of threads and threads consist of events.
Threads are parts of chats.
Users can add events to chats, which then are automatically added to threads.
Users can participate in many chats at the same time.

Threads are a vital part of the architecture. Grouping events in threads allows us to provide the continuous chat experience (i.e. the customer always has the option to continue the conversation) while still maintaining smaller, logical chunks of events (e.g. for reporting and caching purposes). Handling operations such as loading archival events from the chat history can be challenging, but you won’t have to worry about managing threads most of the time. Customer SDK provides wrappers for common tasks and most methods expect to receive chat IDs. You will only get notified about thread metadata if you explicitly ask for it. You can read more about key concepts of the messaging system in the Messaging Overview.

User

Agent

{
  id: 'ed9d4095-45d6-428d-5093-f8ec7f1f81b9',
  type: 'agent',
  name: 'Jane Doe',
  jobTitle: 'Agent',
  avatar: 'https://cdn.livechat-files.com/api/file/avatar.png',
}

Customer

{
  id: 'ed9d0195-45d6-428d-5093-f8ec7f1471b9',
  type: 'customer',
  name: 'Jon Doe',
  avatar: 'https://cdn.livechat-files.com/api/file/avatar.png',
  fields: {
    custom_property: 'BasketValue=10usd',
  }
}

Chat

{
  id: 'OU0V0P0OWT',
  users: [{
    id: 'ed9d4095-45d6-428d-5093-f8ec7f1f81b9',
    // ... more user properties
  }],
  lastSeenTimestamps: {
    'ed9d4095-45d6-428d-5093-f8ec7f1f81b9': 1503062591000, // might be null
  },
  threads: ['OU0V0U3IMN'],
}

Event

Customer SDK parses the server-side form_type field as formType on form and filled_form events. The field is optional. The SDK also supports rich messages that use the ecommerce template. See the Customer Chat API event structures for their complete payloads.

{
  type: 'message',
  text: 'hi!',
    author: 'ed9d4095-45d6-428d-5093-f8ec7f1f81b9', // assigned by server
  id: 'OU0V0U3IMN_1', // assigned by server
    timestamp: 1503062591000, // assigned by server
    customId: '814.3316641404942', // optional
    thread: 'OU0V4R0OXP',
  properties: {},
}

Threads

{
  id: 'OU0V0U3IMN',
  active: true,
  order: 3,
  users: ['ed9d4095-45d6-428d-5093-f8ec7f1f81b9'],
  lastSeenTimestamps: {
    'ed9d4095-45d6-428d-5093-f8ec7f1f81b9': 1503062591000, // might be null
  },
  events: [ /* events */ ],
}

​User

​Agent

​Customer

​Chat

​Event

​Threads