Skip to content

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

Example request:

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

Example response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
[
  {
    "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

Example request:

1
2
3
4
5
6
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"
}

Example response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "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.

Example request:

1
2
3
4
5
6
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"
}

Example response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "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

Example request:

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

Example response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "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

Example request:

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

Example response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
  "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

Example request:

1
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

Example request:

1
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