...

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.

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.

...