Visitors API

Room visitors¶

A visitor has a separate representation for each room. The returned attributes are different depending on from which room the visitor was requested.

Warning

NOTE that all the metadata may not be available at the time of a request. In that case, they will be null. An appropriate notification will be sent via channels when the information becomes available.

Attribute	Type	Description
`id`	string	Unique identifier for the visitor. This is the same for the same visitor regardless of the room from which the visitor was requested.
`room_id`	UUID	ID of the room from which this room visitor resource was requested
`is_present`	boolean	Whether or not the visitor is currently present in the room
`session_id`	string	Identifier for the latest session for the visitor in this room
`explicit_priority`	number	The latest priority of the visitor as set explicitly with rules. It may be `null` if the visitor has not been prioritized with rules.
`implicit_priority`	number	The latest priority automatically calculated for the visitor.
`visit_count`	integer	During how many distinct sessions the visitor has been active on this room.
`device_type`	string	Either `desktop`, `mobile` or `tablet`
`device_screen_width`	integer	The width resolution of the visitor's screen in pixels
`device_screen_height`	integer	The height resolution of the visitor's screen in pixels
`browser_name`	string	Name of the browser which the visitor is currently using, without any version number.
`browser_version`	string	Version of the browser which the visitor is currently using.
`browser_language`	string	The preferred languages of the visitor as sent by the browser as the Accept-Language HTTP header. E.g. `fi-FI,fi;q=0.8,en-US;q=0.6,en;q=0.4`. In most cases it is more convenient to use `preferred_language_code` instead.
`preferred_language_code`	string	The ISO code of the most preferred language of the visitor, e.g. `fi` or `en-US`
`os_name`	string	Name of the operating system which the visitor is using, without any version number.
`os_version`	string	Version of the operating system which the visitor is using
`user_agent`	string	User-Agent header of the visitor browser
`ip_address`	string	IP address of the visitor (IPv4)
`ip_organization`	string	An organization name resolved from the IP address
`geo_city`	string	The best guess about the name of the city where the visitor is currently located. This is usually resolved from their IP address.
`geo_country_code`	string	The best guess about the country where the visitor is currently located. This is usually resolved from their IP address. This is a upper-case, two-letter ISO 3166-1 country code
`geo_country`	string	The country as in `country_code`, but represented as the name of the country.
`referrer_url`	string	The full URL from which the visitor entered the room during this session
`referrer_url_hostname`	string	Hostname from which the visitor entered the room during this session
`referrer_medium`	string	Either `internal`, `search`, `email`, `social`, or `website`
`referrer_source`	string	The name of the referrer source
`original_referrer_url`	string	The full URL from which the visitor originally entered the room
`original_referrer_url_hostname`	string	Hostname from which the visitor originally entered the room
`original_referrer_medium`	string	Either `internal`, `search`, `email`, `social`, or `website`
`original_referrer_source`	string	The name of the original referrer source
`page_title`	string	Title of the web page at which the visitor is currently, at this room.
`page_url`	string	URL of the web page at which the visitor is currently, at this room.
`canonical_page_url`	string	Canonical URL of the web page at which the visitor is currently, at this room. Same than `page_url` if no canonical URL is available.
`session_started_at`	date/time	When the latest session of the visitor has started at this particular room.
`updated_at`	date/time	When the information of the room visitor was updated last time. In practice, this means when we have heard about the visitor last time at this particular room.
`session_duration`	number	An estimated duration of the visitor's session at the moment, in seconds, possibly with fractions. This is equivalent to the difference between `session_started_at` and `updated_at`.
`chat_count`	number	The number of chats this visitor has at this particular room.
`shopping_cart_currency`	string	The currency of the visitor's shopping cart in the room, if the visitor has any, otherwise `null`. Currency is a upper-case ISO 4217 currency code, e.g. `EUR`.
`shopping_cart_total_value`	string	The total value of the visitor's shopping cart in the room, if the visitor has any. Value `null` means the shopping cart is not defined. The value is presented as a decimal string, e.g. `59.00` in the currency defined by `shopping_cart_currency`.
`shopping_cart_total_subscription_value`	string	The total monthly subscription value of the visitor's shopping cart in the room, if the visitor has any. Value `null` means the shopping cart is not defined. The value is presented as a decimal string, e.g. `59.00` in the currency defined by `shopping_cart_currency` and per month.
`shopping_cart_locked_at`	datetime	When the visitor checked out their shopping cart in this room. It is `null` if the cart is not yet checked out or the cart is not defined.
`session_autosuggested_at`	datetime	When the visitor was autosuggested in this room. It is `null` if the visitor was not autosuggested or the autosuggest happened over 5 minutes ago.

Get a single room visitor¶

Returns the details of a single visitor at the given room.

GET /api/v5/orgs/<org_id>/rooms/<room_id>/visitors/<visitor_id>

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have settings permission
404 if the room was not found
404 if the visitor was not found
404 if no visitor information is found for a valid visitor ID

Warning

It is not guaranteed that the visitor information is available for very old visitors. If the visitor information has been removed, then this returns a 404 response.

Get user's single room visitor¶

Returns the details of user's single visitor at the given room.

GET /api/v5/users/<user_id>/rooms/<room_id>/visitors/<visitor_id>

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the user
404 if the visitor was not found
404 if the room was not found
404 if no visitor information is found for a valid visitor ID

Get a single visitor of user's chat¶

Returns the details of user's single visitor at the given room.

GET /api/v5/users/<user_id>/chats/<chat_id>/visitors/<visitor_id>

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the user
404 if the visitor was not found
404 if the chat was not found
404 if no visitor information is found for a valid visitor ID

List room priority visitors¶

Returns a paginated collection of the most important room visitors currently present at the room.

GET /api/v5/orgs/<org_id>/rooms/<room_id>/priority_visitors

The maximum number of returned visitors is not guaranteed, but it is usually around 30 - 50. If you want to limit the number of visitor e.g. shown in your user interface, then you need to limit the number on your client. Please note that the visitors may be returned in multiple pages.

If there is only a few visitors currently present at the room, then all of them are returned.

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have settings permission
404 if the room was not found

List user's room priority visitors¶

Returns a paginated collection of the most important user's room visitors currently present at the room.

GET /api/v5/users/<user_id>/rooms/<room_id>/priority_visitors

The maximum number of returned visitors is not guaranteed, but it is usually around 30 - 50. If you want to limit the number of visitor e.g. shown in your user interface, then you need to limit the number on your client. Please note that the visitors may be returned in multiple pages.

If there is only a few visitors currently present at the room, then all of them are returned.

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the user
404 if the room was not found

Room visitor page views¶

A room visitor page view object represents the visitor's page view at a specific room.

It has the following attributes:

Attribute	Type	Description
`created_at`	datetime	When the visitor visited the page.
`room_id`	UUID	ID of the room from which this room visitor page view resource was requested.
`visitor_id`	string	Unique identifier for the visitor. This is the same for the same visitor regardless of the room from which the visitor was requested.
`session_id`	string	In which session the visitor visited the page.
`page_title`	string	Title of the web page at which the visitor visited.
`page_url`	string	URL of the web page at which the visitor visited.
`canonical_page_url`	string	Canonical URL of the web page at which the visitor visited.

List room visitor page views¶

You can get a paginated collection of all the page views of the room visitor, at this room.

GET /api/v5/users/<user_id>/rooms/<room_id>/visitors/<visitor_id>/pageviews

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the user
404 if the room was not found
404 if the visitor was not found

Warning

It is not guaranteed that the visitor page view information is available for very old visitors. If the visitor page view information has been removed, then this returns a 404 response.

List room visitor page views of user's chat¶

You can get a paginated collection of all the page views of the room visitor, at the room of the user's chat.

GET /api/v5/users/<user_id>/chats/<chat_id>/visitors/<visitor_id>/pageviews

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the user
404 if the chat was not found
404 if the visitor was not found

Warning

It is not guaranteed that the visitor page view information is available for very old visitors. If the visitor page view information has been removed, then this returns a 404 response.

Room visitor variables¶

Website visitors may be associated with arbitrary key-value pairs, known as variables. Both keys and values are strings. Any new variable overwrites any previous variable with the same key. Note that variables are scoped by the room.

For example, a visitor might have a variable username set to value JohnSmith at a room named example.com. This variable only exists in this room. Another variable for the same visitor with the same key but different value may exist in another room.

To create a visitor variable which is not rendered to Giosg user interface it is possible to prefix the variable with double underscore, for example __hidden_variable. This is usefull if you want to store some data for system use but it should not be visible in the UI.

Warning

Currently key's are case-sensitive, so be thorough when creating new visitor variables.

A visitor room variable has the following attributes:

Attribute	Type	Editable	Description
`room_id`	UUID	read-only	ID of the room that is the context of this variable
`visitor_id`	string	read-only	ID of the visitor
`key`	string	required	The name of the key of the variable
`value`	string	required	The current value of the variable. This attribute is `null` if the value is encrypted and the encryption key is no longer stored on the server. In this case, you need to use `encrypted_value` and decrypt the value yourself.
`is_signed`	boolean	read-only	Whether or not the variable was signed when saved.
`is_encrypted`	boolean	read-only	Whether or not the variable value is stored encrypted.
`encrypted_value`	string	read-only	The value encrypted with the AES key if the encryption was used for this variable. This attribute is only present if `is_encrypted` is `true`.
`encrypted_symmetric_key`	string	read-only	The encrypted symmetric key (AES) with which the variable value is encrypted. This attribute is only present if `is_encrypted` is `true`.
`session_id`	string	read-only	Identifier for the session on which the variable was saved for the visitor.

List room visitor variables¶

GET https://service.giosg.com/api/v5/users/ab7d649a-dfca-4677-b0de-66f8ed8d2c46/rooms/ba85ce76-99f6-4ed3-8cb2-e22a0d12c513/visitors/817234ac40464edebd155c88139a2469/variables

[
  {
    "room_id": "16ef9670-ea07-4a21-8276-721edceda148",
    "visitor_id": "08119566026a4e1194a7a3244c90f925",
    "key": "full_name",
    "value": null,
    "is_signed": true,
    "is_encrypted": false,
    "encrypted_value": "7d4a2f83438c446eba3955db80ed0d8f",
    "encrypted_aes_key": "3fe41055efd04755a3bfed6b3df16b3b",
    "session_id": "bdbc4edb-a0f1-4011-8c57-bdeb95afdae5"
  },
  {
    "room_id": "16ef9670-ea07-4a21-8276-721edceda148",
    "visitor_id": "08119566026a4e1194a7a3244c90f925",
    "key": "username",
    "value": "JohnSmith",
    "is_signed": true,
    "is_encrypted": false,
    "encrypted_value": null,
    "encrypted_aes_key": null,
    "session_id": "48c29c06-4a7c-4774-9b42-ea63f95f0ee0"
  }
]

You can list all the variables currently associated to the given visitor at the given room, ordered by key:

GET /api/v5/users/<user_id>/rooms/<room_id>/visitors/<visitor_id>/variables.

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the user
404 if the room was not found
404 if the visitor was not found

List chat visitor variables¶

You can list all the variables currently associated to the given visitor at the given chat, ordered by key:

GET /api/v5/users/<user_id>/chats/<chat_id>/visitors/<visitor_id>/variables.

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the user
404 if the chat was not found
404 if the visitor was not found

Or alternatively:

GET /api/v5/orgs/<organization_id>/owned_chats/<chat_id>/visitors/<visitor_id>/variables.

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have settings permission
404 if the organization's owned chat was not found
404 if the visitor was not found

Or

GET /api/v5/orgs/<organization_id>/involved_chats/<chat_id>/visitors/<visitor_id>/variables.

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have settings permission
404 if the organization's involved chat was not found
404 if the visitor was not found

Or

GET /api/v5/orgs/<organization_id>/routed_chats/<chat_id>/visitors/<visitor_id>/variables.

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have settings permission
404 if the organization's involved chat was not found
404 if the visitor was not found

Or alternatively at the given room:

GET /api/v5/orgs/<organization_id>/rooms/<room_id>/visitors/<visitor_id>/variables.

This endpoint returns:

200 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have settings permission
404 if the room was not found
404 if the visitor was not found

Create a room visitor variable¶

POST /api/v5/orgs/<organization_id>/rooms/<room_id>/visitors/<visitor_id>/variables.

This endpoint returns:

201 if the request was successful
400 if required attribute is missing from the request
400 if the request payload is in wrong format
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have settings permission
404 if the room was not found
404 if the visitor was not found
404 if the key was not found

POST https://service.giosg.com/api/v5/orgs/46b22cdd-2497-4dc7-a18e-f215acade1a5/rooms/ce3fab18-e25c-4f56-81a0-8ee36825f88c/visitors/aa11b24336444111b4b49dfc7b011245/variables

{
  "key": "username",
  "value": "Jane Doe"
}

{
    "visitor_id": "aa11b24336444111b4b49dfc7b011245",
    "room_id": "ce3fab18-e25c-4f56-81a0-8ee36825f88c",
    "key": "username",
    "value": "Jane Doe",
    "session_id": "a0dda7e5-8af7-48d0-b3ea-d2047896555c",
    "created_at": "2022-02-22T11:30:12.969Z",
    "updated_at": "2022-02-22T12:41:54.040Z",
    "is_signed": true,
    "is_encrypted": false,
    "encrypted_value": null,
    "encrypted_symmetric_key": null
}

Create a chat visitor variable¶

Chat visitor variable is similar to room visitor variable, difference is that the variable is connected to only one chat instead of the room where the chat can happen. If variable is connected to room, then it will be also added to each new chats in that given room.

POST https://service.giosg.com/api/v5/users/ab7d649a-dfca-4677-b0de-66f8ed8d2c46/chats/ba85ce76-99f6-4ed3-8cb2-e22a0d12c513/visitors/817234ac40464edebd155c88139a2469/variables

{
  "key": "username",
  "value": "John Smith"
}

{
  "room_id": "16ef9670-ea07-4a21-8276-721edceda148",
  "visitor_id": "08119566026a4e1194a7a3244c90f925",
  "key": "username",
  "value": "John Smith",
  "is_signed": true,
  "is_encrypted": false,
  "encrypted_value": null,
  "encrypted_aes_key": null,
  "session_id": "48c29c06-4a7c-4774-9b42-ea63f95f0ee0"
}

You may create a new visitor variable for given visitor at the given chat:

POST /api/v5/users/<user_id>/chats/<chat_id>/visitors/<visitor_id>/variables.

This endpoint returns:

201 if the request was successful
400 if required attribute is missing from the request
400 if the request payload is in wrong format
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the user
404 if the chat was not found
404 if the visitor was not found
404 if the key was not found

Or alternatively:

POST /api/v5/orgs/<organization_id>/rooms/<room_id>/visitors/<visitor_id>/variables.

This endpoint returns:

201 if the request was successful
400 if required attribute is missing from the request
400 if the request payload is in wrong format
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have settings permission
404 if the room was not found
404 if the visitor was not found
404 if the key was not found

Update existing visitor variable¶

PUT https://service.giosg.com/api/v5/users/ab7d649a-dfca-4677-b0de-66f8ed8d2c46/chats/ba85ce76-99f6-4ed3-8cb2-e22a0d12c513/visitors/817234ac40464edebd155c88139a2469/variables/username

{
  "value": "AgentSmith"
}

{
  "room_id": "16ef9670-ea07-4a21-8276-721edceda148",
  "visitor_id": "08119566026a4e1194a7a3244c90f925",
  "key": "username",
  "value": "AgentSmith",
  "is_signed": true,
  "is_encrypted": false,
  "encrypted_value": null,
  "encrypted_aes_key": null,
  "session_id": "48c29c06-4a7c-4774-9b42-ea63f95f0ee0"
}

You may update existing visitor variable by its key:

PUT /api/v5/users/<user_id>/chats/<chat_id>/visitors/<visitor_id>/variables/<key>.

PATCH /api/v5/users/<user_id>/chats/<chat_id>/visitors/<visitor_id>/variables/<key>.

This endpoint returns:

200 if the request was successful
400 if required attribute is missing from the request
400 if the request payload is in wrong format
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the user
404 if the chat was not found
404 if the visitor was not found
404 if the key was not found

Or alternatively:

PUT /api/v5/orgs/<organization_id>/rooms/<room_id>/visitors/<visitor_id>/variables/<key>.

PATCH /api/v5/orgs/<organization_id>/rooms/<room_id>/visitors/<visitor_id>/variables/<key>.

This endpoint returns:

200 if the request was successful
400 if required attribute is missing from the request
400 if the request payload is in wrong format
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have settings permission
404 if the room was not found
404 if the visitor was not found
404 if the key was not found

Delete existing chat visitor variable¶

You may delete existing visitor variable by it's key:

DELETE /api/v5/users/<user_id>/chats/<chat_id>/visitors/<visitor_id>/variables/<key>

This endpoint returns:

204 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the user
404 if the chat was not found
404 if the visitor was not found
404 if the key was not found

Or alternatively:

DELETE /api/v5/orgs/<organization_id>/rooms/<room_id>/visitors/<visitor_id>/variables/<key>.

This endpoint returns:

204 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
403 if you do not have settings permission
404 if the room was not found
404 if the visitor was not found
404 if the key was not found

Banning room visitors¶

You may need to add room visitor to blacklist. These bans can last a varying length of time and may be restricted to specifict rooms or IP.

A ban object has the following attributes:

Attribute	Type	Editable	Description
`id`	UUID	read-only	ID of the ban object.
`visitor_id`	string	read-only	ID of the visitor.
`room_id`	string	read-only	ID of the chat's room.
`created_by_user_id`	string	read-only	ID of the blocker.
`created_by_user`	object	read-only	The user info of the blocker as an object.
`created_at`	datetime	read-only	When the ban was created.
`ends_at`	datetime	read-only	When the ban ends at.
`duration`	integer	required	Duration of the ban. This must be a positive integer which represents ban duration in seconds.
`reason`	string	optional	Reason why the visitor was added to the blacklist.
`ip_address`	string	read-only	IP address of the visitor.
`is_ip_address_banned`	boolean	optional	Is visitor's IP address banned.

Create a new ban object¶

POST https://service.giosg.com/api/v5/users/ab7d649a-dfca-4677-b0de-66f8ed8d2c46/chats/ba85ce76-99f6-4ed3-8cb2-e22a0d12c513/visitors/817234ac40464edebd155c88139a2469/bans

{
  "id": "feaf6e6b-28ec-11e7-86a5-f45c89c72de3",
  "visitor_id": "08119566026a4e1194a7a3244c90f925",
  "room_id": "16ef9670-ea07-4a21-8276-721edceda148",
  "created_by_user_id": "ab7d649a-dfca-4677-b0de-66f8ed8d2c46",
  "created_by_user": {
    "id": "ab7d649a-dfca-4677-b0de-66f8ed8d2c46",
    "first_name": "Bob",
    "last_name": "Burger",
    "full_name": "Bob Burger",
    "organization_id": "5567a0b0-28ed-11e7-8b5c-f45c89c72de3",
    "is_bot": false
  },
  "created_at": "2017-04-24T12:56:24.162Z",
  "ends_at": "2017-04-24T14:56:24.126Z",
  "duration": 7200,
  "reason": "Kept asking for nearest burgerplace",
  "ip_address": "143.66.91.75",
  "is_ip_address_banned": false
}

You may create a ban object by:

POST /api/v5/users/<user_id>/chats/<chat_id>/visitors/<visitor_id>/bans.

You need to define at least duration as the payload. Reason and is_ip_address_banned are optional fields. This will ban the user from the room in which the chat occured.

This endpoint returns:

201 if the request was successful
400 if required attribute is missing from the request
400 if the request payload is in wrong format
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the user
404 if the chat was not found

Removing visitor's data¶

You may need to remove all data of a visitor. This can be achieved by using our API which will clear all visitor's chat messages and remove all chat memberships, visitor variable, and other visitor information from giosg system. The visitor object itself won't be removed but all its relations to other tables are removed.

Scheduling removal of visitor's data¶

DELETE https://service.giosg.com/api/v5/orgs/ab7d649a-dfca-4677-b0de-66f8ed8d2c46/visitors/817234ac40464edebd155c88139a2469

You may remove visitor's data by:

DELETE /api/v5/orgs/<user_id>/visitors/<visitor_id>.

Note that this API does not remove the visitor data instantaneously as it only schedules the removal of the visitor's data. When the removal has been completed, the requester and other users of the organization with any permission will be notified by email.

This endpoint returns:

202 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
404 if the visitor was not found

Revoking a visitor¶

You may need to revoke the visitor so that the visitor ID and related authentications can no longer access any data related to the visitor. This API does not remove any data but instead just makes the specified visitor ID unusable.

Calling revoke visitor API¶

POST https://service.giosg.com/api/v5/orgs/ab7d649a-dfca-4677-b0de-66f8ed8d2c46/visitors/817234ac40464edebd155c88139a2469/revoke

You may revoke visitor by:

POST /api/v5/orgs/<org_id>/visitors/<visitor_id>/revoke.

After call to the API visitor's active chat sessions will be ended and the visitor will be revoked. Revocation will be active immediately after the API call.

This endpoint returns:

201 if the request was successful
401 if you are not authenticated
403 if you do not have active subscription
403 if you do not have access to the organization
404 if the visitor was not found