Organizations API

Organizations¶

An organization represents any organization account on giosg system. An organization consists of a number of users with their own user accounts. A user always belongs to exactly one organization.

Please note that despite its name a "organization" in this context means any organization or group. It can even consists of only one user.

An organization object contains the following attributes. Note that the contact information is public.

Attribute	Type	Editable	Description
`id`	UUID	read-only	Unique identifier for this organization
`name`	string	required	The name of the organization. Maximum length is 64.
`email`	string	optional	Contact email address, or `null`. Maximum length is 64.
`phone`	string	optional	Contact phone number, or `null`. Maximum length is 16.
`street`	string	optional	Contact street address, or `null`. Maximum length is 128.
`postal_code`	string	optional	Contact address postal code, or `null`. Maximum length is 8.
`city`	string	optional	Contact address city, or `null`. Maximum length is 32.
`country`	string	optional	Country as a two-letter, lowercase ISO 3166-1 code, or `null`. Maximum length is 2.
`business_id`	string	optional	Business ID of the organization, if any, or `null`. Maximum length is 256.
`script_tag`	string	read-only	The script tag for the organization.
`is_online`	boolean	read-only	Whether the organization is currently online, i.e. at least one user from the organization is online. See users for more information.
`is_humans_online`	boolean	read-only	Whether there is at least one non bot user online in the organization. Useful for developing chatbots, that need to know if they can transfer chats to people.
`is_present`	boolean	read-only	Whether the organization is currently present, i.e. at least one user from the organization is present. See users for more information.
`max_rules_count`	integer / null	read-only	Number of rules the organization can create. NOTE: Will be moved to somewhere else in the near future!
`created_at`	datetime	read-only	When this organization account was created.
`updated_at`	datetime	read-only	When organization details were changed last time.

Retrieve organization details¶

Get a single organization object by its ID.

GET https://service.giosg.com/api/v5/orgs/<organization_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

Update organization details¶

You may update some of the attributes of an organization, if you have permissions to do so.

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

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

When using PUT you need to provide an object as a request payload that contains all the required attributes of the organization. When using PATCH, you may omit those attributes that you do not want to change.

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

Organization overviews¶

Usually you may want to know some aggregated numbers of a organization. A organization overview describes the current status of the organization.

An organization overview has the following attributes:

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

Retrieve an overview of an organization¶

You can get the overview of your organization:

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

The overview attributes have the following meanings:

present_visitor_count describes the number of visitors present across all your organization rooms.
pending_chat_count describes the number of pending chats across all your organization 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

Organization's Features¶

Features are different kind of services (e.g. rooms, rules) which giosg provides. A feature object contains following attributes:

Attribute	Type	Editable	Description
`id`	string	read-only	Unique identifier for this feature. In this case the name is the unique identifier.

List current features of organization¶

You may want to list all features which are currently enabled for a organization. Expired / disabled features cannot be listed.

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

Parameter	Type	Default	Description
`ordering`	ordering	`id`	Ordering of results with option `id` (with or without `-`)

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

Organization Settings¶

Every organization has its settings. These settings contain organization specific definitions how the system should work for them. Organization can have only one settings for them.

Attribute	Type	Editable	Description
`id`	UUID	read-only	Unique identifier for this organization settings.
`organization_id`	UUID	read-only	ID of the organization.
`organization`	object	read-only	The organization object.
`ui_version`	string	read-only	Giosg UI version code.
`default_ui_language`	string	required	Default UI language in console.
`timezone`	string	required	Organization time zone. See Time zones API for supported values.
`is_private_chat_history_enabled`	boolean	required	Whether only users with `reports` permission may see the organization's chat history or everyone
`is_strict_password_policy_enabled`	boolean	required	Whether strict password policy is enabled or not.
`is_automatic_chat_links_enabled`	boolean	required	Whether links in chat dialogs are clickable or not.
`is_variable_signing_required`	boolean	required	Do visitor variables have to be signed with key.
`is_login_credentials_preservation_enabled`	boolean	required	Are user login credentials saved, i.e. users do not have to login for every session.
`login_credentials_preservation_duration`	integer	required	For how long login credentials are saved. This value is in seconds.
`password_expiration_days`	integer / null	optional	Password expiration interval in days. Must be at least `1` day. If `null`, passwords will not expire.
`giosg_crawler_secret`	string / null	optional	Organizations secret value that can be used to identify GiosgCrawler instance. This is part of the Crawlers user agen string.
`custom_cdn_url`	string / null	read-only	Organizations own CDN. If `null` static files will be loaded through Giosg CDN.
`created_at`	datetime	read-only	When organization settings were created.
`updated_at`	datetime	read-only	When organization settings were changed last time.

Retrieve organization settings¶

Get organization's settings by:

GET https://service.giosg.com/api/v5/orgs/<organization_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

Update organization settings¶

You may update some of the attributes of organization settings, if you have permissions to do so.

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

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

When using PUT you need to provide an object as a request payload that contains all the required attributes of the organization settings. When using PATCH, you may omit those attributes that you do not want to change.

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

Organization's Customership¶

Information about your organization's customership. The customership object contains information about usage limits of certain features and status of your current subscription (trial account or not).

Attribute	Type	Editable	Description
`organization_id`	UUID	read-only	ID of the organization.
`organization`	object	read-only	The organization object.
`is_trial`	boolean	read-only	Whether organization has a trial subscription or not.
`max_users_count`	integer / null	read-only	How many users organization can have once.
`max_online_users_count`	integer / null	read-only	How many users can organization have chatting once.
`max_rules_count`	integer / null	read-only	How many created rules organization can have once.
`max_scheduled_email_reports_count`	integer / null	read-only	How many scheduled reports organization can have once.
`updated_at`	datetime	read-only	When organization's customership was updated last time.

Retrieve details of organization's customership¶

Get details of organization's customership:

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

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
404 if organization does not have created subscription.