Rules API

Rules¶

Rule resource has the following attributes:

Attribute	Type	Description
`id`	UUID	Unique identifier for the rule.
`name`	string	Name of the rule.
`organization`	object	The organization resource where the rule is configured.
`organization_id`	UUID	ID of the organization where the rule is configured.
`conditions`	array of objects	Ordered list of conditions of the rule. The list order defines the matching order.
`actions`	array of objects	Ordered list of actions of the rule. The list order defines the execution order.
`rooms`	array of objects	A list of rooms where the rule can be triggered. Rooms can only be set if `is_global` is `false`.
`room_ids`	array of UUIDs	A list of IDs of rooms where the rule can be triggered.
`is_global`	boolean	Whether the rule can be triggered in all of the organization's rooms. If this is `true`, `rooms` list should be empty. Defaults to `false`.
`is_auto_generated`	boolean	Whether the rule was created automatically (e.g. as a part of a custom button creation or by an app) instead of being created from the Rule management UI.
`is_enabled`	boolean	Whether the rule is currently enabled. Defaults to `false`.
`is_protected`	boolean	If the rule is protected, it cannot be modified or deleted. This may be set to `true` by some automatically created rules by giosg system.
`match_once_per`	string	How often the rule can match. Choices are `page`, `session` or `visitor`. If this is `null`, the rule can match every time the conditions change or the page is loaded. Defaults to `null`.
`type`	string	Type of the rule. Choices are `normal` or `target`. Defaults to `normal`.
`goal`	object	The goal set for the rule, or `null` if not set.
`goal_id`	UUID	ID of the goal of the rule, or `null` if not set.
`created_at`	datetime	When the rule was created.
`updated_at`	datetime	When the rule was last updated.
`created_by_user`	object	The user resource who created the rule, or `null` if unknown.
`created_by_user_id`	UUID	ID of the user who created the rule, or `null` if unknown.
`updated_by_user`	object	The user resource who last updated the rule, or `null` if unknown.
`updated_by_user_id`	UUID	ID of the user who last updated the rule, or `null` if unknown.

Rule conditions¶

Rule condition object has the following attributes:

Attribute	Type	Description
`id`	UUID	Unique identifier for the rule condition.
`index`	integer	Together with other conditions' indices, defines the order in which the conditions are matched in the rule. Set automatically from the order of the conditions array.
`is_opposite`	boolean	Whether to use the default or opposite match type (when the rule should match). See the defaults and opposites in the conditions list below.
`type`	integer	Type of the condition. See condition types below.
`value`	string	The value related to the type. Required with most types. See choices below.
`settings`	object	Other condition settings. Required with some condition types.

Condition types¶

Type	Description	Match types (default / opposite)	Value	Settings
1	Visitor's city	is / is not	City name as a `string`	`null`
2	CSS selector matching elements on the web page	matches / doesn't match	CSS selector as a `string`	`null`
3	Visitor's previous URL (Regexp)	matches / doesn't match	JavaScript regular expression as a `string`	`null`
4	Visitor's source URL (Regexp)	matches / doesn't match	JavaScript regular expression as a `string`	`null`
5	Visitor's URL (Regexp)	matches / doesn't match	JavaScript regular expression as a `string`	`null`
6	Visitor's country	is / is not	Country name as a `string`	`null`
7	Number of visits	is more than / is less than	Visit count as an `integer`	`null`
8	Shopping cart value	is more than / is less than	Cart value as a `float` with two decimals	`null`
10	Products in shopping cart	include / doesn't include	Product name as a `string`	`null`
11	Pipeline step number	is / is not	Pipeline step as an `integer`	`null`
12	Evaluate JavaScript expression	expression is true / expression is false	JavaScript expression as a `string`	`null`
14	Number of purchases	is more than / is less than	Number of purchases as an `integer`	`null`
15	Visitor's IP address (Regexp)	matches / doesn't match	JavaScript regular expression as a `string`	`null`
16	Visitor's URL	contains / doesn't contain	Part of the URL as a `string`	`null`
17	Agent online presence	when / when not	Either `online` (meaning any agent is online) or `offline` (all agents are offline)	`null`
18	Number of seconds on the page	more than / less than	Number of seconds as an `integer`	`null`
19	Visitor clicks on an element matching a CSS selector		CSS selector as a `string`	`null`
20	Visitor clicks a custom button		ID of the custom button object	`null`
21	Visitor's device	is / is not	`desktop` or `mobile` or `tablet` or `mobile,tablet`	`null`
22	Weekly schedule	during the interval / outside the interval	`null`	array of schedule objects (see object below)
23	Visitor's priority	is more than / is less than	Priority value as an `integer` (1-10)	`null`
25	Visitor was targeted		`null`	`null`
26	Visitor purchased shopping cart content		`null`	`null`
27	Visitor sent a lead form		`null`	`null`
28	Visitor's previous URL	contains / doesn't contain	Part of the URL as a `string`	`null`
29	Visitor's source URL	contains / doesn't contain	Part of the URL as a `string`	`null`
30	Number of seconds waiting for an answer		Number of seconds as an `integer`	`null`
31	Visitor has chatted		`null`	{ "isOnlyForRealChats": boolean }, default is `false`
32	Chat has at least one of tags		List of tag IDs	`null`
33	Visitor belongs to a target experiment group		Target experiment group as a `string` (Note: requires "Target" feature(s))	`null`
34	Number of seconds waiting for the first answer		Number of seconds as an `integer`	`null`
35	Visitor belongs to a user experiment group		User experiment group as a `string`	`null`
36	AI prediction (Target) conversion probability	is more than / is less than	Conversion probability % as a `float` (0-100)	`null`

Weekly schedule object¶

Attribute	Type	Description
`intervals`	array of interval objects	Start weekday and time and end day and time for each interval. See interval object below
`timezone`	`string`	See Time zones API for supported values

Interval object¶

Attribute	Type	Description
`start_day`	`integer`	Number of the weekday (`1-7`), Monday is `1`
`start_hours`	`integer`	Hours from `00` to `23`
`start_minutes`	`integer`	Minutes from `00` to `59`
`end_day`	`integer`	Number of the weekday (`1-7`), Monday is `1`
`end_hours`	`integer`	Hours from `00` to `23`
`end_minutes`	`integer`	Minutes from `00` to `59`

Example weekly schedule object:

{
  "intervals": [
    {
      "start_day": 1,
      "start_hours": 08,
      "start_minutes": 00,
      "end_day": 5,
      "end_hours": 16,
      "end_minutes": 00
    },
    {
      "start_day": 6,
      "start_hours": 09,
      "start_minutes": 30,
      "end_day": 7,
      "end_hours": 18,
      "end_minutes": 00
    }
  ],
  "timezone": "Europe/Helsinki"
}

Rule actions¶

Rule action object has the following attributes:

Attribute	Type	Description
`id`	UUID	Unique identifier for the rule action.
`index`	integer	Together with other actions' indices, defines the order in which the actions are executed. Set automatically from the order of the actions array.
`type`	integer	Type of the action. See choices below.
`value`	string/integer	The value related to the type. Required with most types. See choices below.
`settings`	object	Other action settings. Required with some types.

Action types¶

Type	Description	Value	Settings
1	Send autosuggest	Autosuggest message as a `string`	{ autosuggest_user_id: UUID, close_delay: `integer` (seconds) }
2	Join room(s)	Array of room UUIDs	`null`
5	Disable chat button	`null`	`null`
6	Disable autosuggest	`null`	`null`
7	Run a custom JavaScript	JavaScript expression as a `string`	`null`
8	Enable chat button	`null`	`null`
9	Show elements matching CSS selector	CSS selector as a `string`	`null`
10	Hide elements matching CSS selector	CSS selector as a `string`	`null`
11	Redirect to a web page	URL as a `string`	`null`
13	Show chat button when agents are offline and use lead form	Lead form UUID	`null`
14	Change chat button text	Button text as a `string`	`null`
15	Change chat button target room	Room UUID	`null`
16	Change chat window language	Language as a RFC 3066 code. See supported languages.	`null`
17	Show a lead form	Lead form UUID	`null`
18	Use a lead form processor	Lead form processor UUID	`null`
19	Show custom button	Button UUID	`null`
20	Open chat window	UUID of the parent room of the window	`null`
21	Set visitor priority	Priority as an `integer` (1-10)	`null`
22	Disable autosuggest capacity check	`null`	`null`
23	Apply CSS to the web page	CSS code as a `string`	`null`
24	Load Interaction Designer element	UUID of the element asset	`null`
25	Send chat message	Message as a `string`	{ sender_public_name: `string` }
26	Load interaction	UUID of the interaction	`null`
27	Send chat message	UUID of the interaction	{ sender_public_name: `string`, message: `string` }

Create a new rule¶

You can create a new rule:

POST /api/v5/orgs/<organization_id>/rules

Attribute	Required	Default
`name`	required
`actions`	required
`conditions`	optional	[]
`room_ids`	optional	[]
`is_global`	optional	`false`
`match_once_per`	optional	`null`
`goal_id`	optional	`null`
`type`	optional	`normal`

Note! If is_global is set to true, you can't set room_ids. Note! If type is target and is_global is false, the rule has to have at least one room. Note! The amount of rules may be limited by your customership.

This endpoint returns:

201 if a new rule was created successfully
400 if required attributes are missing
400 if payload attributes are in wrong format
401 if you are not authenticated
402 if your organization has reached the maximum amount of rules
403 if you do not have access to the organization
403 if you do not have active subscription
403 if you do not have settings permission

Example request:

POST https://service.giosg.com/api/v5/orgs/ab7d649a-dfca-4677-b0de-66f8ed8d2c46/rules

Example payload:

{
  "name": "Show chat button",
  "conditions": [
    {
      "type": 21,
      "value": "desktop"
    },
    {
      "is_opposite": true,
      "type": 2,
      "value": "#block-chat"
    }
  ],
  "actions": [
    {
      "type": 19,
      "value": "9056c957-59df-11e9-aa2e-f218983c3266",
      "settings": {}
    }
  ],
  "room_ids": [
    "ba85ce76-99f6-4ed3-8cb2-e22a0d12c513",
    "f4cd6ad7-9072-11e6-84ab-f45c89c72de3"
  ],
  "is_enabled": true
}

Example response:

{
  "name": "Show chat button",
  "conditions": [
    {
      "id": "767be7fd-59df-11e9-ad5e-f218983c3266",
      "index": 0,
      "is_opposite": false,
      "type": 21,
      "value": "desktop",
      "settings": {}
    },
    {
      "id": "7ce47c3a-59df-11e9-a855-f218983c3266",
      "index": 1,
      "is_opposite": true,
      "type": 2,
      "value": "#block-chat",
      "settings": {}
    }
  ],
  "actions": [
    {
      "id": "821c72fd-59df-11e9-97e2-f218983c3266",
      "index": 0,
      "type": 19,
      "value": "48073dae-5a98-11e9-a2e7-f218983c3266",
      "settings": {}
    }
  ],
  "room_ids": [
    "ba85ce76-99f6-4ed3-8cb2-e22a0d12c513",
    "f4cd6ad7-9072-11e6-84ab-f45c89c72de3"
  ],
  "is_global": false,
  "is_auto_generated": false,
  "is_enabled": true,
  "is_protected": false,
  "match_once_per": null,
  "goal_id": null,
  "goal": null,
  "type": "normal",
  "created_at": "2016-09-01T11:31:36.042Z",
  "updated_at": "2016-09-01T11:31:36.042Z",
  "created_by_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
  "created_by_user": {
    "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
    "full_name": "Bill Giosg",
    "first_name": "Bill",
    "last_name": "Giosg",
    "organization_id": "ab7d649a-dfca-4677-b0de-66f8ed8d2c46",
    "is_bot": false
  },
  "updated_by_user": {
    "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
    "full_name": "Bill Giosg",
    "first_name": "Bill",
    "last_name": "Giosg",
    "organization_id": "ab7d649a-dfca-4677-b0de-66f8ed8d2c46",
    "is_bot": false
  },
  "updated_by_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e"
}

Retrieve rule¶

You can retrieve a rule:

GET /api/v5/orgs/<organization_id>/rules/<rule_id>

Update rule¶

You can update a rule:

PUT/PATCH /api/v5/orgs/<organization_id>/rules/<rule_id>

Attribute	Required
`name`	optional
`actions`	optional
`conditions`	optional
`room_ids`	optional
`is_global`	optional
`match_once_per`	optional
`goal_id`	optional
`type`	optional

Note! If is_global is set to true, you can't set room_ids. If you want to update room_ids, you also have to update is_global to false. If you want to update is_global from false to true, you have to update room list to be empty.

This endpoint returns:

200 if the rule was updated successfully
400 if payload attributes are in wrong format
400 if the rule is protected
401 if you are not authenticated
403 if you do not have access to the organization
403 if you do not have active subscription
403 if you do not have settings permission
404 if the rule was not found

Delete rule¶

You can delete a rule:

DELETE /api/v5/orgs/<organization_id>/rules/<rule_id>

This endpoint returns:

204 if the rule was deleted successfully
400 if the rule is protected
401 if you are not authenticated
403 if you do not have access to the organization
403 if you do not have active subscription
403 if you do not have settings permission
404 if the rule was not found

List rules¶

You can list rules of an organization:

GET /api/v5/orgs/<organization_id>/rules

or a room:

GET /api/v5/orgs/<organization_id>/rooms/<room_id>/rules

You can also list global rules, i.e. rules that can be triggered in all rooms:

GET /api/v5/orgs/<organization_id>/global_rules

or rules that are not triggered in any room:

GET /api/v5/orgs/<organization_id>/roomless_rules

These endpoints return:

200 if for a successful request
401 if you are not authenticated
403 if you do not have access to the organization
403 if you do not have active subscription
403 if you do not have settings permission