Rooms API

Rooms and domains¶

The room resource has the following attributes.

Attribute	Type	Editable	Description
`id`	UUID	read-only	The unique identifier of this room
`organization_id`	UUID	read-only	ID of the organization who owns this room.
`organization`	object	read-only	The organization who owns this room.
`domain`	string	optional	A domain hostname if this room is a domain room, otherwise `null` if this is a custom room. Cannot be changed after creation. You cannot have multiple domain rooms with the same `domain` attribute!
`name`	string	required	Name of the room, set by the owner. Must be a non-empty string.
`display_name`	string	read-only	Display name of the room. It may equal to the `name` attribute, unless this room is shared to your organization with a custom `share_name`.
`is_shared`	boolean	read-only	`true` if the room is shared to your organization, `false` if your organization owns the room
`language_code`	string	optional	Language of this room as a RFC 3066 code. Defaults to `en`, cannot be `null`. It must be one of the supported languages.
`created_at`	datetime	read-only	When this room was created. Available only to your own organization.
`updated_at`	datetime	read-only	When this room was updated last time. Available only to your own organization.
`updated_by_user_id`	UUID	read-only	ID of the user who last updated this room, or `null` if unknown. Available only to your own organization.
`updated_by_user`	object	read-only	Details of the user who last updated this room, or `null` if unknown. Available only to your own organization.
`is_online`	boolean	read-only	Whether the room is currently online, i.e. there is a router with at least one online user in any of the routing steps assigned to the room, and `is_open` is `true`. Visitor can start a chat in a room only if the room is online.
`is_humans_online`	boolean	read-only	Whether the room is currently online and there is at least one non bot user online in the routing steps. Useful for developing chatbots, that need to know if they can transfer chats to people.
`is_deleted`	boolean	read-only	Whether this room exists no more. The resource exists only for historical purposes and cannot be used in any other context.
`is_service_hours_enabled`	boolean	read-only	Whether the room has service hours enabled.
`is_open`	boolean	read-only	Whether the room is currently open, i.e. currently in service hours if the room has service hours hours enabled, otherwise always `true`.
`is_chat_encryption_enabled`	boolean	optional	Whether the room has chat encryption enabled. This is `false` by default.
`public_key_id`	string	optional	ID of the public key used to encrypt chats, `null` if not set.
`sensitive_data_purge_ttl`	integer	optional	The number of days after chat session has closed to purge sensitive data from chat sessions in the room. Setting to `null` disables sensitive data purging. This is `null` by default.
`bots_ignored_in_online_status`	boolean	optional	Controls whether room's `is_online` field's value's calculation ignores bots' online statuses and only considers human users. Bot users are those that have the `is_bot` field set as true. This is `false` by default.

Warning

The following attributes also exists but they are deprecated, so you should avoid using them.

Attribute	Type	Editable	Description
`token`	string	read-only	A legacy signed ID of the room. You probably won't need this in new implementations!

Domain rooms are like any other rooms except that they are linked to exactly one domain (website). You need a domain room in order to use a Giosg services on your website.

List rooms of an organization¶

Return a paginated collection of all the room resources that the given organization has access to, including any shared rooms by default.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/rooms

This endpoint takes the following optional GET parameters:

Parameter	Type	Default	Description
`ordering`	ordering	`created_at`	Ordering of results with options `created_at` and `-created_at`
`is_deleted`	boolean	(none)	If `true`, return only deleted rooms. If `false`, excludes any deleted rooms.
`is_shared`	boolean	(none)	If `true`, return only rooms shared to your organization. If `false`, return only your own organization's rooms.

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

Retrieve room details¶

Get a single room object that your organization has access to, by its ID. Note that this may be a shared and/or deleted room.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/rooms/<room_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 room was not found

Creating a room¶

Create a new custom room or a domain room by making a POST request, providing the room object as a payload. By providing the domain attribute with non-null value will create a new domain room.

POST https://service.giosg.com/api/v5/orgs/<organization_id>/rooms

This endpoint returns:

201 if the request was successful
400 if required attributes are 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

Update a room¶

You may update the editable attributes of your own room by making either a PATCH (update a subset of attributes) or PUT request (update all the attributes).

PUT https://service.giosg.com/api/v5/orgs/<organization_id>/rooms/<room_id>

PATCH https://service.giosg.com/api/v5/orgs/<organization_id>/rooms/<room_id>

This endpoint returns:

200 if the request was successful
400 if required attributes are 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 room was not found

Delete a room¶

Warning

Deleting a room will immediately unshare it from your partners! Even though your statistics for this room are preserved, you cannot gather any more data for this room. You cannot undo this action, but you need to re-create and re-share the room again.

You may delete one of your own rooms by making a DELETE request.

DELETE https://service.giosg.com/api/v5/orgs/<organization_id>/rooms/<room_id>

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 room was not found

List users of a room¶

Return a paginated collection of all the user resources which have access to the given room. This lists only users which are members of the given organization.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/rooms/<room_id>/users

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 room was not found

List rooms of a user¶

Return a paginated collection of all the room resources that the given user (or their team) have a permission to access.

GET https://service.giosg.com/api/v5/users/<user_id>/rooms

Notice

Note that this only lists rooms to which the user has an explicit permission, even if you are using the endpoint as a user with 'settings' permission. See below if you need to list rooms for an organization.

This endpoint takes the following optional GET parameters:

Parameter	Type	Default	Description
`ordering`	ordering	`created_at`	Ordering of results with options `created_at`, and `updated_at` (`-` for descending results).
`is_shared`	boolean	(none)	If `true`, return only rooms shared to the organization of the user. If `false`, return only rooms belonging to the organization of the user.

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

Retrieve details of user's room¶

You can retrieve details of user's room:

GET https://service.giosg.com/api/v5/users/<user_id>/rooms/<room_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 user does not have access to the room

The tag resource has the following attributes.

Attribute	Type	Editable	Description
`name`	string	editable	The unique name for a tag in this room.
`created_at`	string	read-only	When this tag was created.
`hashed_name`	string	read-only	Sha1 hash of this tag. This is the only information that the visitor and goals generated have about the tag.
`room_id`	string	read-only	UUID of the room for this tag.

GET https://service.giosg.com/api/v5/orgs/ac83d426-be80-4d75-8c62-49a77f98468e/chats/3c43e25a-54d4-46de-9b1d-13ff39df30b7/rooms/c83d426-be80-4d75-8c62-49a77f98468e/allowed_tags

Example response

{
  "next": "https://service.giosg.com/api/v5/orgs/ac83d426-be80-4d75-8c62-49a77f98468e/chats/3c43e25a-54d4-46de-9b1d-13ff39df30b7/rooms/c83d426-be80-4d75-8c62-49a77f98468e/allowed_tags?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "name": "Lead",
      "created_at": "2016-09-01T11:31:36.042Z",
      "room_id": "c83d426-be80-4d75-8c62-49a77f98468e",
      "hashed_name": "c83d42604d758c6249a77f98468e"
    },
    {
      "name": "Premium customer",
      "room_id": "c83d426-be80-4d75-8c62-49a77f98468e",
      "created_at": "2016-09-01T12:20:12.206Z",
      "hashed_name": "c83d42604d758c6249a77f98468e"
    }
  ]
}

Returns a paginated collection of all the tags for a room.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/rooms/<room_id>/allowed_tags

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 room was not found

Returns a paginated collection of all the tags for all organization rooms.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/allowed_tags

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

List system tags for all organization rooms¶

Returns a paginated collection of all the system tags for all organization rooms.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/system_tags

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

Create tag for a room¶

POST https://service.giosg.com/api/v5/orgs/ac83d426-be80-4d75-8c62-49a77f98468e/rooms/c83d426-be80-4d75-8c62-49a77f98468e/allowed_tags

{
  "name": "Lead"
}

Example response

{
  "name": "Lead",
  "room_id": "c83d426-be80-4d75-8c62-49a77f98468e",
  "created_at": "2016-09-01T12:20:12.206Z",
  "hashed_name": "c83d42604d758c6249a77f98468e"
}

You may create a tag for a room by making a POST request. This creates a new tag which can then be added to a chat session in this room:

POST https://service.giosg.com/api/v5/orgs/<organization_id>/rooms/<room_id>/allowed_tags

This endpoint returns:

201 if the request was successful
400 if required attributes are 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 room was not found

Delete a tag of a room¶

DELETE https://service.giosg.com/api/v5/orgs/ac83d426-be80-4d75-8c62-49a77f98468e/rooms/c83d426-be80-4d75-8c62-49a77f98468e/allowed_tags/lead

You may delete one of your tags for a room by making a DELETE request. After this request the tag will not show up in listing of the tags:

DELETE https://service.giosg.com/api/v5/orgs/<organization_id>/rooms/<room_id>/allowed_tags/<tag>

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 room was not found
404 if tag was not found

Room overviews¶

Usually you may want to know some aggregated numbers of a room. A room overview describes the current status of the room in the given context, for example, the number of present visitors, or a number of pending chats. There are two kind of contexts:

A single room
All rooms of a user

A room overview has the following attributes:

Attribute	Type	Description
`present_visitor_count`	integer	The total number of unique visitors currently present in the context of the overview.
`pending_chat_count`	integer	The total number of pending chats in the context of the overview.

Retrieve an overview of a room¶

You can get the overview of one room:

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

In this case the overview attributes have the following meanings:

present_visitor_count describes the number of room visitors
pending_chat_count describes the number of pending chats of the room

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 room was not found

Retrieve an overview of all user rooms¶

You can get an aggregated overview of all the rooms that the given user has permission to:

GET /api/v5/orgs/<organization_id>/users/<user_id>/room_overview

In this case the overview attributes have the following meanings:

present_visitor_count describes the number of distinct visitors in all of the user's rooms
pending_chat_count describes the number of pending chats in the user's rooms

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

Organization room settings¶

Organization room settings contain organization specific settings for a room. In other words, if the room is shared for your organization, these settings apply only for your organization and vice versa.

The organization room settings resource has the following attributes.

Attribute	Type	Editable	Description
`id`	UUID	read-only	The unique identifier of this organization room settings.
`organization_id`	UUID	read-only	ID of the organization who owns this room.
`organization`	object	read-only	The organization who owns this room.
`room_id`	UUID	read-only	ID of the room to which these settings apply.
`room`	object	read-only	The room to which these settings apply.
`router_id`	UUID	optional	ID of the router that is used to route chats in this room.
`router`	object	read-only	router that is used to route chats in this room.
`brand_id`	UUID	optional	ID of the brand that is used in this room. If `null` then the default theme is used.
`is_pending_chat_messages_hidden`	boolean	required	Whether pending visitor messages should be hidden in giosg Console.
`is_auto_tagging_enabled`	boolean	required	Whether chats will be automatically tagged wiht `Auto: phone` and `Auto: email` tags if there is phone number or email.
`is_analytics_tracking_enabled`	boolean	required	Whether Google Analytics tracking is enabled.
`analytics_object_type`	string	optional	Type of the Google Analytics object. This is required if `is_analytics_tracking_enabled` is `true`. Options are `gaq`, `datalayer`, `ga-send` and `custom`.
`analytics_custom_object`	string	optional	This is required if `analytics_object_type` is `custom`.
`is_ajax_tracking_enabled`	boolean	required	Whether AJAX tracking is enabled.
`created_at`	datetime	read-only	When these room settings were created.
`updated_at`	datetime	read-only	When these room settings were updated last time.
`legacy_chat_dialog_id`	UUID	optional	ID of the chat dialog used in the room. This is `null` by default.

Retrieve organization room settings¶

Get the settings of an organization room.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/rooms/<room_id>/settings

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 room was not found

Update organization room settings¶

Update the settings of an organization room.

PUT https://service.giosg.com/api/v5/orgs/<organization_id>/rooms/<room_id>/settings

PATCH https://service.giosg.com/api/v5/orgs/<organization_id>/rooms/<room_id>/settings

This endpoint returns:

200 if the request was successful
400 if required attributes are 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 room was not found

Domain links¶

A domain link represents relation between room and the domain. It defines the domains where the room is allowed to work. The domain link resource has the following attributes:

Attribute	Type	Editable	Description
`id`	UUID	read-only	The unique identifier of this domain link.
`organization_id`	UUID	read-only	ID of the organization who owns this domain link.
`organization`	object	read-only	The organization who owns this domain link.
`room_id`	UUID	read-only	ID of the room which has access to this domain link.
`room`	object	read-only	The room which has access to this domain link.
`domain_room_id`	UUID	read-only	ID of the domain room (room).
`domain_room`	object	read-only	The domain room (room) which has access to this domain link.
`created_at`	datetime	read-only	When this domain link was created.
`updated_at`	datetime	read-only	When this domain link was updated last time.

List room's domain links¶

Return a paginated collection of all the domain link resources that the given room has access to.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/rooms/<room_id>/domain_links

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 room was not found

Create a new domain link for a room¶

Create a new domain link for a room by making a POST request, providing the domain_room_id as a payload. The domain_room_id is the id of a room which is a domain i.e. room where the domain is not null.

POST https://service.giosg.com/api/v5/orgs/<organization_id>/rooms/<room_id>/domain_links

This endpoint returns:

200 if existing domain link was updated
201 if domain link was created successfully
400 if required attributes are 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 room was not found

Delete room's domain link¶

You may delete one of your own room's domain link by making a DELETE request.

DELETE https://service.giosg.com/api/v5/orgs/<organization_id>/rooms/<room_id>/domain_links/<domain_room_id>

This endpoint returns:

204 if the request was successful
401 if you are not authenticated
403 if you do not have active subscriptiond
403 if you do not have access to the organization
403 if you do not have settings permission
404 if room was not found
404 if domain link was not found

Room queue API¶

The Room Queue API provides information about rooms queues, enabling you to access queue details for each chat session within a specific room. This API exposes endpoints for both listing all active queues for a room and retrieving detailed information about a specific queue.

Attribute	Format	Editable	Description
`id`	UUID/string	read-only	ID of the queue.
`chat_id`	UUID/string	read-only	ID of chat session this queue belongs to.
`room_id`	UUID/string	read-only	ID of the room where chat session belongs to.
`created_at`	datetime	read-only	When the queue was added to chat.
`organization_id`	UUID/string	read-only	ID of the organization the room belongs.
`type`	string	read-only	Type of the queue.
`current_position_in_queue`	integer	read-only	Visitors position in the queue.
`initial_estimated_wait_time`	datetime	read-only	Initial waiting time estimation.
`current_estimated_wait_time`	datetime	read-only	Updated waiting time estimation.
`chat_picked_up_at`	datetime	read-only	Time when chat is picked up (for active queue object this is always null).

List room queues¶

List all active queue objects for the room.

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

Example response

{
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "64d8e1d2-b9d2-11ee-81f3-1e00d136cc32",
      "chat_id": "64ce7ee0-b9d2-11ee-81f3-1e00d136cc32",
      "room_id": "64cbfe68-b9d2-11ee-81f3-1e00d136cc32",
      "organization_id": "64c5fdc4-b9d2-11ee-81f3-1e00d136cc32",
      "created_at": "2020-01-23T11:32:58.127016",
      "type": "chat",
      "current_estimated_wait_time": "2020-01-23T11:33:58.127016",
      "current_position_in_queue": 1,
      "initial_estimated_wait_time": "2020-01-23T11:33:58.127016",
      "chat_picked_up_at": null
    },
    {
      "id": "c83d426-be80-4d75-8c62-49a77f98468e",
      "chat_id": "3c43e25a-54d4-46de-9b1d-13ff39df30b7",
      "room_id": "64cbfe68-b9d2-11ee-81f3-1e00d136cc32",
      "organization_id": "64c5fdc4-b9d2-11ee-81f3-1e00d136cc32",
      "created_at": "2020-01-23T11:34:58.127016",
      "type": "chat",
      "current_estimated_wait_time": "2020-01-23T11:35:58.127016",
      "current_position_in_queue": 2,
      "initial_estimated_wait_time": "2020-01-23T11:35:58.127016",
      "chat_picked_up_at": null
    },
  ]
}

Room queue retrieve API¶

Retrieve the rooms queue object (active or picked up).

GET /api/v5/orgs/<organization_id>/rooms/<room_id>/queues/<queue_id>

Example response

{
  "id": "64d8e1d2-b9d2-11ee-81f3-1e00d136cc32",
  "chat_id": "64ce7ee0-b9d2-11ee-81f3-1e00d136cc32",
  "room_id": "64cbfe68-b9d2-11ee-81f3-1e00d136cc32",
  "organization_id": "64c5fdc4-b9d2-11ee-81f3-1e00d136cc32",
  "created_at": "2020-01-23T11:32:58.127016",
  "type": "chat",
  "current_estimated_wait_time": null,
  "current_position_in_queue": null,
  "initial_estimated_wait_time": null,
  "chat_picked_up_at": "2020-01-23T11:33:58.127016"
}

Rooms API

Rooms and domains¶

List rooms of an organization¶

Retrieve room details¶

Creating a room¶

Update a room¶

Delete a room¶

List users of a room¶

List rooms of a user¶

Retrieve details of user's room¶

List tags for a room¶

List tags for all organization rooms¶

List system tags for all organization rooms¶

Create tag for a room¶

Delete a tag of a room¶

Room overviews¶

Retrieve an overview of a room¶

Retrieve an overview of all user rooms¶

Organization room settings¶

Retrieve organization room settings¶

Update organization room settings¶

Domain links¶

List room's domain links¶

Create a new domain link for a room¶

Delete room's domain link¶

Room queue API¶

List room queues¶

Room queue retrieve API¶