Changelog
Agent Chat API
Web API Reference
RTM API Reference
Data structures
RTM pushes
Changelog
Customer Chat API

Changelog

This document is the record of all the changes in the Agent Chat API, Web and RTM references, starting from version 3.0.

We use the 🛠️ emoji to mark bug fixes. We also specify the date of introducing the fix in the YYYY-MM-DD format.

The developer preview version provides a preview of the upcoming changes to the API. It's not open to public use. However, if you want to test some features, contact us at developers@livechat.com or ask on the chat, and we'll give you access.

[v3.5] - Developer preview

Chats

  • The List Archives (Web & RTM) method has a new filter, customer_countries.

Status

  • The Change Push Notifications method was removed.
  • The Login (RTM) method no longer accepts the push_notifications parameter.

Configuration

[v3.4] - 2021-12-22

Chats

  • There are new pushes:
  • The List Archives (Web & RTM) method:
    • has new filters: event_types (which replaces the events filter), greetings, and agent_response.
    • has new filter modifiers: filters.agents.require_every_value, filters.tags.require_every_value, filters.sales.require_every_value, filters.goals.require_every_value, and filters.event_types.require_every_value.
  • Multiple methods no longer require the chats--my:ro, chats--my:rw, chats.conversation--my:rw, and chats.conversation--my:rw scopes.
  • The Start Chat (Web & RTM) and Resume Chat (Web & RTM) methods now require that authors (except the requester) of all initial events are listed in the users field. Both the events and users have a fixed visibility set to all.
  • The Start Chat, Resume Chat, Send Event, Send Typing Indicator, and Send Rich Message Postback methods now require either the chats--all:rw or chats--access:rw scope instead of the chats.conversation--all:rw or chats.conversation--access:rw.
  • The Deactivate Chat (Web & RTM) method now requires the requester to be present on the list of chat users. You can override it with a new param, ignore_requester_presence.

Chats users

  • Users now have a new field, visibility.
  • The Add User to Chat (Web & RTM) method:
    • now requires an active thread. The require_active_thread flag was removed.
    • now requires the requester to be present on the list of chat users. You can override it with a new param, ignore_requester_presence.
  • The Remove User from Chat (Web & RTM) method now requires the requester to be present on the list of chat users. You can override it with a new param, ignore_requester_presence.

Chat access

  • The Transfer Chat (Web & RTM) method:
    • now requires an active thread.
    • now requires the requester to be present on the list of chat users. You can override it with a new param, ignore_requester_presence.
    • had the force parameter renamed to ignore_agents_availability.
  • The Grant Chat Access and Revoke Chat Access methods were removed. Their use cases are now covered by Transfer Chat (Web & RTM). The corresponding pushes, chat_access_granted and chat_access_revoked, were also removed and replaced by the chat_access_updated push.

Configuration

Threads

  • There are new properties: previous_accessible_thread_id and next_accessible_thread_id, which can be returned by the List Archives (Web & RTM) method.

Events

  • The Form (Web & RTM) and Filled Form (Web & RTM) events have a new field, form_type.
  • All Events (Web & RTM) had the recipients field renamed to visibility.
  • The Send Event (Web & RTM) method now requires the requester to be present on the list of chat users.

Status

  • The Login (RTM) method has a new response parameter, license.organization_id, which contains the ID of the organization associated with the license you logged into.
  • The agent_disconnected push has a new reason, connection_evicted.

Other

[v3.3] - 2021-03-30

RTM

  • The General RTM API Request Format was extended with an optional parameter, version. You can now call individual methods on different (higher) versions than the one of your RTM connection.
  • The General Push Format was extended with the version field. To receive pushes from different API versions, subscribe to them via the new, pushes parameter in Login (RTM).

Chats

  • The Deactivate Chat (Web & RTM) method had the chat_id parameter renamed to id.
  • The Follow Chat (Web & RTM) method had the chat_id parameter renamed to id.
  • The Unfollow Chat (Web & RTM) method had the chat_id parameter renamed to id.
  • The Activate Chat method was renamed to Resume Chat (Web & RTM).
  • The Start Chat (Web & RTM) and Resume Chat (Web & RTM) methods have a new optional parameter, active.
  • The Start Chat and Activate Chat methods now update the requester's events_seen_up_to as if all chat events were already seen by the requester. A subsequent call to Mark Events As Seen can be skipped in such cases.

Chat access

  • The Transfer Chat (Web & RTM) method had the chat_id parameter renamed to id.

Events, users & data structures

  • The File (Web & RTM) event has a new parameter for images, alternative_text.
  • The Rich Message (Web & RTM) data structure:
    • has a new parameter for images, alternative_text,
    • has a new property for buttons, target.
  • The Customer (Web & RTM) data structure:
    • has a new property for visits, ended_at.
    • has new properties: followed, online, group_ids, state, email_verified.
  • In the Filled form fields and Form fields data structures, the type property has a new possible value, subject. It's a new type that can appear in ticket forms.
  • There's a new event type, Form that allows for sending an empty form to fill out.

Properties

  • The Update Chat Properties (Web & RTM) method had the chat_id parameter renamed to id.
  • The Delete Chat Properties (Web & RTM) method had the chat_id parameter renamed to id.

Customers

  • The Get Customer (Web & RTM) method had the customer_id parameter renamed to id.
  • The Update Customer (Web & RTM) method had the customer_id parameter renamed to id.
  • The Ban Customer (Web & RTM) method had the customer_id parameter renamed to id.
  • There are new methods:
  • There's a new push, incoming_customers.
  • There's a new push, customer_unfollowed, complementary to the Unfollow Customer method.
  • The customer_created and customer_visit_started pushes were replaced by the incoming_customer push.
  • The customer_visit_ended push was replaced by the customer_left and customer_transferred pushes.
  • The List Customers (Web & RTM) method:
    • has a new parameter, sort_by.
    • has new filters: include_customers_without_chats and chat_group_ids.
    • has a new field, limited_customers, added to the response.
  • The List Threads (Web & RTM) method:
    • has new filters: from and to.
  • The customer_updated push:
    • now returns only the updated data.
    • has a new format; the fields are no longer nested within the customer field.

Status

  • The Login (RTM) method has new optional parameters:
    • customer_monitoring_level - it controls the volume of customer-related pushes sent to the agent.
    • pushes- it controls to which pushes the user is subscribed during the current RTM connection.
  • There's a new method, List Routing Statuses (Web & RTM), for retrieving the agent's current routing status.

[v3.2] - 2020-06-18

Chats

  • The Get Archives method was renamed to List Archives (Web & RTM).
  • The List Archives method:
    • has a new filter, agents. It replaces the agents_ids filter.
    • has a new filter, events.types.
    • has new pagination with hashed page IDs replacing the old pagination format. Pagination is now uniform across the whole Agent Chat API.
    • has a new parameter, highlights. It allows you to highlight the match of filters.query with an HTML tag.
  • The Get Chats Summary method was renamed to List Chats (Web & RTM).
  • The List Chats method:
    • has a new filter, include_chats_without_threads.
    • had the order field renamed to sort_order.
    • had the chat.order field removed from the response.
  • The Get Chat Threads method evolved into Get Chat (Web & RTM).
  • The Get Chat method:
    • allows to retrieve a particular thread from the specified chat.
    • changed its shape; it no longer contains the order field and the chat key.
    • returns thread instead of threads_summary.
  • The Close Thread method was renamed to Deactivate Chat (Web & RTM). The corresponding push, thread_closed, was renamed to chat_deactivated.
  • The incoming_chat_thread push was renamed to incoming_chat.
  • The incoming_chat push has new fields, requester_id and transferred_from.
  • There's a new method, List Threads (Web & RTM).
  • There's a new push, chat_unfollowed, complementary to the Unfollow Chat method.
  • The Get Chat Threads Summary method was removed.

Chat access

  • The Grant Access method was renamed to Grant Chat Access (Web & RTM).
  • The Grant Chat Access method:
    • no longer accepts the resource parameter.
    • had its corresponding push, access_granted, renamed to chat_access_granted.
  • The Revoke Access method was renamed to Revoke Chat Access (Web & RTM).
  • The Revoke Access method:
    • no longer accepts the resource parameter.
    • had its corresponding push, access_revoked, renamed to chat_access_revoked.
  • Transfer Chat (Web & RTM) can now be used with inactive chats.
  • The chat_transferred push:
    • is no longer tied directly to Transfer Chat. Now, it can be generated when the transfer is implicit, for example, agents are reassigned due to their inactivity.
    • has new fields, requester_id, thread_id, reason, queue, and transferred_to.
    • no longer has the type and ids fields.
  • The Set Chat Access method was removed. Its use cases are now covered by Transfer Chat (Web & RTM). The corresponding push, chat_access_set, was also removed.

Chat users

  • The chat_user_added push was renamed to user_added_to_chat.
  • The user_added_to_chat push:
    • has new fields: reason and requester_id.
    • no longer has the user_type field.
  • The chat_user_removed push was renamed to user_removed_from_chat.
  • The user_removed_from_chat push:
    • has new fields: reason and requester_id.
    • no longer has the user_type field.
  • The Add User to Chat method (Web & RTM) accepts an optional parameter, require_active_thread.

Events

  • The Thread data structure:
    • has new fields: previous_thread_id, next_thread_id, queue, and queues_duration.
    • had the order and timestamp fields replaced with a new one, created_at (date & time in microseconds in UTC).
    • had the restricted_access field type changed to string. It contains the reason for access restriction.
  • The Filled form fields data structure has a new parameter, id (fields.answer.id for the group_chooser field type). It's an identifier for each option Customers can choose.
  • The Chat summary data structure has a new field, queue, nested in last_thread_summary.

Properties

  • The Property data structure now has the same format in requests as in responses and pushes.
  • The Update Chat Thread Properties method was renamed to Update Thread Properties (Web & RTM). The corresponding push, chat_thread_properties_updated, was renamed to thread_properties_updated.
  • The Delete Chat Thread Properties method was renamed to Delete Thread Properties (Web & RTM). The corresponding push, chat_thread_properties_deleted, was renamed to thread_properties_deleted.

Thread tags

  • The Tag Chat Thread method was renamed to Tag Thread (Web & RTM). The corresponding push, chat_thread_tagged, was renamed to thread_tagged.
  • The Untag Chat Thread method was renamed to Untag Thread (Web & RTM). The corresponding push, chat_thread_untagged, was renamed to thread_untagged.

Customers

  • There's a new method Get Customer (Web & RTM) that returns info about a given Customer.
  • The Update Customer (Web & RTM) method, which used to return the Customer data structure, now has no response payload.
  • Each method, response, and push that deals with a variation of customer fields had this field renamed to session_fields and its format changed. It's now an array that respects the item order.
  • The Get Customers method was renamed to List Customers (Web & RTM).
  • In the List Customers method, the order field was renamed to sort_order.

Status

  • The Login method:
    • has a new parameter away. It was introduced to prevent chat assignments after unexpected reconnects.
    • had the order field in the chat object removed from the responses.
  • The Update Agent method was replaced with Set Routing Status (Web & RTM). The corresponding push, agent_updated, was replaced with routing_status_set.

Other

  • There's a new method List Agents For Transfer (Web & RTM).
  • There's a new push, queue_positions_updated, with updated positions and wait times for queued chats.
  • In Multicast (Web & RTM), the scopes field was renamed to recipients.

[v3.1] - 2019-09-17

Added

  • Web API: The Send File method was replaced with Upload File (Web). The new method should be used along with Send Event (Web & RTM), Start Chat (Web & RTM), or Activate Chat (Web & RTM).

Changed

  • Web API: From now on, sending payloads explicitly in the request body is allowed. You no longer have to wrap it up in the payload object.
  • Web API: When using Bot Agents, you need to include the X-Author-Id header in requests instead of sending author_id in the request body.
  • Method Update Last Seen Timestamp was transformed into Mark Events as Seen (Web & RTM). Now, it accepts the seen_up_to parameter (date & time in microseconds in UTC) instead of timestamp. Also, it no longer returns timestamp in the response.
  • Push last_seen_timestamp_updated was transformed into events_marked_as_seen with seen_up_to parameter instead of timestamp.
  • Fields order and timestamp in events were replaced with the new field, created_at (date & time in microseconds in UTC).
  • Method Create Customer (Web & RTM) now returns only customer_id instead of the whole Customer data structure.
  • Method Send Event (Web & RTM) no longer accepts the require_active_thread parameter. Thread is always required to be active unless attach_to_last_thread is enabled.
  • Method Send Event now returns only event_id instead of the whole Event data structure.
  • Method Start Chat (Web & RTM) now returns only chat_id, thread_id and optionally event_ids if requested. It used to return the whole Chat data structure.
  • Method Activate Chat (Web & RTM) now returns only thread_id and optionally event_ids if requested. It used to return the whole Chat data structure.

Removed

  • The Send File method was removed.

...