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.

[v3.6] - Developer preview

Chats

• The Get Chat (Web & RTM) method now validates access to the requested thread.
• The Thread data structure has a new customer_visit field.
• The agent_disconnected push has a reason for disconnection, role_permissions_changed.

Customers

• The List Customers method was removed.

Bots

• Authorizing bots via X-Author-Id is removed. Bots can be authorized only via the new Bot Authorization Tokens (see **Issue Bot Token).

[v3.5] - 2022-11-23

Chats

• The List Archives (Web & RTM) method has a new filter, customer_countries.
• 🛠️ (2022-12-7): The Get Chat (Web & RTM) method now validates access to the requested thread.

Status

• The Change Push Notifications method was removed.
• The Login (RTM) method no longer accepts the push_notifications parameter.
• A new push, groups_status_updated has been added.
• The incoming_multicast push is no longer sent when group statuses change.

Configuration

• There are new pushes:
  • tag_created
  • tag_deleted
  • tag_updated
• The work_scheduler field in agent_created, agent_updated, bot_created, and bot_updated pushes has a new format.

[v3.4] - 2021-12-22

Chats

• There are new pushes:
  • chat_deleted
  • thread_deleted
  • threads_deleted
• 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.
• 🛠️ (2022-12-7): The Get Chat (Web & RTM) method now validates access to the requested thread.

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

• Updating license resources in the Configuration API v3 now results in pushes informing agents about applied changes. These pushes are as follows:
  • agent_created
  • agent_approved
  • agent_updated
  • agent_suspended
  • agent_unsuspended
  • agent_deleted
  • auto_access_added
  • auto_access_updated
  • auto_access_deleted
  • bot_created
  • bot_updated
  • bot_deleted
  • group_created
  • group_deleted
  • group_updated

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

• The Send Typing Indicator (Web & RTM) method and incoming_typing_indicator push had the field recipients renamed to visibility.

[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:
  • Follow Customer (Web & RTM).
  • Unfollow Customer (Web & RTM).
• 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.