From 64900775577a8c22d7e34f984ac18c8cb5bfaa7d Mon Sep 17 00:00:00 2001 From: Marcin Dojwa Date: Mon, 16 Jun 2025 17:01:18 +0200 Subject: [PATCH 1/3] feat: document greetings methods --- .../configuration-api/v3.6/index.mdx | 538 ++++++++++++++++++ 1 file changed, 538 insertions(+) diff --git a/src/pages/management/configuration-api/v3.6/index.mdx b/src/pages/management/configuration-api/v3.6/index.mdx index b2d75f8d7..61eef5944 100644 --- a/src/pages/management/configuration-api/v3.6/index.mdx +++ b/src/pages/management/configuration-api/v3.6/index.mdx @@ -37,6 +37,7 @@ All configurations set by this API will have action in system after max 2 minute | **Agents** | [`create_agent`](#create-agent) [`get_agent`](#get-agent) [`list_agents`](#list-agents) [`update_agent`](#update-agent) [`delete_agent`](#delete-agent) [`suspend_agent`](#suspend-agent) [`unsuspend_agent`](#unsuspend-agent) [`request_agent_unsuspension`](#request-agent-unsuspension) [`approve_agent`](#approve-agent) | | **Auto access** | [`add_auto_access`](#add-auto-access) [`list_auto_access`](#list-auto-access) [`delete_auto_access`](#delete-auto-access) [`update_auto_access`](#update-auto-access) | | **Bots** | [`create_bot_template`](#create-bot-template) [`create_bot`](#create-bot) [`delete_bot_template`](#delete-bot-template) [`delete_bot`](#delete-bot) [`update_bot_template`](#update-bot-template) [`update_bot`](#update-bot) [`list_bot_templates`](#list-bot-templates) [`get_bot`](#get-bot) [`list_bots`](#list-bots) [`issue_bot_token`](#issue-bot-token) [`reset_bot_template_secret`](#reset-bot-template-secret) [`reset_bot_secret`](#reset-bot-secret) | +| **Greetings** | [`create_greeting`](#create-greeting), [`update_greeting`](#update-greeting), [`delete_greeting`](#delete-greeting), [`list_greetings`](#list-greetings), [`get_greeting`](#get-greeting) | | **Groups** | [`create_group`](#create-group) [`get_group`](#get-group) [`list_groups`](#list-groups) [`update_group`](#update-group) [`delete_group`](#delete-group) | | **Properties** | [`register_properties`](#register-properties) [`unregister_properties`](#unregister-properties) [`publish_properties`](#publish-properties) [`list_properties`](#list-properties) [`update_license_properties`](#update-license-properties) [`delete_license_properties`](#delete-license-properties) [`list_license_properties`](#list-license-properties) [`update_group_properties`](#update-group-properties) [`delete_group_properties`](#delete-group-properties) [`list_groups_properties`](#list-groups-properties) | | **Tags** | [`create_tag`](#create-tag) [`delete_tag`](#delete-tag) [`list_tags`](#list-tags) [`update_tag`](#update-tag) | @@ -1853,6 +1854,543 @@ curl -X POST \ +# Greetings + +Greetings let you manage your campaigns. + +## Methods + +| HTTP method | The Greetings API endpoint | +| ----------- | ---------------------------------------------------------------- | +| `POST` | `https://api.livechatinc.com/v3.6/configuration/action/` | + +| Required header | Value | +| --------------- | ------------------ | +| `Content-Type` | `application/json` | + +
+ + + +### Create Greeting + +Creates a new greeting with specified parameters within a license. + +#### Specifics + +| | | +| -------------------------------- | ----------------------------------------------------------------------- | +| Method URL | `https://api.livechatinc.com/v3.6/configuration/action/create_greeting` | +| Required scopes | `greetings:rw` | +| [Batch support](#batch-requests) | No | + +#### Request + +| Parameter | Data type | Required | Notes | +| ---------------------------------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------- | +| `type`**1** | `string` | Yes | Greeting type | +| `active` | `bool` | Yes | Whether the greeting is active | +| `active_from` | `string` | No | RFC 3339 date-time format; when the greeting becomes active | +| `active_until` | `string` | No | RFC 3339 date-time format; when the greeting stops being active | +| `name` | `string` | Yes | Greeting name | +| `group` | `int` | Yes | Group ID the greeting belongs to; the group must exist | +| `rules`**2** | `object[]` | Yes | Array of action rules that define when the greeting should be triggered; at least one rule is required | +| `rules[].condition`**3**| `string` | Yes | Logical condition for the rule | +| `rules[].type`**4** | `string` | Yes | Type of rule condition | +| `rules[].operator`**5** | `string` | No | Comparison operator for the rule (required for most types, not required for `url_funnel`, `custom_variable`, `ads_traffic`) | +| `rules[].value` | `string` | No | Value to compare against (required for most rule types, see type-specific requirements in **4**) | +| `rules[].urls` | `object[]` | No | Array of URLs (required only for `url_funnel` type - must contain 1-10 URL objects) | +| `rules[].urls[].url` | `string` | Yes | URL for funnel rule (required when `urls` array is used) | +| `rules[].urls[].operator`**5** | `string` | Yes | Operator for URL comparison (required when `urls` array is used) | +| `rules[].session_field` | `object` | No | Key-value pairs (required for `custom_variable` and `ads_traffic` types - exactly one element, see type-specific requirements in **4**) | +| `properties`**6** | `object` | No | Additional properties for the greeting as key-value pairs | +| `rich_message`**7** | `object` | No | Rich message content of the greeting | + +**1)** Possible values for the `type` parameter: + +| Possible value | Notes | +| -------------- | --------------------------------------- | +| `normal` | Standard greeting type | +| `announcement` | Announcement-style greeting | + +**2)** Rules validation: +- At least one rule is required +- Maximum 10 rules per condition type allowed + +**3)** Possible values for the `rules[].condition` parameter: + +| Possible value | Notes | +| -------------- | --------------------------------------- | +| `and` | All conditions must be met | +| `or` | Any condition can be met | + +**4)** Parameter requirements for each `rules[].type` value: + +| Type value | Required Parameters | Parameter Details | +| ------------------ | ------------------- | ---------------------------------------------------------------------------------------------------------- | +| `visit_time_site` | `value`, `operator` | `value` must be integer 0-900 (seconds spent on entire website) | +| `visit_time_page` | `value`, `operator` | `value` must be integer 0-900 (seconds spent on current page) | +| `url_current` | `value`, `operator` | `value` contains current page URL to match | +| `url_visited` | `value`, `operator` | `value` contains previously visited URL to match | +| `url_funnel` | `urls` | `urls` array with 1-10 URL objects, each with `url` and `operator`. No `operator` parameter required at rule level | +| `pages_view_number`| `value`, `operator` | `value` contains number of pages viewed to compare | +| `url_referrer` | `value`, `operator` | `value` contains referrer URL to match | +| `geolocation` | `value`, `operator` | `value` contains geographic location to match | +| `visits_number` | `value`, `operator` | `value` contains number of visits to compare | +| `search_keyword` | `value`, `operator` | `value` contains search keyword to match | +| `custom_variable` | `session_field` | `session_field` object with exactly one key-value pair (max 255 characters each). No `operator` required | +| `ads_traffic` | `session_field` | `session_field` with one key from: `microsoft`, `facebook`, `google`, `twitter`, `yahoo` (value max 255 chars) | + +**5)** Possible values for the `rules[].operator` and `rules[].urls[].operator` parameters: + +| Possible value | Notes | +| ------------------ | --------------------------------------- | +| `equals` | Exact match | +| `doesnt_equal` | Does not match | +| `lower_than` | Less than | +| `lower_or_equal` | Less than or equal to | +| `greater_than` | Greater than | +| `greater_or_equal` | Greater than or equal to | +| `contains` | Contains substring | +| `doesnt_contain` | Does not contain substring | + +**6)** Possible values for the `properties` object keys: + +| Possible value | Notes | +| --------------------------- | --------------------------------------- | +| `addon` | Addon-related property | +| `is_exit_intent` | Exit intent detection flag | +| `greeting-message_text` | Plain text message content | +| `greeting-message_json_key` | JSON key for message content | +| `greeting-message_phrase_key` | Phrase key for message content | + +**7)** The `rich_message` object structure: + +| Parameter | Required | Data type | Notes | +| --------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `template_id` | yes | `string` | Defines how every Rich Message will be presented. Values: `cards`, `sticker`, or `quick_replies`. | +| `elements` | no | `array` | Can contain up to 10 `element` objects. | +| `elements[].title` | yes | `string` | Displays formatted text on RMs. | +| `elements[].subtitle` | yes | `string` | Displays formatted text on RMs. | +| `elements[].image` | yes | `object` | Displays images on RMs. Required param: `url`; Optional params: `name`, `content_type`, `size`, `width`, `height`, `alternative_text`. | +| `elements[].image.url` | yes | `string` | Image URL | +| `elements[].image.alternative_text` | no | `string` | Alternative text for the image | +| `elements[].buttons` | no | `array` | Displays buttons. Can contain up to 13 `button` objects. | +| `elements[].buttons[].text` | yes | `string` | Text displayed on a button. | +| `elements[].buttons[].type` | yes | `string` | Defines the behavior after a user clicks the button. Should be used together with `elements.buttons.value`. Possible values: `webview`, `message`, `url`, `phone`. [More...](/extending-chat-widget/rich-messages/#getting-started) | +| `elements[].buttons[].value` | yes | `string` | Should be used together with `elements.buttons.type`. You can use this field to give the rich message of a `webview` type (a Moment) a custom title. [More...](/extending-chat-widget/chat-widget-moments/#how-to-start) | +| `elements[].buttons[].postback_id` | yes | `string` | A description of the sent action. Describes the action sent via `send_rich_message_postback`. [More...](/extending-chat-widget/rich-messages/#getting-started) | +| `elements[].buttons[].role`**1** | no | `string` | Button role. | + + +**1)** Possible values for the `elements[].buttons[].role` parameter: + +| Possible value | Notes | +| -------------- | --------------------------------------- | +| `default` | | +| `primary` | | +| `danger` | | + + +#### Response + +| Field | Data type | Notes | +| ----- | --------- | -------------------------------- | +| `id` | `int` | ID of the newly created greeting | + + + + + + + +```shell +curl -X POST \ + https://api.livechatinc.com/v3.6/configuration/action/create_greeting \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "type": "normal", + "active": true, + "active_from": "2024-01-01T00:00:00Z", + "active_until": "2024-12-31T23:59:59Z", + "name": "Welcome greeting", + "group": 0, + "rules": [ + { + "condition": "and", + "type": "url_current", + "operator": "contains", + "value": "checkout" + }, + { + "condition": "or", + "type": "visit_time_site", + "operator": "greater_than", + "value": "30" + } + ], + "properties": { + "addon": "chat_widget", + "is_exit_intent": "false" + }, + "rich_message": { + "template_id": "text", + "elements": [ + { + "title": "Welcome to our website!", + "subtitle": "How can we help you today?" + } + ] + } + }' +``` + + + + + + + +
+ +
+ + + +### Update Greeting + +Updates the properties of a greeting specified by `id`. + +#### Specifics + +| | | +| -------------------------------- | ----------------------------------------------------------------------- | +| Method URL | `https://api.livechatinc.com/v3.6/configuration/action/update_greeting` | +| Required scopes | `greetings:rw` | +| [Batch support](#batch-requests) | No | + +#### Request + +| Parameter | Data type | Required | Notes | +| ---------------------------------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------- | +| `id` | `int` | Yes | ID of the greeting to update | +| `active` | `bool` | No | Whether the greeting is active | +| `active_from` | `string` | No | RFC 3339 date-time format; when the greeting becomes active | +| `active_until` | `string` | No | RFC 3339 date-time format; when the greeting stops being active | +| `name` | `string` | No | Greeting name (cannot be empty if provided) | +| `rules` | `object[]` | No | Array of action rules; see [Create Greeting rules documentation](#create-greeting) for detailed structure and validation | +| `properties` | `object` | No | Additional properties; see [Create Greeting properties documentation](#create-greeting) for allowed keys | +| `rich_message` | `object` | No | Rich message content; see [Create Greeting rich_message documentation](#create-greeting) for complete structure | + +#### Notes + +- All parameters except `id` are optional - you can update only the fields you want to change +- The `type` and `group` fields cannot be updated after greeting creation +- Rule validation, property keys, and rich message structure follow the same requirements as [Create Greeting](#create-greeting) +- If `name` is provided, it cannot be empty +- If `rules` array is provided, it must contain at least one rule and follow all validation rules from Create Greeting + +#### Response + +No response payload (`200 OK`). + + + + + + + +```shell +curl -X POST \ + https://api.livechatinc.com/v3.6/configuration/action/update_greeting \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "id": 123, + "active": false, + "name": "Updated welcome greeting", + "rules": [ + { + "condition": "and", + "type": "url_current", + "operator": "contains", + "value": "product" + } + ], + "properties": { + "addon": "chat_widget", + "is_exit_intent": "true" + }, + "rich_message": { + "template_id": "text", + "elements": [ + { + "title": "Updated greeting message!", + "subtitle": "Can we help you find a product?" + } + ] + } + }' +``` + + + + + +
+ +
+ + + +### Delete Greeting + +Deletes a greeting specified by `id`. + +#### Specifics + +| | | +| -------------------------------- | ----------------------------------------------------------------------- | +| Method URL | `https://api.livechatinc.com/v3.6/configuration/action/delete_greeting` | +| Required scopes | `greetings:rw` | +| [Batch support](#batch-requests) | No | + +#### Request + +| Parameter | Data type | Required | Notes | +| --------- | --------- | -------- | ------------------------------ | +| `id` | `int` | Yes | ID of the greeting to delete | + +#### Response + +No response payload (`200 OK`). + + + + + + + +```shell +curl -X POST \ + https://api.livechatinc.com/v3.6/configuration/action/delete_greeting \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "id": 123 + }' +``` + + + + + +
+ +
+ + + +### List Greetings + +Returns a list of greetings, optionally filtered by groups. The method supports pagination to handle large result sets. + +#### Specifics + +| | | +| -------------------------------- | ---------------------------------------------------------------------- | +| Method URL | `https://api.livechatinc.com/v3.6/configuration/action/list_greetings` | +| Required scopes | `greetings:ro` | +| [Batch support](#batch-requests) | No | + +#### Request + +| Parameter | Data type | Required | Default | Notes | +| ---------- | --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `groups` | `array` | No | All groups | Array of group IDs to filter greetings. Must contain non-negative integers. Cannot be used with `page_id`. | +| `page_id` | `string` | No | - | Page ID for pagination. When provided, `groups` and `limit` parameters are ignored as they're encoded in the page ID. Cannot be used with `groups` or `limit`. | +| `limit` | `int` | No | `100` | Number of greetings per page. Must be between 1 and 100. Cannot be used with `page_id`. | + +#### Response + +| Field | Data type | Notes | +| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------ | +| `greetings` | `array` | Array of greeting objects. See [Create Greeting](#create-greeting) for the structure of greeting objects. | +| `found_greetings` | `int` | Total number of greetings found (not just in current page). | +| `next_page_id` | `string` | Page ID for the next page of results. Only present if there are more results available. | + + + + + + + +```shell +curl -X POST \ + https://api.livechatinc.com/v3.6/configuration/action/list_greetings \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "groups": [0, 1], + "limit": 25 + }' +``` + + + + + +```json +{ + "greetings": [ + { + "id": 123, + "type": "normal", + "active": true, + "name": "Welcome greeting", + "group": 0, + "rules": [ + { + "condition": "and", + "type": "visit_time_site", + "operator": "greater_than", + "value": "10" + } + ], + "properties": { + "text": "Hello! How can I help you today?" + }, + "rich_message": { + "elements": [ + { + "title": "Welcome!", + "subtitle": "How can we help you today?", + "buttons": [ + { + "text": "Get Support", + "type": "message", + "value": "I need support", + "postback_id": "support_request" + } + ] + } + ] + } + } + ], + "found_greetings": 1 +} +``` + + + + + +
+ +
+ + + +### Get Greeting + +Returns details of a specific greeting by its ID. + +#### Specifics + +| | | +| -------------------------------- | --------------------------------------------------------------------- | +| Method URL | `https://api.livechatinc.com/v3.6/configuration/action/get_greeting` | +| Required scopes | `greetings:ro` | +| [Batch support](#batch-requests) | No | + +#### Request + +| Parameter | Data type | Required | Notes | +| --------- | --------- | -------- | -------------------------- | +| `id` | `int` | Yes | ID of the greeting to get | + +#### Response + +Returns a greeting object with the same structure as described in [Create Greeting](#create-greeting), plus the `id` field. + +| Field | Data type | Notes | +| --------------- | --------- | -------------------------------------------------------------------------- | +| `id` | `int` | Greeting ID. | +| `type` | `string` | Greeting type (`normal` or `announcement`). | +| `active` | `boolean` | Whether the greeting is active. | +| `active_from` | `string` | ISO 8601 datetime when the greeting becomes active (if set). | +| `active_until` | `string` | ISO 8601 datetime when the greeting stops being active (if set). | +| `name` | `string` | Greeting name. | +| `group` | `int` | ID of the group the greeting belongs to. | +| `rules` | `array` | Array of rule objects. See [Create Greeting](#create-greeting) for details. | +| `properties` | `object` | Additional properties. See [Create Greeting](#create-greeting) for details. | +| `rich_message` | `object` | Rich message content. See [Create Greeting](#create-greeting) for details. | + + + + + + + +```shell +curl -X POST \ + https://api.livechatinc.com/v3.6/configuration/action/get_greeting \ + -H 'Authorization: Bearer ' \ + -H 'Content-Type: application/json' \ + -d '{ + "id": 123 + }' +``` + + + + + +```json +{ + "id": 123, + "type": "normal", + "active": true, + "name": "Welcome greeting", + "group": 0, + "rules": [ + { + "condition": "and", + "type": "visit_time_site", + "operator": "greater_than", + "value": "10" + } + ], + "properties": { + "text": "Hello! How can I help you today?" + }, + "rich_message": { + "elements": [ + { + "title": "Welcome!", + "subtitle": "How can we help you today?", + "buttons": [ + { + "text": "Get Support", + "type": "message", + "value": "I need support", + "postback_id": "support_request" + } + ] + } + ] + } +} +``` + + + + + +
+ # Groups Groups let you organize your work by creating teams with Agent and Bot members. You can use groups to do configuration based on shared settings (language, working hours, department) and to separate chat routing. It's worth mentioning that one Agent can belong to multiple groups at the same time. It's possible to configure routing priorities for Agents and Bots specifically per group. From 713d206e4a9dfc1ef8626ea53ba38b030449c6e5 Mon Sep 17 00:00:00 2001 From: Marcin Dojwa Date: Wed, 18 Jun 2025 17:03:48 +0200 Subject: [PATCH 2/3] fix: groups param default description --- src/pages/management/configuration-api/v3.6/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/pages/management/configuration-api/v3.6/index.mdx b/src/pages/management/configuration-api/v3.6/index.mdx index 61eef5944..4f350b99f 100644 --- a/src/pages/management/configuration-api/v3.6/index.mdx +++ b/src/pages/management/configuration-api/v3.6/index.mdx @@ -2208,7 +2208,7 @@ Returns a list of greetings, optionally filtered by groups. The method supports | Parameter | Data type | Required | Default | Notes | | ---------- | --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `groups` | `array` | No | All groups | Array of group IDs to filter greetings. Must contain non-negative integers. Cannot be used with `page_id`. | +| `groups` | `array` | No | All accesible groups | Array of group IDs to filter greetings. Cannot be used with `page_id`. | | `page_id` | `string` | No | - | Page ID for pagination. When provided, `groups` and `limit` parameters are ignored as they're encoded in the page ID. Cannot be used with `groups` or `limit`. | | `limit` | `int` | No | `100` | Number of greetings per page. Must be between 1 and 100. Cannot be used with `page_id`. | From 3f2bbf552352fc5b6b4573e8800f4099340290a9 Mon Sep 17 00:00:00 2001 From: Marcin Dojwa Date: Fri, 18 Jul 2025 20:24:14 +0200 Subject: [PATCH 3/3] fix: update greeting postback_id docs --- src/pages/management/configuration-api/v3.6/index.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/pages/management/configuration-api/v3.6/index.mdx b/src/pages/management/configuration-api/v3.6/index.mdx index 4f350b99f..9b5354b3c 100644 --- a/src/pages/management/configuration-api/v3.6/index.mdx +++ b/src/pages/management/configuration-api/v3.6/index.mdx @@ -1977,10 +1977,10 @@ Creates a new greeting with specified parameters within a license. | `elements[].image.alternative_text` | no | `string` | Alternative text for the image | | `elements[].buttons` | no | `array` | Displays buttons. Can contain up to 13 `button` objects. | | `elements[].buttons[].text` | yes | `string` | Text displayed on a button. | -| `elements[].buttons[].type` | yes | `string` | Defines the behavior after a user clicks the button. Should be used together with `elements.buttons.value`. Possible values: `webview`, `message`, `url`, `phone`. [More...](/extending-chat-widget/rich-messages/#getting-started) | +| `elements[].buttons[].type` | yes | `string` | Defines the behavior after a user clicks the button. Should be used together with `elements.buttons.value`. Possible values: `webview`, `message`, `url`, `phone`. [More...](/extending-chat-widget/rich-messages/#getting-started) | | `elements[].buttons[].value` | yes | `string` | Should be used together with `elements.buttons.type`. You can use this field to give the rich message of a `webview` type (a Moment) a custom title. [More...](/extending-chat-widget/chat-widget-moments/#how-to-start) | -| `elements[].buttons[].postback_id` | yes | `string` | A description of the sent action. Describes the action sent via `send_rich_message_postback`. [More...](/extending-chat-widget/rich-messages/#getting-started) | -| `elements[].buttons[].role`**1** | no | `string` | Button role. | +| `elements[].buttons[].postback_id` | yes | `string` | A unique (in the whole greeting) ID of the button. It will be used to report the button actions using [`send_greeting_postback`](/messaging/customer-chat-api/v3.6/#send-greeting-postback) | +| `elements[].buttons[].role`**1** | no | `string` | Button role. | **1)** Possible values for the `elements[].buttons[].role` parameter: