NAV

Using the API

Introduction

Welcome to giosg API documentation’s HTTP API section!

To use this documentation, you need active subscription for giosg. This document describes what you can do with the giosg HTTP API and how you can use it in your application or software. In case of the documented endpoint failing or not working as documented, please contact support@giosg.com.

Terms used in the document

There are some terms which are used often in the documentation and should be familiarized with to be able to use this documentation properly.

Term Description
organization Giosg organization account has to be created in order to be able to use Giosg products such as Giosg LIVE, Giosg RULES and Giosg APIs.
room Room belongs to an organization and represents the premise where the chats take place.
domain room Domain room is like a room but it is linked to a domain. Each organization should have at least one domain room in order to use Giosg on their website.
user Giosg user account belongs to a certain organization.
visitor Visitor represents a person who visits a client’s website. Each visitor belongs to a certain room.
chat Chat represents a single conversation which happen in a room.
chat message Chat message is a single message in a chat conversation. Chat message has five different types, it can be an actual message (msg), autosuggest (autosuggest), a join event (join), a leave event (leave) or a shopping cart locked event (shoppingcart_locked).
chat membership Chat membership represents a participant in a chat. Chat membership can be a user or a visitor and there may be multiple of both of them in one chat conversation.
lead Leads are potential customers on a client’s website and you may use our APIs to gather information about them.
team Team belongs to an organization and consists users as admins and members.
shopping cart Shopping cart contains information about the products in visitor’s shopping cart. Shopping carts can be used only with Giosg BASKET product.

Example usage

Here are some examples of what APIs your app might want to use:

Authentication

An example request

POST https://service.giosg.com/api/v5/login

An example response

{
    "user_id": "ab82d28b-76a5-41fb-ab96-45f9211eba45",
    "organization_id": "e6a08f51-c250-4074-847b-58d444dbbeb1",
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.e30.we2snuuhq-cnPk-GMJVoBhyZ7ZKPa95Qxe_3VkEaf_E",
    "expires_at": "2015-12-22T11:25:30.595Z",
    "expires_in": 1800,
    "token": "4ec031b2e4147ec3cecce413f3db9c95b9edcb8d"
}

You can authenticate with a user by sending their email and password with the following request:

POST /api/v5/login

The payload should contain the following attributes:

Attribute Type Description
email string Login email of the user
password string Login password of the user

This endpoint returns some of the following status codes:

A successful authentication returns a response with the following attributes:

Attribute Type Description
user_id ID ID of the user being authenticated
organization_id ID ID of the organization of the authenticated user
access_token string The access token that you need to use to authorize access to other HTTP API endpoints.
expires_at date/time When this information (especially the access token) expires. You should renew this information before it expires.
expires_in integer After how many seconds this information (especially the access token) expires. You should renew this information before it expires. Useful for scheduling a timer for renewing the authentication.
token string The user’s API token that you may use to authorize access to other HTTP API endpoints.

NOTE: For information on using API’s with API Token see Authentication with an API token section.

Authorization with an access token

After authentication, you need to provide the access_token for each following API request in a Authorization HTTP header:

Authorization: Bearer <access_token>

You should replace the <access_token> with the token you received when authenticating or refreshing your authentication.

Authentication with an API token

If you want to use the API from a server, then you need to provide a valid API token in order access the API. You can create an API token from “Access tokens” section in your company settings:

Log in to Console → Settings Menu → Company → Access tokens

Once you have obtained your API tokens, define the Authorization HTTP header for all your API requests:

Authorization: Token <api_key>

You should replace the <api_key> with your API tokens.

When using a API token authorization, you do not need to authenticate first.

Renewing an access token

If your access token you received when authenticating is about to expire, then you can renew it by making the following request.

POST /api/v5/auth

This request should be authorized with your current access token as other API requests.

Returns one of the following status codes:

When successful, the response is equal to the one returned by a successful authentication, including the new access_token and its expiration details.

Supported languages

Only small portion of languages are supported by giosg. The correct format for languages is RFC 3066. All the listed languages are supported choices for some objects e.g. Rooms and User preferences. Some of the languages are valid options for the user interface language. A language object consists:

Attribute Type Description
rfc_3066 string Language in RFC 3066 format.
name string Name of the language in English.
is_ui_language boolean Whether this language is supported in giosg console with translations or not.

List supported languages

An example request

GET /api/v5/languages

An example response

{
    "next": null,
    "previous": null,
    "results": [
        {
            "rfc_3066": "de",
            "name": "German",
            "is_ui_language": false,
            "language_bidi": "ltr"
        },
        {
            "rfc_3066": "en",
            "name": "English",
            "is_ui_language": true,
            "language_bidi": "ltr"
        }
    ]
}

You may list supported languages by:

GET /api/v5/languages

This endpoint returns:

Supported time zones

All common time zones are supported by giosg. The format for time zone is stadard zone name string. Supported time zones can be used to set organization time zone setting using Organization Settings API.

Time zone object consists:

Attribute Type Description
name string Name of the time zone
offset string Offset of the time zone eg. +0200

List supported languages

An example request

GET /api/v5/timezones

An example response

{
    "next": null,
    "previous": null,
    "results": [
        {
            "name": "Asia/Bangkok"
        },
        {
            "name": "Europe/Helsinki"
        },
        {
            "name": "Pacific/Fakaofo"
        },
        {
            "name": "US/Pacific"
        },
        {
            "name": "UTC"
        }
    ]
}

You may list supported time zones by:

GET /api/v5/timezones

Response codes

giosg HTTP API uses regular HTTP codes for successful and failed requests. There might be explicitly defined response codes at the API endpoint’s own section.

Successful requests

Possible response codes for successful requests are:

HTTP status code Description
200 OK The request was successful.
201 Created The request successfully created new resource, normal response of succesful POST request.
204 No Content The request successfully returned no content, normal response of successful DELETE request.

Failed requests

Possible response codes for failed requests are:

HTTP status code Description
400 Bad Request The request is missing attributes, request attributes cannot be parsed, or the request is invalid.
401 Unauthorized The request cannot be processed because the authentication credentials were invalid or not provided.
403 Forbidden The request cannot be processed because:
  • you do not have permission for the requested resource
  • no subscription or the subscription has expired
404 Not Found The requested resource could not be found.
405 Method Not Allowed The request cannot be processed because the endpoint does not support the used request method.

API permission cheat sheet

This is a cheat sheet for checking which user permissions are required by Giosg system for endpoints. Only Organization prefixed endpoints may require permissions.

Terms used in cheat sheet

Term Definition
all All organization’s users can access this resource
x HTTP Method is not supported by the API
settings Only users with settings permission can access this resource. In Giosg system these endpoints are used in settings site.
users Only users with users permission can access this resource. In Giosg system these endpoints are used in user management site.
reports Only users with reports permission can access this resource. In Giosg system these endpoints are used in reporting site.

Cheat sheet

Accept Header

You also need to define that you accept JSON-formatted responses by providing the Accept HTTP header:

Accept: application/json

Alternatively, if you are unable to customize headers, you may add format=json GET parameter.

Resource identifiers

Unless stated otherwise, all the resources in the system are identified with a Universally Unique Identifier (UUID). It is always represented as a string ID, in lower case and including dashes.

For example: 9ae65e7d-56c5-11e5-af8d-6c4008c08dfe

Paginated collections

An example of a JSON response with a paginated collection

{
  "next": "https://service.giosg.com/api/v5/examples?cursor=da965a3ea0164c8ab8baef1d4654e2d3",
  "previous": null,
  "results": [
    {"name": "Example Resource 1"},
    {"name": "Example Resource 2"},
    {"name": "Example Resource 3"},
    {"name": "Example Resource 4"},
    {"name": "Example Resource 5"}
  ]
}

Some of the API endpoints return paginated collections. That means that for large collections of resources, not all resources are returned in a single response, but the response contains an URL that can be used to fetch the next chunk (page) of results.

Paginated collections are objects with the following attributes.

Attribute Type Description
next string Full URL for requesting the next page. This is null if the current page is the last page.
previous string Full URL for requesting the previous page. This is null if the current page is the first page
results array of objects The list containing the result resources for the current page. Each item is an object whose attributes depend on the returned resource type.

Ordering collections

A paginated collection can usually be ordered by using an ordering attribute.

The allowed sorting criteria depends on the endpoint, but the basic usage is always the same. You have an allowed set of sorting attributes, e.g. first_name, last_name and created_at. You may then choose the primary sorting key and any secondary sorting keys with a comma-separated string, e.g. last_name,first_name.

Any sorting order is ascending by default, but may be reverted to descending order by prefixing with a minus (-) character, e.g. -created_at or last_name,-created_at.

Date/time format

Unless stated otherwise, all the date/times returned by API endpoints are ISO-8601 strings with format YYYY-MM-DDTHH:MM:SS.MSSZ, for example: 2015-08-31T16:32:17.879Z. Also, any date/time URL parameters or attributes send as a request payload accept this same format.

Unless stated otherwise, the times are expressed in UTC timezone!

Organization 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 ID 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 any user from the organization is online. See user clients for more information.
is_present boolean read-only Whether any user from the organization currently present. See user clients 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 date/time read-only When this organization account was created. Available only for your own organization.
updated_at date/time read-only When organization details were changed last time. Available only for your own organization.

Retrieve organization details

Get a single organization object by its ID.

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

This endpoint returns:

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:

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][organization 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:

This endpoint returns:

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:

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 ID read-only Unique identifier for this organization settings.
organization_id ID read-only ID of the organization.
organization object read-only The organization object.
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.
created_at date/time read-only When organization settings were created.
updated_at date/time 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:

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:

User API

Users

A user represents a giosg user account. A user resource has the following attributes.

Attribute Type Editable Description
id ID read-only Unique identifier.
email string required Email address. Must be unique. For users with is_bot as true this can be null.
organization_id ID read-only ID of the organization to which the user belongs to.
organization object read-only The organization resource to which the user belongs to.
first_name string required First name.
last_name string required Last name.
full_name string read-only Full name.
is_manager boolean optional This attribute is deprecated and will be dropped soon.
is_staff boolean read-only Whether the user is a giosg.com staff member. This cannot be altered with API endpoints. If you want this to be true, apply at our website!
alias string optional Display name, used when chatting. May be null but not a blank string.
gender integer optional Gender with three options: "male", "female", null (unknown).
birthday date optional Date of birth in format YYYY-MM-DD, e.g. 1980-06-19.
phone string optional Contact phone number.
title title optional Title of the user. May be null but not a blank string
created_at date/time read-only When the user resource was created.
updated_at date/time read-only When the user resource was updated last time.
deleted_at date/time read-only When the user resource was deleted. null if the user resource has not been deleted yet.
avatar_id ID read-only ID of the user’s avatar. null if the user has no avatar.
avatar object read-only The avatar of the user as an object. It contains attributes idand url. This is null if the user has no avatar.
is_online_enabled boolean required Whether or not the user wants to serve online as an operator. This determines if the is_online can be true.
is_online boolean read-only Whether the user is currently in online status as an operator, based on the most recent information about the user. This can only be true if is_online_enabled is true and the user is considered signed in. Otherwise this is false. See user clients for more information.
is_present boolean read-only Whether the user is currenlty present, based on the most recent information about the user. See user clients for more information.
current_chat_count integer read-only The number of chats the user has currently, based on the most recent information about the user.
is_deleted boolean read-only Whether this user exists no more. If true, the resource exists only for historical purposes and cannot be used in any other context!
is_bot boolean read-only Whether this user is a bot or not. Bot users are automatically created when an application requiring app_user is installed.

Retrieve the authenticated user

There is a special API endpoint that returns the user resource depending on who is authenticated.

GET https://service.giosg.com/api/v5/users/me

To find out your organization’s ID, just use the organization_id attribute of the returned resource. Alternatively you can use the nested organization resource for more details).

This endpoint returns:

Create an organization user

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

Creating an organization user requires 3 compulsory attributes:

Attribute Type Editable Description
email string required The email address for the user. Must be a valid email. For users with is_bot as true this can be null.
first_name string required First name of the user.
last_name string required Last name of the user.

Example request and payload: Create a new organization user with POST

POST https://service.giosg.com/api/v5/orgs/64c8fb1c-8673-11e7-a7c7-00163e8edbc5/users
{
  "email": "test@example.com",
  "first_name": "first name",
  "last_name": "last name",
  "is_manager": true,
  "alias": "Test Alias",
  "gender": "male",
  "birthday": 1990-07-10,
  "phone": "0123456789",
  "title": "Test Title",
  "is_online_enabled": true
}

Create a new user object (<user_id>) for an organization (<organization_id>).

This endpoint returns:

List organization users

Get a paginated collection of users who belong to a given organization (<organization_id>)

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

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at, updated_at, or email (with or without -)
is_deleted boolean (none) By default returns all users. If true, returns only deleted users. If false, returns only active users.
is_manager boolean (none) This parameter is deprecated and will be dropped soon.

This endpoint returns:

Retrieve an organization user

Get a single user object by its ID (<user_id>) that belongs to an organization (<organization_id>)

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

This endpoint accepts the following GET parameters.

This endpoint returns:

Update an organization user

Example request and payload: Switch user to online

PATCH https://service.giosg.com/api/v5/orgs/2577ef72-efa0-4b4c-b5b6-0fc3a73e818f/users/fb993c84-1591-41f1-8d36-3804117f64e0
{
    "is_online_enabled": true
}

You may update some of the attributes of a user (<user_id>) that belongs to an organization (<organization_id>) by making a PATCH request:

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

You may also update the whole user resource with a PUT request. In this case, you need to define all the required attributes and any omitted optional attributes will be set to their defaults:

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

This endpoint returns:

Delete an organization user

DELETE https://service.giosg.com/api/v5/orgs/<organization_id>/users/<user_id>

DELETE
https://service.giosg.com/api/v5/orgs/2577ef72-efa0-4b4c-b5b6-0fc3a73e818f/users/fb993c84-1591-41f1-8d36-3804117f64e0

Only delete the user account if you want to permanently disable the user account!

This endpoint returns:

User clients

Each single application instance that uses the giosg HTTP API is considered a “user client”. Each user may have multiple clients. For example, the same user may use giosg on their desktop computer and/or on their mobile device. What is a “client” depends on the type of the app:

User clients have two important functions:

Users have two special attributes that depends of whether or not the user has announced his presence: is_online and is_present. Their values may only be true if there is at least one user client that the system considers “present”. The system remembers when the client has last time announced about themselves and automatically determines if the related user is present. Also, user may only be online if they are also present.

A user client has the following attributes:

Attribute Type Editable Description
id ID read-only An unique identifier for the client, generated by the system.
gcm_token string optional This attribute is deprecated and will be dropped soon.
subscribed_channels array of strings optional This attribute is deprecated and will be dropped soon.
presence_expires_in integer required The number of seconds the system should keep this client present. Only the latest provided value applies for the client.
presence_expires_at date/time read-only When the client will expire (or has expired), calculated from presence_expires_in. If this is in the past, then the client is not considered present.
is_about_to_expire boolean read-only Whether or not this user client is about to expire soon. This becomes false when creating/refreshing a user client, and will later change to true. This can be used to implement “server-side pinging”, see below.
created_at date/time read-only When the user client resource was created.
updated_at date/time read-only When the user client resource was updated last time.

The presence_expires_in defines how often you need to refresh the client’s presence status. Longer timeout allows you to make less refresh requests. On the other hand, with longer timeouts it takes longer to notice that your client has been closed, shut down, or disconnected from the network. We recommend shorter timeouts for browsers (e.g. 60 seconds) and longer timeouts for mobile apps.

Register a user client

Example request

POST https://service.giosg.com/api/v5/orgs/e9acaa51-f7a8-442e-ac7f-d36d926e228b/users/6b9d5dd2-ffb9-467c-b893-f41b6d2e93ae/clients

Example request payload for creating a new user client.

{
    "presence_expires_in": 60
}

Example response

{
    "id": "6d78c168-8688-4b79-a528-fbd3af53beef",
    "gcm_token": null,
    "subscribed_channels": [],
    "presence_expires_at": "2016-03-10T22:00:49.123Z",
    "presence_expires_in": 60
}

When a user starts using a new client (e.g. opens a giosg app web page) they should announce their existence to the server:

POST /api/v5/orgs/<organization_id>/users/<user_id>/clients

You must provide the presence_expires_in attribute. Please note that you should refresh the client presence again before this number of seconds have elapsed in order to keep your client online. You should consider your client devices performance for this.

This endpoint returns:

Refresh a user client

Example request

PUT https://service.giosg.com/api/v5/orgs/e9acaa51-f7a8-442e-ac7f-d36d926e228b/users/6b9d5dd2-ffb9-467c-b893-f41b6d2e93ae/clients/6d78c168-8688-4b79-a528-fbd3af53beef

You need to frequently tell the server about the presence of your client, otherwise the user will be automatiaclly switched to “not present” and “offline” state.

You refresh one of your clients:

PUT /api/v5/orgs/<organization_id>/users/<user_id>/clients/<client_id>

OR

PATCH /api/v5/orgs/<organization_id>/users/<user_id>/clients/<client_id>

The <client_id> is the id returned when first time announcing the client with POST.

Again, you must provide a payload object with the presence_expires_in attribute, which overwrites any previously set value.

This endpoint returns:

Unregister a user client

In some cases you may want to unregister the client completely to make the the client not present immediately:

DELETE /api/v5/orgs/<organization_id>/users/<user_id>/clients/<client_id>

This endpoint returns:

List user clients

GET /api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/users/aad26fe2-c8f3-45dc-931b-4b0b5e06467d/clients
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/users/aad26fe2-c8f3-45dc-931b-4b0b5e06467d/clients?cursor=45d9e7358e1249c491b4fa0212310f55",
  "previous": null,
  "results": [
    {
        "gcm_token": null,
        "subscribed_channels": [],
        "created_at": "2015-09-18T05:46:30.100Z",
        "id": "fdfc443a-1390-11e6-ba72-60f81dcf1946",
        "updated_at": "2016-05-06T13:46:53.882Z"
    },
    {
        "gcm_token": null,
        "subscribed_channels": [],
        "created_at": "2015-09-21T15:59:40.000Z",
        "id": "fdfb4397-1390-11e6-b10a-60f81dcf1946",
        "updated_at": "2016-05-06T13:46:53.874Z"
    }
  ]
}

You can get a paginated collection of all the user clients of the user:

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

This endpoint returns:

User preferences

Each user always has a single preferences resource containing private settings conserning the user account. A user preferences resource has the following attributes.

Attribute Type Editable Default Description
user_id ID read-only User’s UUID Unique identifier of user.
chat_capacity integer required 5 An estimate about the maximum number of people the user is willing to chat with simultaneously. The system uses this value in its algorithms to determine how many messages are sent in the name of the user.
desktop_message_sound string required visitor_message Identifier for the message sound used when a visitor sends a message.
is_desktop_message_sound_continuous boolean required true Whether or not to play the message sound continuously until the user interacts with the UI.
desktop_visitor_added_sound string required visitor_connect Identifier for the message sound played when a new visitor becomes present.
is_desktop_visitor_added_sound_continuous boolean required true Whether or not to play the visitor added sound continuously until the user interacts with the UI.
ui_language_code string required en Preferred UI Language in ISO 639-1 code.
is_muted_offline boolean required false Whether or not to disable the sounds while the user is offline.
is_statistics_email_enabled boolean required true Whether or not to send statistic emails to the user.
is_desktop_notification_enabled boolean required false Whether or not to use desktop notifcations (if supported by the browser)
is_spellcheck_enabled boolean required false Whether or not to enable spellchecking when composing messages (if supported by the browser)
desktop_volume integer required 100 The volume which is used for desktop message and visitor added notifications. The value can be between zero and hundred (0-100), meaning zero is silent while hundred is the maximum.
is_swimlane_visible boolean optional true Whether or not to show the swimlane in giosg console.

Retrieve user preferences

You can get the preferences of the user:

GET /api/v5/users/<user_id>/preferences

This endpoint returns:

Update user preferences

You can update some or all your preferences with a PATCH request:

PATCH /api/v5/users/<user_id>/preferences

Any omitted preference attributes are kept in their previous values.

You can also make a PUT request, but in this case you need to provide all the preference attributes, otherwise a 400 response is returned:

PUT /api/v5/users/<user_id>/preferences

This endpoint returns:

User avatar

Each user may have one avatar or none. An avatar resource has the following attributes.

Attribute Type Editable Description
id ID read-only Unique identifier of avatar.
url string required URL location where the avatar is hosted.
created_at date/time read-only When the user client resource was created.
updated_at date/time read-only When the user client resource was updated last time.

Retrieve avatar

You can get the avatar of the user:

GET /api/v5/users/<user_id>/avatar

This endpoint returns:

Or alternatively:

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

This endpoint returns:

Uploading new avatar for the user

You can upload a new avatar for user by making a POST request:

POST /api/v5/users/<user_id>/avatar

This endpoint returns:

Or alternatively:

POST /api/v5/orgs/<organization_id>/users/<user_id>/avatar

This endpoint returns:

You need to provide the image as a request payload in multipart/form-data format.

Deleting avatar of user

You can delete user’s avatar by making a DELETE request:

DELETE /api/v5/users/<user_id>/avatar

This endpoint returns:

Or alternatively:

DELETE /api/v5/orgs/<organization_id>/users/<user_id>/avatar

This endpoint returns:

User permissions

User permissions represent which resources are accessed by user. There are three different permissions which user may have (Settings, Reports, and User management). These permissions define which APIs are accessable by the user as well as which UI elements are shown in Giosg service e.g. buttons in top bar. Console view is accessable for all users in Giosg service and cannot be disabled by changing permissions. Required permission scopes are listed after each endpoint or you may refer our API permission cheat sheet.

A user permission has the following attributes:

Attribute Type Editable Description
organization_id ID read-only ID of the organization in which user belongs.
organization object read-only Organization in which user belongs.
user_id ID read-only ID of the user whose permission it is.
user object read-only User whose permission it is.
scope string required Which resource is accessable by user. Options are settings, reports, and users.
created_at date/time read-only When the user permission was created.
created_by_user_id ID read-only ID of the user which created this user permission.
created_by_user object read-only User which created this user permission.

List organization user’s permissions

GET https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/users/006ff599-9073-11e6-a887-f45c89c72de3/permissions
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/users/006ff599-9073-11e6-a887-f45c89c72de3/permissions?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
      "organization": {
        "id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "name": "Company X"
      },
      "user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "user": {
        "id":  "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "scope": "settings",
      "created_at": "2015-02-13T11:31:36.042",
      "created_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "created_by_user": {
        "id":  "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      }
    }
  ]
}

You can list permissions of an organization’s user:

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

This API endpoint returns a paginated collection. They are sorted by the creation time of the permissions, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

Retrieve details of an organization’s user’s permission

You can retrieve details of organization’s user’s permission:

GET /api/v5/orgs/<organization_id>/users/<user_id>/permissions/<permission_scope>

This endpoint returns:

Delete permission of a user

Example request for deleting a user’s permission

POST https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/users/006ff599-9073-11e6-a887-f45c89c72de3/permissions/reports

You can remove a user’s permission by:

DELETE /api/v5/orgs/<organization_id>/users/<user_id>/permissions/<permission_scope>

This endpoint returns:

Creating a new permission for a user

Example request for creating a new user permission

POST https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/users/006ff599-9073-11e6-a887-f45c89c72de3/permissions

Example request payload

{
  "scope": "reports"
}

You can create a new permission for a user by:

POST /api/v5/orgs/<organization_id>/users/<user_id>/permissions

This endpoint returns:

List user’s permissions

Example request for listing user’s permissions

GET https://service.giosg.com/api/v5/users/006ff599-9073-11e6-a887-f45c89c72de3/permissions

You can list permissions of a user:

GET /api/v5/users/<user_id>/permissions

This API endpoint returns a paginated collection. They are sorted by the creation time of the permissions, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

List all organization’s users with given permission scope

Example request for listing all organization’s users with given scope

POST https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/permissions/reports/users

You can list all organization’s users for a permission scope by:

POST /api/v5/orgs/<organization_id>/permissions/<permission_scope>/users

This API endpoint returns user objects instead permission objects.

This endpoint returns:

Teams API

Teams

A team object contains the following attributes.

Attribute Type Editable Description
id ID read-only The unique identifier of this team
organization_id ID read-only ID of the organization who owns this team.
organization object read-only The organization who owns this team.
name string required Name of the team. Must be a non-empty string.
display_name string read-only Display name of the team. It may equal to the name attribute, unless this team is [shared][outgoing team share] to your organization with a custom share_name. (Currently always equal to the name attribute)
member_count integer read-only Number of members in this team. Available only to your own organization.
present_member_count integer read-only Number of present both members in this team. Available only to your own organization.
is_online boolean read-only Whether or not the team is currently online.
is_present boolean read-only Whether or not the team is currently present.
created_by_user_id ID read-only The ID of the user who created the team.
created_by_user object read-only The user who created the team.
updated_by_user_id ID read-only The ID of the user who updated the team.
updated_by_user object read-only The user who updated the team.
created_at date/time read-only When the team resource was created
updated_at date/time read-only When the team resource was updated last time

Get a collection of organization’s teams

Return a paginated collection of all the team resources of an organization (<organization_id>).

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

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

Retrieve organization’s team details

Get a single team object (<team_id>) of an organization (<organization_id>). This may be a [team shared to the organization][incoming team share].

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

This endpoint returns:

Get a collection of user’s teams

Return a paginated collection of all the team resources of a user (<user_id>).

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

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

Get a collection of organization’s user teams

Return a paginated collection of all the team resources of an organization’s (<organization_id>) user (<user_id). This means teams to which the user belongs to.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/users/<user_id>/teams

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

Retrieve user’s team details

Get a single team object (<team_id>) of a user (<user_id>).

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

This endpoint returns:

Create a team

Create a team for an organization (<organization_id>)

Example request payload

{
  "name": "Test team"
}

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

This endpoint returns:

Update a team

You may update the editable attributes of a team (<team_id>) that belongs to an organization (<organization_id>). You can make either a PATCH request (update a subset of attributes) or POST request (update all the attributes).

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

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

This endpoint returns:

Delete a team

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

DELETE https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>

This endpoint returns:

Team memberships

A team membership represents a user belonging to a specific team. Team memberships are only visible for teams of your own organization. A team membership resource has the following attributes.

Attribute Type Editable Description
team_id ID read-only ID of the team to which this member belongs.
team object read-only The team to which this member belongs, with attributes id, name, display_name, and organization_id.
user_id ID required ID of the member user.
user object read-only The member user resource, with attributes id, first_name, last_name, full_name and organization_id.
created_by_user_id ID read-only The ID of the user who created the membership.
created_by_user object read-only The user who created the membership.
created_at date/time read-only When the membership resource was created.

Team memberships are readable by any member of the same organization. However, they can be created or deleted only by organization users with users permission. Otherwise, the endpoints will return a 403 Forbidden response.

Get a collection of team members

Return a paginated collection of all the team membership resources for a specific team.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/memberships

This endpoint returns:

Add a member to a team

You may add a user of your own organization to one of your teams by creating a team membership object.

Example request payload

{
  "user_id": "ab98bd97-872c-11e7-921d-60f81dcf1946"
}

POST https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/memberships

This endpoint returns:

Remove a member from a team

You may remove a user from a team by deleting her membership.

DELETE https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/memberships/<user_id>

This endpoint returns:

Retrieve team membership details

You may get the a user membership resource in a team:

GET https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/memberships/<user_id>

This endpoint returns:

Team users

A team user represents a user belonging to a specific team. Team users are only visible for teams of your own organization. Team users are readable by any member of the same organization.

Get a collection of team users

Return a paginated collection of all the team user resources of an organization.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/teams/<team_id>/users

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at

This endpoint returns:

Teamless users

A teamless user represents a user that is not a member of any team.

Get a collection of teamless users

Return a paginated collection of all the teamless user resources of an organization.

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

This endpoint returns:

Rooms API

Rooms and domains

The room resource has the following attributes.

Attribute Type Editable Description
id ID read-only The unique identifier of this room
organization_id ID 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][outgoing room share] 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 date/time read-only When this room was created. Available only to your own organization.
updated_at date/time read-only When this room was updated last time. Available only to your own organization.
updated_by_user_id ID 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 true if the room is currently online, i.e. there is at least one online user and the organization is allowed to be online at that room.
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.
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:

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:

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:

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:

Delete a room

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:

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:

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

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:

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:

List tags for a 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:

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:

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:

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 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:

This endpoint returns:

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:

This endpoint returns:

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 ID read-only The unique identifier of this organization room settings.
organization_id ID read-only ID of the organization who owns this room.
organization object read-only The organization who owns this room.
room_id ID read-only ID of the room to which these settings apply.
room object read-only The room to which these settings apply.
router_id ID optional ID of the router that is used to route chats in this room.
brand_id ID 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_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 date/time read-only When these room settings were created.
updated_at date/time read-only When these room settings were updated last time.

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:

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:

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 ID read-only The unique identifier of this domain link.
organization_id ID read-only ID of the organization who owns this domain link.
organization object read-only The organization who owns this domain link.
room_id ID 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 ID read-only ID of the domain room.
domain_room object read-only The [domain room][] which has access to this domain link.
created_at date/time read-only When this domain link was created.
updated_at date/time read-only When this domain link was updated last time.

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:

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:

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:

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.

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 ID 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 date/time 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 date/time 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.
Attribute Type Description
pipeline_step_index integer Number of the current pipeline step of the visitor starting from 1, or null if not in a pipeline.
pipeline_step_name string Name of the current pipeline step of the visitor, or null if not in a pipeline.
pipeline_step_count integer The total number of steps in the pipeline, or null if not in a pipeline.
legacy_id string Visitor’s chat_id in older format. This attribute should not be used anywhere and it will be removed as soon as possible.

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:

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:

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:

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:

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:

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 date/time When the visitor visited the page.
room_id ID 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:

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:

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.

A visitor room variable has the following attributes:

Attribute Type Editable Description
room_id ID 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:

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

Example response:

[{
    "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:

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:

Or alternatively:

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

This endpoint returns:

Or

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

This endpoint returns:

Or alternatively at the given room:

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

This endpoint returns:

Create a chat visitor variable

Example request:

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": "JohnSmith"
}

Example response:

{
    "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 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:

Or alternatively:

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

This endpoint returns:

Update existing visitor variable

Example request:

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"
}

Example response:

{
    "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 it’s 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:

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:

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:

Or alternatively:

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

This endpoint returns:

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 ID 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 date/time read-only When the ban was created.
ends_at date/time 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:

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

Example response:

{
    "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:

Chat API

Chats

A chat represents a single conversation. In practice, there is usually zero or one visitor member and an arbitrary number of user (“operator”) members.

A chat has the following attributes:

Attribute Type Editable Description
id ID read-only Unique identifier for the chat.
created_at date/time read-only When the chat conversation started.
updated_at date/time read-only When the chat conversation was last time updated.
waiting_started_at date/time read-only When the chat became waiting. This is is the timestamp when the is_waiting attribute changed true. It does not change when the is_waiting becomes false. Default value for this is null and it stays so if the chat never became waiting.
is_ended boolean optional Whether or not the chat has ended. Once ended, messages and members of the chat cannot be altered any more. Updating this to true immediately and permanently locks the chat. Defaults to false.
ended_at date/time read-only When the chat conversation ended (or null if not ended).
room_id ID read-only ID of the room in which the chat occurred.
room_name string read-only Name of the room in which the chat occurred.
room_organization_id ID read-only ID of the organization which owns the room in which the chat occurred.
is_private boolean read-only Whether or not the chat is marked as private for its operators.
is_real_conversation boolean read-only Whether or not the chat is an actual conversation.
is_autosuggested boolean read-only Whether or not the chat started with an automatic autosuggestion message.
is_encrypted boolean read-only Whether or not the messages of this chat are stored encrypted.
encrypted_symmetric_key string read-only The encrypted symmetric key (AES) with which all the chat messages in this chat are encrypted. This attribute is available only if is_encrypted is true.
message_count integer read-only How many messages there are in total in this chat at the moment. NOTE that this only includes messages with type msg, so this does not include autosuggestions, or join/leave messages.
user_message_count integer read-only How many messages there were by operators in this chat.
visitor_message_count integer read-only How many messages there were by visitors in this chat.
has_messages boolean read-only Whether or not there are any messages in chat.
has_user_messages boolean read-only Whether or not there are any user messages in chat.
has_visitor_messages boolean read-only Whether or not there are any visitor messages in chat.
first_visitor_message_url string read-only Full URL of the page that the visitor was on when they sent their first message to this chat, or null if contains no message from the visitor.
first_visitor_message_url_title string read-only Title of the page that the visitor was on when they sent their first message, or null if contains no message from the visitor.
autosuggest_url string read-only Full URL of the page that the visitor was on when they received an autosuggest, or null if this chat does not contain an autosuggestion.
autosuggest_url_title string read-only Title of the page that the visitor was on when they received an autosuggest, or null if this chat does not contain an autosuggestion.
tag_count integer read-only How many tags there are associated with this chat.
is_waiting boolean optional This is true for new chats that are started by a visitor and they require a response by a user (and the chat has not ended yet). Otherwise this is false.
is_pending boolean read-only This is true if is_waiting is true and the chat has no present user members (i.e. present_user_participant_count is 0). Otherwise this is false.
member_count integer read-only How many people (visitor and users) have attended or sent messages to this chat.
user_member_count integer read-only How many users have sent at least one message to the chat.
visitor_member_count integer read-only How many visitors have attended this chat.
present_participant_count integer read-only How many people (visitor and users) there are currently participating and present at this chat.
present_user_participant_count integer read-only How many users there are currently participating and present at this chat.
present_visitor_participant_count integer read-only How many visitor there are currently participating and present at this chat.
visitor_wait_time float read_only How many seconds the visitor had to wait for an answer to the first sent message. This is null if the visitor has not got an answer yet.
duration float read_only Duration of the chat in seconds. This is time difference from first message time to last message time in chat. This value is null until the chat has ended.
active_duration float read_only How many seconds of the chat duration was considered to be active time. This is calculated so that after each message chat is assumed to be active for 60 seconds and idle after that if no new messages are received. This value is null until the chat has ended.
Attribute Type Editable Description
token string read-only A legacy Giosg-signed encoded unique string for the chat. You probably won’t need this in new implementations!
legacy_conversation_state string read-only A legacy conversation state of the chat. You probably won’t need this in new implementations!
legacy_room_id string read-only A legacy ID of the chat’s room. You probably won’t need this in new implementations!

List chats at a room

GET https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/rooms/9926bdfa-56e0-11e5-b98c-6c4008c08dfe/chats
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/rooms/9926bdfa-56e0-11e5-b98c-6c4008c08dfe/chats?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "token": "uibdbtmk5etolmjaduaafnqpl2ujzkyr4slkq3cabdai37qm",
      "created_at": "2015-02-13T11:31:36.042",
      "ended_at": null,
      "waiting_started_at": null,
      "updated_at": "2015-02-13T12:38:36.431",
      "room_id": "9926bdfa-56e0-11e5-b98c-6c4008c08dfe",
      "room_name": "Customer Support",
      "room_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "is_private": false,
      "is_real_conversation": false,
      "is_autosuggested": false,
      "is_encrypted": true,
      "encrypted_symmetric_key": "0d59ab43b5704f08b2aec117658f4bc29a9b0c248547404298bb8a3f06eab7206455a0ddfa1d4972a364d7766eccb4ca",
      "message_count": 0,
      "user_message_count": 0,
      "visitor_message_count": 0,
      "has_messages": false,
      "has_user_messages": false,
      "has_visitor_messages": false,
      "first_visitor_message_url": "http://www.customerpage.com/settings",
      "first_visitor_message_url_title": "Profile Settings",
      "autosuggest_url": "http://www.customerpage.com/",
      "autosuggest_url_title": "Site Frontpage",
      "tag_count": 2,
      "is_waiting": true,
      "member_count": 2,
      "duration": 120,
      "active_duration": 77,
      "user_member_count": 1,
      "visitor_member_count": 1,
      "present_participant_count": 1,
      "present_user_participant_count": 1,
      "present_visitor_participant_count": 1,
      "legacy_conversation_state": "waiting",
      "legacy_room_id": "7sbjsyokgkdmyoifwyaafzll6sdthgar42sbv5c4rhds3yym"
    }
  ]
}

You can list chats for a room:

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

This API endpoint returns a paginated collection. They are sorted by the creation time of the chats, in descending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.
is_waiting boolean (none) If true, then return only waiting chats. If false, return only chats that are not waiting. You may usually want to list pending chats instead of using this.
is_ended boolean (none) If true, only return ended chats. If false, only return open chats.
has_messages boolean (none) If true, only return chats which have messages. If false, only return chats without messages.
has_user_messages boolean (none) If true, only return chats which have messages from user. If false, only return chats without messages from user.
has_visitor_messages boolean (none) If true, only return chats which have messages from visitor. If false, only return chats without messages from visitor.

This endpoint returns:

List organization’s owned chats

GET https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/owned_chats
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/owned_chats?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "token": "uibdbtmk5etolmjaduaafnqpl2ujzkyr4slkq3cabdai37qm",
      "created_at": "2015-02-13T11:31:36.042",
      "ended_at": null,
      "waiting_started_at": null,
      "updated_at": "2015-02-13T12:38:36.431",
      "room_id": "9926bdfa-56e0-11e5-b98c-6c4008c08dfe",
      "room_name": "Customer Support",
      "room_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "is_private": false,
      "is_real_conversation": false,
      "is_autosuggested": false,
      "is_encrypted": true,
      "encrypted_symmetric_key": "0d59ab43b5704f08b2aec117658f4bc29a9b0c248547404298bb8a3f06eab7206455a0ddfa1d4972a364d7766eccb4ca",
      "message_count": 0,
      "user_message_count": 0,
      "visitor_message_count": 0,
      "has_messages": false,
      "has_user_messages": false,
      "has_visitor_messages": false,
      "first_visitor_message_url": "http://www.customerpage.com/settings",
      "first_visitor_message_url_title": "Profile Settings",
      "autosuggest_url": "http://www.customerpage.com/",
      "autosuggest_url_title": "Site Frontpage",
      "tag_count": 2,
      "is_waiting": true,
      "member_count": 2,
      "user_member_count": 1,
      "visitor_member_count": 1,
      "present_participant_count": 1,
      "present_user_participant_count": 1,
      "present_visitor_participant_count": 1,
      "legacy_conversation_state": "waiting",
      "legacy_room_id": "7sbjsyokgkdmyoifwyaafzll6sdthgar42sbv5c4rhds3yym"
    }
  ]
}

You can list owned chats for an organization:

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

This API endpoint returns a paginated collection of owned chats. These are chats that belong to rooms owned by the organization. They are sorted by the creation time of the chats, in descending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.
is_waiting boolean (none) If true, then return only waiting chats. If false, return only chats that are not waiting. You may usually want to list pending chats instead of using this.
is_ended boolean (none) If true, only return ended chats. If false, only return open chats.
has_messages boolean (none) If true, only return chats which have messages. If false, only return chats without messages.
has_user_messages boolean (none) If true, only return chats which have messages from user. If false, only return chats without messages from user.
has_visitor_messages boolean (none) If true, only return chats which have messages from visitor. If false, only return chats without messages from visitor.

This endpoint returns:

Retrieve details of organization’s owned chat

You can retrieve details of organization’s owned chat:

GET /api/v5/orgs/<organization_id>/owned_chats/<chat_id>

This endpoint returns:

List organization’s involved chats

You can list chats where users of an organization are members of:

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

This API endpoint returns a paginated collection of involved chats, chats that have at least one chat membership of a user that belongs to the organization. They are sorted by the creation time of the chats, in descending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.
is_waiting boolean (none) If true, then return only waiting chats. If false, return only chats that are not waiting. You may usually want to list pending chats instead of using this.
is_ended boolean (none) If true, only return ended chats. If false, only return open chats.
has_messages boolean (none) If true, only return chats which have messages. If false, only return chats without messages.
has_user_messages boolean (none) If true, only return chats which have messages from user. If false, only return chats without messages from user.
has_visitor_messages boolean (none) If true, only return chats which have messages from visitor. If false, only return chats without messages from visitor.

This endpoint returns:

Retrieve details of organization’s involved chat

You can retrieve details of organization’s involved chat:

GET /api/v5/orgs/<organization_id>/involved_chats/<chat_id>

This endpoint returns:

List pending chats of a room

One of the most important use cases is that the users (chat “agents” or “operators”) want to serve visitors that have started a new chat. You can get a paginated collection of pending chats for a specific room that the user has permission:

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

This is a small subset of all the chats of the room, with the following differences:

This endpoint returns:

List pending chats of a user

You usually want to just show pending chats for all rooms the user has access to. One approach is to first list the user’s rooms and then get the pending chats for each room. However, there is a more convenient shortcut to get a paginated collection of pending chats of each room the user has access:

GET /api/v5/users/<user_id>/pending_chats

Please note that because this lists pending chats, whether or not the user is a member of the chat does not affect the listed chats.

This endpoint returns:

List routed chats of a user

This will list all the chats for every room where the user has been linked to using a router. This returns an ordered paginated collection of routed chats.

GET /api/v5/users/<user_id>/routed_chats

Please note that because this lists routed chats, whether or not the user is a member of the chat does not affect the listed chats.

This endpoint returns:

Retrieve details of user’s routed chat

You can retrieve details of user’s routed chat:

GET /api/v5/users/<user_id>/routed_chats/<chat_id>

This endpoint returns:

List chats of a user

You can get a collection of chats where user is a member:

GET /api/v5/users/<user_id>/chats

This returns a paginated collection. It is sorted by the creation time of the chat, in descending order.

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or updated_at (- for descending results).
is_participating boolean (none) If true, only return chats where <user_id> is participating. If false, exclude chats where <user_id> is currently participating.
is_ended boolean (none) If true, only return ended chats. If false, only return open chats.
has_messages boolean (none) If true, only return chats which have messages. If false, only return chats without messages.
has_user_messages boolean (none) If true, only return chats which have messages from user. If false, only return chats without messages from user.
has_visitor_messages boolean (none) If true, only return chats which have messages from visitor. If false, only return chats without messages from visitor.

This endpoint returns:

Create a new chat with a visitor in a room

Start a new chat with a visitor in the given room.

POST /api/v5/users/<user_id>/rooms/<room_id>/visitors/<visitor_id>/chats

Creating a new chat using this endpoint does not require any attributes and therefore the payload is not required. This endpoint will attempt to get an existing recent chat where the given user can join, instead of creating a new chat. In addition, we will automatically (and atomically) create a membership for this user and chat. NOTE: The “private chats” setting affects the decision whether to create or resume a chat.

This endpoint returns:

Create a new empty chat for user

Start a new chat without a visitor for user. Other users/teams/partner organizations can be invited to this chat by using chat invitations.

POST /api/v5/users/<user_id>/chats

Creating a new chat using this endpoint does not require any attributes and therefore the payload is not required.

This endpoint returns:

List visitor’s chats it a room

You can get a collection of chats where the visitor is a member, in the given room:

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

This returns paginated collection. It is sorted by the creation time of the chat, in descending order.

This endpoint returns:

End a chat

Example request that closes a chat

PUT https://service.giosg.com/api/v5/users/bed3221e-879e-43df-8d0e-d63f8c1f012d/chats/100067c3-2dda-4343-b403-1bb6caf1d14d

Example payload

{
    "is_ended": true
}

Conversations between users and visitors usually end automatically when no one has sent any messages to the chat after a certain time. However, users may also explicitly end the chat conversation.

Once ended, no new chat messages or chat memberships can be added to the chat anymore! Chat cannot be reopened. You should create a new chat if you want to continue conversation with the other person. This changes the chat’s is_waiting status to be false.

You can end explicitly a chat in which you are a member by updating the is_ended attribute to true:

PUT /api/v5/users/<user_id>/chats/<chat_id>

or

PATCH /api/v5/users/<user_id>/chats/<chat_id>

You need to define the is_ended attribute with value true as a payload.

This endpoint returns:

Change a chat to not waiting status

Example request that changes waiting status of a chat to not waiting

PUT https://service.giosg.com/api/v5/users/bed3221e-879e-43df-8d0e-d63f8c1f012d/chats/100067c3-2dda-4343-b403-1bb6caf1d14d

Example payload

{
    "is_waiting": false
}

You can explicitly change waiting status of a chat in which you are a member by updating the is_waiting attribute to false:

PUT /api/v5/users/<user_id>/chats/<chat_id>

or

PATCH /api/v5/users/<user_id>/chats/<chat_id>

You need to define the is_waiting attribute with value false as a payload.

This endpoint returns:

Chat memberships

The visitor as well as each user who have attended to the chat (i.e. they are “chat members”) are represented with a chat membership objects.

Attribute Format Editable Description
member_id ID/string read-only ID of the user or visitor being present at the chat.
member_type string read-only Either visitor or user.
member_name string read-only The name of the user/visitor as it would be displayed for the operator. For users this the actual name. For visitors this is any custom name, or null.
member_public_name string read-only The name of the user/visitor as it would be displayed for the visitor. This is user’s alias if they have one, otherwise it is their real name. For visitors, this is any custom username (e.g. set by API data) or null
member_avatar object read-only If the user/visitor has an avatar image, then this is is an object with id and url attributes. Otherwise this is null.
member_organization_id ID read-only ID of the member’s organization.
room_id ID read-only ID of the room where the chat takes place.
room_organization_id ID read-only ID of the room’s organization where the chat takes place.
chat_id ID read-only ID of the chat.
created_at date/time read-only When the user/visitor was added as a chat member.
updated_at date/time read-only When the this membership was updated.
chat_created_at date/time read-only When the chat started.
message_count integer read-only How many messages the user/visitor has sent to the chat. This may be 0, e.g. when operator has joined the chat but has not sent any message yet.
is_participating boolean required Whether or not the user/visitor has the chat “open”. In practise this reflects the state of the chat window. When the user/visitor closes the chat window, it is supposed that he is no more participating the chat (but the membership still remains)
is_present boolean read-only Whether or not the user/visitor is currently present. Equals the is_present attribute of the member.
composing_status string required One of the following: idle, typing, typed. The typing status will be automatically downgraded to typed if the composing status has not been refreshed for a while.
Attribute Type Editable Description
legacy_member_id string read-only A legacy ID of the user. You probably won’t need this in new implementations!

List chat memberships

GET /api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/rooms/aad26fe2-c8f3-45dc-931b-4b0b5e06467d/chats/58f5055c-56e0-11e5-9354-6c4008c08dfe/memberships
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/chats/58f5055c-56e0-11e5-9354-6c4008c08dfe/memberships?cursor=45d9e7358e1249c491b4fa0212310f55",
  "previous": null,
  "results": [
    {
      "member_id": "378ad5a0-bb89-481b-978b-4268b368cfef",
      "member_type": "user",
      "member_name": "John Smith",
      "member_public_name": "Customer Service",
      "member_avatar": {
        "id": "7f9cb877-0fd9-4c27-90b0-bd4c2842da3d",
        "url": "http://www.example.com/avatar/5ef1a0ef-8b61-4473-8706-9669e30b47e6.jpg"
      },
      "member_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "chat_id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "room_id": "e39930de-0957-11e7-87e4-f45c89c72de3",
      "room_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "created_at": "2015-02-13T11:31:36.042",
      "updated_at": "2015-02-13T11:32:36.042",
      "chat_created_at": "2015-02-13T11:30:36.042",
      "is_participating": true,
      "is_present": true,
      "composing_status": "idle",
      "message_count": 8
    },
    {
      "member_id": "3b90ef7c93484af4965a79ace7bc9a62",
      "member_type": "visitor",
      "member_name": null,
      "member_public_name": null,
      "member_avatar": null,
      "member_organization_id": null,
      "chat_id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "room_id": "e39930de-0957-11e7-87e4-f45c89c72de3",
      "room_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "created_at": "2015-02-13T12:14:34.154",
      "updated_at": "2015-02-13T12:15:34.154",
      "chat_created_at": "2015-02-13T11:30:36.042",
      "is_participating": true,
      "is_present": true,
      "composing_status": "typing",
      "message_count": 7
    }
  ]
}

You can get a paginated collection of all the memberships of the chat:

GET /api/v5/orgs/<organization_id>/rooms/<room_id>/chats/<chat_id>/memberships

This endpoint returns:

Or alternatively:

GET /api/v5/users/<user_id>/chats/<chat_id>/memberships

This endpoint returns:

Or alternatively you can list memberships of a routed chat of the user:

/api/v5/users/<user_id>/routed_chats/<chat_id>/memberships

This endpoint returns:

Or list organization’s owned chat’s memberships:

GET /api/v5/orgs/<organization_id>/owned_chats/<chat_id>/memberships

This endpoint returns:

Or list organization’s involved chat’s memberships:

GET /api/v5/orgs/<organization_id>/involved_chats/<chat_id>/memberships

This endpoint returns:

Also, as an alternative to list a user’s chats, you may list their own chat memberships. Each result is a chat member resource for each of the chat of the user:

GET /api/v5/users/<user_id>/chat_memberships

This endpoint takes the following GET-parameters:

Parameter Type Default Description
is_participating boolean (none)  If true, then return only chats where user is participating. If false, return only chats where user is not participating.

This endpoint returns:

List chat memberships of all active chats

You can list the chat memberships for any active (non-closed) chat at a room to which the user has a permission. This excludes chats with only autosuggest message. This is useful in cases where you want to, for example, show which of the visitors are currently chatting! You can also use this endpoint as an immediate “table” for “joining” the visitors to pending chats.

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

This endpoint returns:

List visitor’s chat memberships

You can get a paginated collection of all the memberships of the visitor by chat:

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

This endpoint returns:

List pending chat’s memberships

You can get a paginated collection of pending chat’s memberships:

GET /api/v5/users/<user_id>/pending_chats/<chat_id>/memberships

This endpoint returns:

Join user to a pending chat

Example request for joining a user to a chat

POST https://service.giosg.com/api/v5/users/0f34f1b2-2922-4a2e-9706-8cca0a1b3eec/pending_chats/62eb5cd5-5d52-4bb1-b711-ba31f864e775/memberships

Example request payload

{
  "is_participating": true,
  "composing_status": "idle"
}

You can add your user as a member to one of their pending chats:

POST /api/v5/users/<user_id>/pending_chats/<chat_id>/memberships

You should define whether you want to be participating the chat with is_participating. You usually want to set this true when creating a new membership. Also, the composing_status is required, but may usually want to set it initially to idle.

If you want to prevent other users “taking” this pending chat, then ensure that

The chat will then be marked as “non-pending” and the chat is removed from “pending chats” of other users. However, if your user becomes absent before sending any messages to the chat, then the chat is returned to “pending chats” (but your user will still remain a chat member).

This endpoint returns:

Join user to a routed chat

Example request for joining a user to a routed chat

POST https://service.giosg.com/api/v5/users/0f34f1b2-2922-4a2e-9706-8cca0a1b3eec/routed_chats/62eb5cd5-5d52-4bb1-b711-ba31f864e775/memberships

Example request payload

{
  "is_participating": true,
  "composing_status": "idle"
}

You can add your user as a member to one of their routed chats:

POST /api/v5/users/<user_id>/routed_chats/<chat_id>/memberships

You should define whether you want to be participating the chat with is_participating. You usually want to set this true when creating a new membership. Also, the composing_status is required, but may usually want to set it initially to idle.

This endpoint returns:

Join user to a organization’s chat

Example request for joining a organization’s user to a chat

POST https://service.giosg.com/api/v5/orgs/0f34f1b2-2922-4a2e-9706-8cca0a1b3eec/owned_chats/62eb5cd5-5d52-4bb1-b711-ba31f864e775/memberships

Example request payload

{
  "member_id": "2ffbfa02-c1f1-11e6-87fa-f45c89c72de3",
  "is_participating": true,
  "composing_status": "idle"
}

You can add your organization’s user as a member to a organization’s owned chats:

POST /api/v5/orgs/<organization_id>/owned_chats/<chat_id>/memberships

This endpoint returns:

Or you may join to your organization’s involved chat:

POST /api/v5/orgs/<organization_id>/involved_chats/<chat_id>/memberships

This endpoint returns:

You should define whether you want to be participating the chat with is_participating. You usually want to set this true when creating a new membership. Also, the composing_status is required, but may usually want to set it initially to idle. Note that the member_id is required field for this endpoint.

If is_participating is set as true and the chat was pending, then this will remove this chat from pending chats for all users.

Update a chat membership of a user

Example request for making the operator typing at the chat

PUT https://service.giosg.com/api/v5/users/ce771dbe-afbf-4e58-bbcb-9855ecacee9a/chat_memberships/62eb5cd5-5d52-4bb1-b711-ba31f864e775

Example request payload

{
  "is_participating": true,
  "composing_status": "typing"
}

The chat membership’s is_participating attribute should be refreshed when the user opens or closes a chat.

In addition, you should frequently notify the backend about the composing status of the user. For example, you should make a request when the user starts typing a message for the chat (and more requests frequently if the user keeps typing, stops typing or clears the composition area).

You can change the chat status of the user similarly than described in the previous session:

PUT /api/v5/users/<user_id>/chat_memberships/<chat_id>

You should provide the is_participating attribute with either true or false value, indicating whether or not the user should be currently present at the chat. Also, you need to provide the composing_status attribute describing whether or not the user is typing or has typed a message.

This endpoint returns:

Chat messages

Chat consists of a number of messages. Some of them are actual typed messages from either operator or visitor, and some of them are automatically added events about the chat, especially when an operator has joined or leaved the chat.

Attribute Type Editable Description
id ID read-only Unique identifier for the message
type string read-only Whether the message is an actual message (msg), autosuggest (autosuggest), a join event (join), a leave event (leave), a shopping cart locked event (shoppingcart_locked), an action event (action) from attachment reaction, or a message from system (system). When POSTing a message, this will automatically be set to msg.
chat_id ID read-only ID of the chat.
room_id ID read-only ID of the room in which the chat occurred.
created_at date/time read-only When the message was sent.
sender_type string read-only Whether the sender is operator (user), visitor (visitor), or triggered by rule (rule). When POSTing a new message with these endpoints, this will automatically be set to user.
sender_id ID/string read-only Identifier for the sender. If the sender is a user, then this is the user’s ID. For visitor this is an unique string. If the sender was a rule, it is the ID of the rule which triggered this message.
sender_public_name string read-only A display name for the sender as the visitor would see him. This value might change if the sender type was rule.
sender_name string read-only A display name for the sender as an operator would see him. This value might change if the sender type was rule.
sender_avatar object read-only If the sender has an avatar image, then this is an object with id and url attributes. Otherwise this is null.
message string required Content text of the message. The maximum length is 2000 characters. This will always be the decrypted if the decryption key is still being stored at the server. Otherwise, this will be null if the server cannot decrypt the message any more. In this case your client needs to decrypt the chiphertext in encrypted_message. In cases where the chat message’s type was action, this can be either the text of the chosen attachment action or title of the attachment. If neither are provided, this is null.
is_encrypted boolean read-only Whether or not the message is stored encrypted. When true, the encrypted_message attribute contains the encrypted chiphertext of the message.
encrypted_message string read-only The encrypted chiphertext of the message, if encryption is used for the chat. This attribute is only present if is_encrypted is true.
sensitive_data_purged_at date/time read-only When the message’s sensitive data was purged. This means that the message and visitor’s sender_name and sender_public_name are set as null. This is null if the data was not purged.
selected_reply_suggestion_id ID optional The chat reply suggestion that was selected as a basis for this message. NOTE: the message may differ from the suggestion of the related suggestion, if the user has edited the selected suggestion message before sending it! This is null if the message is not based on any chat reply suggestion.
selected_reply_suggestion object read-only The selected chat reply suggestion as a nested object, containing attributes id, suggestion, and relevancy_score. This is nullif the message is not based on any chat reply suggestion.
attachments list of objects optional List of chat message attachments for this chat message. These represent rich or interactive content provided in this message. These are explained in next section.
response_to_message_id ID read-only Unique identifier of the message this was a response to. null if it wasn’t a response.
response_to_attachment_id ID read-only Unique identifier of the chosen attachment this was a response to. null if it wasn’t a response.
response_to_attachment object read-only The chosen attachment of the response. null if it wasn’t a response.
response_to_action_id ID read-only Unique identifier of the chosen attachment action this was a response to. null if it wasn’t a response.
response_to_action object read-only The chosen attachment action of the response. null if it wasn’t a response.
response_value string read-only The chosen attachment value of the response. If the chosen attachment was an action, then this is the value of the action. Otherwise this may be the attachment’s title_link_url, image_url, image_link_url or a link provided in text field (Markdown). null if it wasn’t a response.

List chat messages

GET /api/v5/orgs/54de4830-a16e-417a-802b-4bf4bcb59ed8/owned_chats/450fc49e-277e-4dd6-af0f-6e9dcb885b09/messages
{
  "next": "https://service.giosg.com/api/v5/orgs/54de4830-a16e-417a-802b-4bf4bcb59ed8/owned_chats/450fc49e-277e-4dd6-af0f-6e9dcb885b09/messages?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "8a94b3f1-d8a9-4530-b1f1-b757a8a57078",
      "type": "autosuggest",
      "chat_id": "450fc49e-277e-4dd6-af0f-6e9dcb885b09",
      "room_id": "1b6ba2e1-bfe0-11e8-8c3f-8c8590c2eeca",
      "created_at": "2015-02-13T11:30:03.045",
      "sender_type": "user",
      "sender_id": "7c94ae79-a4b4-4eea-ac23-24c16f910080",
      "sender_public_name": "Customer Service",
      "sender_name": "John Smith",
      "message": "How may I help you?",
      "is_encrypted": false,
      "sensitive_data_purged_at": null,
      "selected_reply_suggestion_id": null,
      "selected_reply_suggestion": null,
      "attachments": [],
      "response_to_message_id": null,
      "response_to_attachment_id": null,
      "response_to_attachment": null,
      "response_to_action_id": null,
      "response_to_action": null,
      "response_value": null
    },
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "type": "msg",
      "chat_id": "450fc49e-277e-4dd6-af0f-6e9dcb885b09",
      "room_id": "1b6ba2e1-bfe0-11e8-8c3f-8c8590c2eeca",
      "created_at": "2015-02-13T11:31:36.042",
      "sender_type": "visitor",
      "sender_id": "f7a5a3b83d2e40dfb0dedd6c0e284214",
      "sender_public_name": null,
      "sender_name": null,
      "message": "Yes, actually you could.",
      "is_encrypted": false,
      "sensitive_data_purged_at": null,
      "selected_reply_suggestion_id": null,
      "selected_reply_suggestion": null,
      "attachments": [],
      "response_to_message_id": null,
      "response_to_attachment_id": null,
      "response_to_attachment": null,
      "response_to_action_id": null,
      "response_to_action": null,
      "response_value": null
    },
    {
      "id": "a3a3b8ed-7336-431a-8350-8f5be471a09e",
      "type": "join",
      "chat_id": "450fc49e-277e-4dd6-af0f-6e9dcb885b09",
      "room_id": "1b6ba2e1-bfe0-11e8-8c3f-8c8590c2eeca",
      "created_at": "2015-02-13T11:31:38.123",
      "sender_type": "user",
      "sender_id": "7c94ae79-a4b4-4eea-ac23-24c16f910080",
      "sender_public_name": "Customer Service",
      "sender_name": "John Smith",
      "message": null,
      "is_encrypted": false,
      "sensitive_data_purged_at": null,
      "selected_reply_suggestion_id": null,
      "selected_reply_suggestion": null,
      "attachments": [],
      "response_to_message_id": null,
      "response_to_attachment_id": null,
      "response_to_attachment": null,
      "response_to_action_id": null,
      "response_to_action": null,
      "response_value": null
    },
    {
      "id": "487a4dce-503a-43d0-bd62-1e1a7582c93b",
      "type": "msg",
      "chat_id": "450fc49e-277e-4dd6-af0f-6e9dcb885b09",
      "room_id": "1b6ba2e1-bfe0-11e8-8c3f-8c8590c2eeca",
      "created_at": "2015-02-13T11:32:01.654",
      "sender_type": "user",
      "sender_id": "7c94ae79-a4b4-4eea-ac23-24c16f910080",
      "sender_public_name": "Customer Service",
      "sender_name": "John Smith",
      "message": "OK, what do you want to know?",
      "is_encrypted": false,
      "sensitive_data_purged_at": null,
      "selected_reply_suggestion_id": null,
      "selected_reply_suggestion": null,
      "attachments": [],
      "response_to_message_id": null,
      "response_to_attachment_id": null,
      "response_to_attachment": null,
      "response_to_action_id": null,
      "response_to_action": null,
      "response_value": null
    }
  ]
}

Get the collection of all chat messages in the given chat if it’s organization’s owned chat.

GET /api/v5/orgs/<organization_id>/owned_chats/<chat_id>/messages

This endpoint returns:

Or if the organization is involved in the chat:

GET /api/v5/orgs/<organization_id>/involved_chats/<chat_id>/messages

This endpoint returns:

Or alternatively:

GET /api/v5/users/<user_id>/chats/<chat_id>/messages

This endpoint returns:

Or alternatively list messages of user’s routed chat:

GET /api/v5/users/<user_id>/routed_chats/<chat_id>/messages

This endpoint returns:

The response is a paginated collection, ordered by the creation date in descending order.

Send a chat message

POST /api/v5/users/7c94ae79-a4b4-4eea-ac23-24c16f910080/chats/9d25ef9d-26ed-40e8-8d74-a6a17039195d/messages
{
  "message": "OK, I've found out the issue!"
}

Send a new chat message to a user’s chat with type msg to a chat:

POST /api/v5/users/<user_id>/chats/<chat_id>/messages

The <user_id> will be set as the sender of the message.

If the chat was previously in waiting state, then is_waiting of the chat is automatically changed to false.

You may also include the chat_reply_suggestion_id attribute with an ID of any chat reply suggestion in the same chat.

This endpoint returns:

Chat message attachments

Chat message attachments represent rich or interactive content for chat message. You may provide images, buttons etc. as attachment with actions for different scenarios. You might want to consider reading the chat message attachment guide before using these. An attachment object consists:

Attribute Format Editable Description
id ID read-only ID of the attachment.
title string optional The title of this attachment.
title_link_url string optional The URL of the title. If provided, then title will show as clickable link which will open in the given URL.
text string optional The text part of this attachment. This may serve as description. This can also be Markdown (bold, cursive or link).
image_url string optional The URL of image.
image_link_url string optional The URL of image link. If provided, then the image will show as clickable image which will open in the given URL.
link_target string optional The target URL of the image_link_url and title_link_url. This value is omitted if no links are provided, otherwise this defines whether the link is opened in a new tab or redirects current tab to a new URL. Valid choices for this are _blank (open new tab) and _parent (redirect in current tab). Defaults to _blank.
actions list of objects optional List of possible actions for this attachment. These are explained in next section.

NOTE: If none of the fields; title, text, image_url or actions is provided, then 400 is returned.

An attachment may have multiple actions. For example you might want to provide feedback survey as an attachment and have multiple different buttons as answer options. For now actions are always buttons with different kind of outcomes. An attachment action object consists:

Attribute Format Editable Description
id ID read-only ID of the action.
text string required The text of this action. The text will be shown inside the button when rendered to the user interface.
type string required The type of this action. This can be button or link_button.
link_target string optional The target URL of the link_button. This value is omitted if the type of this action is not link_button, otherwise this defines whether the link is opened in a new tab or redirects current tab to a new URL. Valid choices for this are _blank (open new tab) and _parent (redirect in current tab). Defaults to _blank.
value string required The value for this action. For action with type of link_button this should be either a valid URL (For example: https://giosg.com/contact-us) where the button should redirect or an anchor link (For example: #contact-us) that navigates to an anchor inside the current page. Otherwise, the value can be any string.
style string optional Style of the action. This can be primary, secondary, info, success, warning, danger, link, brand_primary or brand_secondary. This defines color of the button. If omitted, defaults to secondary. Brand colors defined for a Room can be used aswell.
is_disabled_on_selection boolean required Defines whether the actions are disabled after selection. If true then all of the attachment’s actions with true for is_disabled_on_selection are disabled after selection of one. If false then the action remains enabled after selection.
is_disabled_on_visitor_message boolean required Defines whether the actions are disabled after visitor sends a new message to chat conversation. This message’s type has to be msg (a real message). If true then all of the attachment’s actions with true for is_disabled_on_visitor_message are disabled after the visitor’s message. If false then the action remains enabled after visitor message.

Send a chat message with attachments

POST /api/v5/users/7c94ae79-a4b4-4eea-ac23-24c16f910080/chats/9d25ef9d-26ed-40e8-8d74-a6a17039195d/messages
{
  "message": "Do you want help?",
  "attachments": [
    {
      "text": "Was this conversation helpful?",
      "actions": [
        {
          "text": "Yes",
          "type": "button",
          "value": "yes",
          "style": "success",
          "is_disabled_on_selection": true,
          "is_disabled_on_visitor_message": false
        },
        {
          "text": "Maybe",
          "type": "button",
          "value": "maybe",
          "is_disabled_on_selection": true,
          "is_disabled_on_visitor_message": false
        },
        {
          "text": "No",
          "type": "button",
          "value": "no",
          "style": "danger",
          "is_disabled_on_selection": true,
          "is_disabled_on_visitor_message": false
        }
      ]
    }
  ]
}

Sending a chat message with attachments is no different than sending chat message normally. You can provide additional attachments list (optionally with desired actions too) along the message in the payload.

Chat message response actions

{
  "id": "899042d4-4aaf-11e7-899c-f45c89c72de3",
  "type": "action",
  "chat_id": "9d25ef9d-26ed-40e8-8d74-a6a17039195d",
  "room_id": "322ca9c0-bfe0-11e8-8ff3-8c8590c2eeca",
  "created_at": "2017-06-13T11:30:03.045",
  "sender_type": "visitor",
  "sender_id": "a3fedae14aaf11e7a05ef45c89c72de3",
  "sender_public_name": null,
  "sender_name": null,
  "message": "Yes",
  "is_encrypted": false,
  "sensitive_data_purged_at": null,
  "selected_reply_suggestion_id": null,
  "selected_reply_suggestion": null,
  "attachments": [],
  "response_to_message_id": "8a94b3f1-d8a9-4530-b1f1-b757a8a57078",
  "response_to_attachment_id": "4ee16b6b-4b4d-11e7-9eaa-f45c89c72de3",
  "response_to_action_id": "605dc7c0-4ab3-11e7-94ab-f45c89c72de3",
  "response_to_action": {
    "id": "605dc7c0-4ab3-11e7-94ab-f45c89c72de3",
    "text": "Yes",
    "type": "button",
    "value": "yes",
    "style": "success",
    "is_disabled_on_selection": true
  }
}

In most cases you might want to know which attachment the visitor selected. These responses can be done by using public API for sending chat message. For now these responses can be requested by using the list API of chat messages. The message type of these are action and they contain additional info about the selected attachment/action.

Chat invitations

User may invite users, teams or partner organizations to ongoing chat. This is done with invitation objects. When sending and managing chat invitations, we use chat invitations.

An chat invitation object has the following attributes::

Attribute Type Editable Description
id ID read-only Unique identifier of this invitation
is_accepted boolean required Whether or not the chat invitation has been accepted.
is_expired boolean read-only Whether or not the chat invitation has been expired. Chat invitation will expire if it’s not accepted before visitor leaves.
invited_by_user_id ID read-only ID of the user who invited.
invited_by_user object read-only The User who invited.
chat_id ID read-only ID of the chat.
room_id ID read-only ID of the room in which the chat occurred.
invited_user_id ID required ID of the user who was invited.
invited_team_id ID required ID of the team which was invited.
invited_organization_id ID required ID of the organization which was invited.
invitee_name string read-only Name of the invitee. This is either full name of the user, name of the team, or name of the organization depending on which party was invited.
accepted_by_user_id ID read-only ID of the user who accepted invite.
accepted_by_user object read-only The User who accepted invite.
user_member_count integer read-only How many [User][user members] are in this chat.
visitor_member_count integer read-only How many [Visitor][visitor members] are in this chat.
created_at date/time read-only When the chat invitation was sent.
updated_at date/time read-only When the chat invitation was last time updated.
accepted_at date/time read-only When the chat invitation was accepted (or null if not accepted).

NOTE: Only one of the invited_user_id, invited_team_id or invited_organization_id can be defined per chat invitation object. Other two attributes should be either null or omitted.

List outgoing chat invitations for user

GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/f8a3917d-9073-11e6-b96f-f45c89c72de3/outgoing_chat_invitations
{
  "next": "https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/f8a3917d-9073-11e6-b96f-f45c89c72de3/outgoing_chat_invitations",
  "previous": null,
  "results": [
    {
      "id": "4d0648b8-9074-11e6-963e-f45c89c72de3",
      "is_accepted": true,
      "is_expired": false,
      "invited_by_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
      "invited_by_user": {
        "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
        "full_name": "Bill Giosg",
        "first_name": "Bill",
        "last_name": "Giosg",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3"
      },
      "chat_id": "f8a3917d-9073-11e6-b96f-f45c89c72de3",
      "room_id": "f4cd6ad7-9072-11e6-84ab-f45c89c72de3",
      "invited_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "invited_team_id": null,
      "invited_organization_id": null,
      "invitee_name": "Bob von Helper",
      "accepted_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "accepted_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Bob von Helper",
        "first_name": "Bob",
        "last_name": "von Helper",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3"
      },
      "user_member_count": 1,
      "visitor_member_count": 1,
      "created_at": "2016-09-01T11:31:36.042Z",
      "updated_at": "2016-09-01T15:31:36.042Z",
      "accepted_at": "2016-09-01T16:31:36.042Z"
    },
  ]
}

You can get a paginated collection of all the outgoing chat invitations for the user in current chat. They are sorted by the creation time of the invitation, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
is_accepted boolean (none) If true, then return only accepted chat invitations. If false, return only chat invitations which are pending but are not expired.
is_expired boolean (none)  If true, then return only expired chat invitations. If false, return only chat invitations which has not expire.

GET /api/v5/users/<user_id>/chats/<chat_id>/outgoing_chat_invitations

This endpoint returns:

Send a chat invitation

Example request that send a chat invitation for a user from own organization

POST https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/f8a3917d-9073-11e6-b96f-f45c89c72de3/outgoing_chat_invitations
{
  "invited_user_id": "006ff599-9073-11e6-a887-f45c89c72de3"
}

Example response

{
  "id": "4d0648b8-9074-11e6-963e-f45c89c72de3",
  "is_accepted": false,
  "is_expired": false,
  "invited_by_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
  "invited_by_user": {
    "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
    "full_name": "Bill Giosg",
    "first_name": "Bill",
    "last_name": "Giosg",
    "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3"
  },
  "chat_id": "f8a3917d-9073-11e6-b96f-f45c89c72de3",
  "room_id": "f4cd6ad7-9072-11e6-84ab-f45c89c72de3",
  "invited_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
  "invited_team_id": null,
  "invited_organization_id": null,
  "invitee_name": "Bob von Helper",
  "accepted_by_user_id": null,
  "accepted_by_user": null,
  "user_member_count": 1,
  "visitor_member_count": 1,
  "created_at": "2016-09-01T11:31:36.042Z",
  "updated_at": "2016-09-01T11:31:36.042Z",
  "accepted_at": null
}

You may send a chat invitation to your organization’s users, teams or partner organizations by creating a new chat invitation object.

POST /api/v5/users/<user_id>/chats/<chat_id>/outgoing_chat_invitations

You need to define only one of the invited_user_id, invited_team_id or invited_organization_id attributes as a payload.

This endpoint returns:

List incoming chat invitations for the user

GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/incoming_chat_invitations
{
  "next": "https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/incoming_chat_invitations",
  "previous": null,
  "results": [
    {
      "id": "6d348a30-9076-11e6-8756-f45c89c72de3",
      "is_accepted": false,
      "is_expired": false,
      "invited_by_user_id":  "006ff599-9073-11e6-a887-f45c89c72de3",
      "invited_by_user": {
        "id":  "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Bob von Helper",
        "first_name": "Bob",
        "last_name": "von Helper",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3"
      },
      "chat_id": "f8a3917d-9073-11e6-b96f-f45c89c72de3",
      "room_id": "f4cd6ad7-9072-11e6-84ab-f45c89c72de3",
      "invited_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
      "invited_team_id": null,
      "invited_organization_id": null,
      "invitee_name": "Bill Giosg",
      "accepted_by_user_id": null,
      "accepted_by_user": null,
      "user_member_count": 1,
      "visitor_member_count": 1,
      "created_at": "2016-09-01T15:31:36.042Z",
      "updated_at": "2016-09-01T15:31:36.042Z",
      "accepted_at": null
    },
  ]
}

You can get a paginated collection of all the incoming chat invitations for the user. They are sorted by the creation time of the invitation, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
is_accepted boolean (none) If true, then return only accepted chat invitations. If false, return only chat invitations which are pending but are not expired.
is_expired boolean (none)  If true, then return only expired chat invitations. If false, return only chat invitations which has not expire.

GET /api/v5/users/<user_id>/incoming_chat_invitations

This endpoint returns:

Accept incoming chat invitation

Example request that accepts the chat invitation for user

PATCH https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/f8a3917d-9073-11e6-b96f-f45c89c72de3/incoming_chat_invitations/6d348a30-9076-11e6-8756-f45c89c72de3
{
  "is_accepted": true
}

You may accept your user’s incoming chat invitations.

PUT /api/v5/users/<user_id>/incoming_chat_invitations/<invitation_id>

PATCH /api/v5/users/<user_id>/incoming_chat_invitations/<invitation_id>

This endpoint returns:

Chat tags

Chats may be tagged with any number of keywords, or simply put “tags”.

A chat tag has the following attributes:

Attribute Type Editable Description
name string required The name of the tag.
created_at date/time read-only When the chat was tagged with this tag.
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 ID read-only ID of the room to which this tag belongs to.

List tags of a chat

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

You can get a paginated collection of all the tags for one of a user’s chats:

GET /api/v5/users/<user_id>/chats/<chat_id>/tags

This endpoint returns:

Alternatively you may want to retrieve tags by using the organization:

You can get all the tags for a organization’s owned chat:

GET /api/v5/orgs/<organization_id>/owned_chats/<chat_id>/tags

This endpoint returns:

And for the organization’s involved chat:

GET /api/v5/orgs/<organization_id>/involved_chats/<chat_id>/tags

This endpoint returns:

List allowed tags for a chat

GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/3c43e25a-54d4-46de-9b1d-13ff39df30b7/allowed_tags
{
  "next": "https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/3c43e25a-54d4-46de-9b1d-13ff39df30b7/allowed_tags?cursor=c42126a86cf547b1a9742d480950a981",
  "previous": null,
  "results": [
    {
      "name": "Lead",
      "created_at": "2016-09-01T11:31:36.042Z",
      "hashed_name": "cf23df2207d99a74fbe169e3eba035e633b65d94",
      "room_id": "3c43e25a-54d4-46de-9b1d-13ff39df30b8"
    },
    {
      "name": "Premium customer",
      "created_at": "2016-09-01T12:20:12.206Z",
      "hashed_name": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
      "room_id": "3c43e25a-54d4-46de-9b1d-13ff39df30b8"
    },
    {
      "name": "Support",
      "created_at": "2016-09-01T13:14:01.030Z",
      "hashed_name": "85136c79cbf9fe36bb9d05d0639c70c265c18d37",
      "room_id": "3c43e25a-54d4-46de-9b1d-13ff39df30b8"
    }
  ]
}

You can get a paginated collection of all the tags that are allowed for one of a user’s chats. The allowed tags are defined by the room to which the chat belongs.

GET /api/v5/users/<user_id>/chats/<chat_id>/allowed_tags

This endpoint returns:

Alternatively you may want to retrieve allowed tags by using the organization:

You can get all the allowed tags for a organization’s owned chat:

GET /api/v5/orgs/<organization_id>/owned_chats/<chat_id>/allowed_tags

This endpoint returns:

And for the organization’s involved chat:

GET /api/v5/orgs/<organization_id>/involved_chats/<chat_id>/allowed_tags

This endpoint returns:

Add a tag to a chat

Example request that adds a tag to a chat

POST https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/1d3885ef-a151-4cb1-b289-69123f142a8a/tags
{
  "name": "Lead"
}

Example response

{
  "name": "Lead",
  "hashed_name": "85136c79cbf9fe36bb9d05d0639c70c265c18d37",
  "created_at": "2016-09-01T11:31:36.042Z"
}

You can add a tag to one of the user’s chats:

POST /api/v5/users/<user_id>/chats/<chat_id>/tags

This endpoint returns:

Alternatively you may want to add tags by using the organization:

You can add a tag for a organization’s owned chat:

POST /api/v5/orgs/<organization_id>/owned_chats/<chat_id>/tags

This endpoint returns:

And for the organization’s involved chat:

POST /api/v5/orgs/<organization_id>/involved_chats/<chat_id>/tags

This endpoint returns:

Also, you need to define the name attribute as a payload.

Remove a tag from a chat

DELETE https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/3c43e25a-54d4-46de-9b1d-13ff39df30b7/tags/Premium%20customer

You can remove a tag from one of the user’s chats:

DELETE /api/v5/users/<user_id>/chats/<chat_id>/tags/<tag_name>

This endpoint returns:

Alternatively you may want to remove tags by using the organization:

You can remove a tag for a organization’s owned chat:

DELETE /api/v5/orgs/<organization_id>/owned_chats/<chat_id>/tags/<tag_name>

This endpoint returns:

And for the organization’s involved chat:

DELETE /api/v5/orgs/<organization_id>/involved_chats/<chat_id>/tags/<tag_name>

This endpoint returns:

Also, the <tag_name> must be a URL-encoded name of the tag to be removed.

Chat conversation starters

User may have none or multiple chat conversation starters with limitation of one per language.

A chat conversation starter has the following attributes:

Attribute Type Editable Description
language_code string required Language of this message as a RFC 3066 code. It must be one of the supported languages.
message string required The conversation starter message.
created_at date/time read-only When the chat conversation starter was created.
updated_at date/time read-only When the chat conversation starter was last time updated.

List chat conversation starters for user

GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chat_conversation_starters
{
  "next": "https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chat_conversation_starters",
  "previous": null,
  "results": [
    {
      "language_code": "en",
      "message": "How can I help you?",
      "created_at": "2016-09-01T11:31:36.042Z",
      "updated_at": "2016-09-01T15:31:36.042Z"
    },
    {
      "language_code": "fi",
      "message": "Kuinka voin auttaa?",
      "created_at": "2016-09-01T12:20:12.206Z",
      "updated_at": "2016-09-01T16:31:36.042Z"
    },
    {
      "language_code": "sv",
      "message": "Hur kan jag hjälpa dig?",
      "created_at": "2016-09-01T13:14:01.030Z",
      "updated_at": "2016-09-01T17:31:36.042Z"
    }
  ]
}

You can get a paginated collection of all the chat conversation starters for the user. They are sorted by the creation time of the conversation starters, in ascending order.

GET /api/v5/users/<user_id>/chat_conversation_starters

This endpoint returns:

Add a chat conversation starter for user

Example request that adds a chat conversation starter for the user

POST https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chat_conversation_starters
{
  "message": "Can I help you?",
  "language_code": "en"
}

Example response

{
  "language_code": "en",
  "message": "Can I help you?",
  "created_at": "2016-09-01T11:31:36.042Z",
  "updated_at": "2016-09-01T11:31:36.042Z"
}

You can add a chat conversation starter for the user:

POST /api/v5/users/<user_id>/chat_conversation_starters

You need to define the message and language_code attributes as a payload.

This endpoint returns:

Update a chat conversation starter

Example request that updates the chat conversation starter for user

PATCH https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chat_conversation_starters/fi
{
  "message": "Kuinka voin auttaa sinua?"
}

You may update the editable attributes of your user’s chat conversation starters.

PUT /api/v5/users/<user_id>/chat_conversation_starters/<language_code>

PATCH /api/v5/users/<user_id>/chat_conversation_starters/<language_code>

This endpoint returns:

Remove a chat conversation starter from user

DELETE https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chat_conversation_starters/en

You can remove a chat conversation starter from user:

DELETE /api/v5/users/<user_id>/chat_conversation_starters/<language_code>

This endpoint returns:

Chat reply suggestions

Chat messages may have reply suggestions tied to them. These are handy e.g. when creating a Bot user which only suggests replies for user by analyzing the corresponding message. Chat reply suggestions are shown to chat agents in real time in the giosg Console user interface. A chat reply suggestion object consists:

Attribute Format Editable Description
id ID/string read-only ID of the reply suggestion
suggestion string required The message of this suggestion.
relevancy_score float optional How “good” reply suggestion is this for the message. The value should be a float between 0 and 1 or null.
created_by_user_id ID/string read-only ID of the user which added this reply suggestion.
created_by_user object read-only User which added this reply suggestion.
updated_by_user_id ID/string read-only ID of the user which updated this reply suggestion.
updated_by_user object read-only Last user which updated this reply suggestion.
room_id ID read-only ID of the room where the chat takes place.
chat_id ID read-only ID of the chat.
message_id ID read-only ID of the chat message which this suggestion is tied to.
organization_id ID read-only ID of the user’s organization.
created_at date/time read-only When the reply suggestion was created.
updated_at date/time read-only When the this reply suggestion was updated.

List reply suggestions of a chat

You can get a paginated collection of all the reply suggestions for the chat:

GET /api/v5/users/<user_id>/chats/<chat_id>/reply_suggestions

This endpoint returns:

Or alternatively you may list user’s chat reply suggestions for a routed chat, to which the use may not have joined yet:

GET /api/v5/users/<user_id>/routed_chats/<chat_id>/reply_suggestions

This endpoint returns:

These endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

List reply suggestions of a message

GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/3c43e25a-54d4-46de-9b1d-13ff39df30b7/messages/cb2f4b33-cc1c-11e6-97e1-f45c89c72de3/reply_suggestions
{
  "next": "https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/chats/3c43e25a-54d4-46de-9b1d-13ff39df30b7/messages/cb2f4b33-cc1c-11e6-97e1-f45c89c72de3/reply_suggestions?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "11d9bd6b-cc1d-11e6-8000-f45c89c72de3",
      "suggestion": "Yes we do have those products.",
      "relevancy_score": 0.6,
      "created_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "created_by_user": {
        "id":  "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "is_bot": false
      },
      "updated_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "updated_by_user": {
        "id":  "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "is_bot": false
      },
      "room_id": "babff2ca-cc1d-11e6-962b-f45c89c72de3",
      "chat_id": "3c43e25a-54d4-46de-9b1d-13ff39df30b7",
      "message_id": "cb2f4b33-cc1c-11e6-97e1-f45c89c72de3",
      "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
      "created_at": "2016-09-01T11:31:36.042Z",
      "updated_at": "2016-09-01T11:31:36.042Z"
    },
  ]
}

You can get a paginated collection of all the reply suggestions for the corresponding message:

GET /api/v5/users/<user_id>/chats/<chat_id>/messages/<message_id>/reply_suggestions

This endpoint returns:

Or alternatively you may list user’s chat reply suggestions for a routed chat, to which the use may not have joined yet:

GET /api/v5/users/<user_id>/routed_chats/<chat_id>/messages/<message_id>/reply_suggestions

This endpoint returns:

These endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

Update a chat reply suggestion

You may update the editable attributes of your reply suggestions:

PUT/PATCH /api/v5/users/<user_id>/chats/<chat_id>/messages/<message_id>/reply_suggestions/<reply_suggestion_id>

This endpoint returns:

Or alternatively you may list user’s chat reply suggestions for a routed chat, to which the use may not have joined yet:

PUT/PATCH /api/v5/users/<user_id>/routed_chats/<chat_id>/messages/<message_id>/reply_suggestions/<reply_suggestion_id>

This endpoint returns:

Add a chat reply suggestion for a message

You can add a chat reply suggestion for the message:

POST /api/v5/users/<user_id>/chats/<chat_id>/messages/<message_id>/reply_suggestions

This endpoint returns:

Or alternatively you may list user’s chat reply suggestions for a routed chat, to which the use may not have joined yet:

POST /api/v5/users/<user_id>/routed_chats/<chat_id>/messages/<message_id>/reply_suggestions

This endpoint returns:

You need to define the suggestion attribute as a payload. If you pass relevancy_score with float value, then it will be shown in console.

Router API

Routers are used to assign traffic from websites to chat agents. Routers are used to define where chat agents can be online, and where they are allowed to get pending chat tasks.

For example, let’s say your organization has two websites and a team of chat agent users. You would like to have the team to chat in the websites. You can define a router including this particular team, and then link the router to be used on your domain rooms.

If the organization has purchased the “Overflow” feature, then routers can also include simple rules that allows routing the pending chats further to additional chat agents, when given conditions match. For example, new pending chats should first be assigned to a primary chat agent team. However, if all of those chat agents are offline, then the chat should be assigned to a secondary chat agent team.

Routing system consists of the following core concepts:

Routers

“Routers” are the core of the chat routing system. A router defines a set of users or teams. The router can then be set up to be used with any number of rooms.

In order to use a router for an organization in some specific room, you need to update the router_id attribute of the related room settings. This can be done by updating the organization’s room settings resource.

A router always contains at least one “routing step” that defines a set of users and teams. The first step in the router is always required and it describes to whom new pending tasks are immediately assigned when this router is used.

Only if the organization has purchased the “Overflow” feature, a router may contain more than one router steps and steps may have “routing preconditions”. These additional steps can be used to define additional users to whom a pending chat will be assigned incrementally when certain conditions match.

For example: there could be a router whose first step defines the primary chat team. The second step defines that if all of those chat agents are offline, then the pending chat will be assigned to some other, secondary chat team.

Take a look at the “Routing steps” section for more information about incremental pending chat assignments. Also, see the “Routing preconditions” for a list of all supported condition types.

A router object contains the following attributes:

Attribute Type Editable Description
id ID read-only The unique identifier of this router.
name string required Name of the router. Must be a non-empty string.
steps array of objects required Array of routing step objects for this router. NOTE: Your organization must have the “Overflow” feature enabled to define more than one step. The API will return 400 otherwise.
organization_id string read-only ID of the organization that owns the router.
created_at date/time read-only When the router resource was created.
created_by_user_id ID read-only ID of the user who created this router.
created_by_user object read-only The user resource created this router.
updated_at date/time read-only When the router resource was updated last time.
updated_by_user_id ID read-only ID of the user who last updated this router.
updated_by_user object read-only The user resource who last updated this router.

Get a collection of organization’s routers

Return a paginated collection of all the router resources of an organization (<organization_id>).

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

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

Retrieve router details

Example request and payload: Retrieve organization’s router details

GET https://service.giosg.com/api/v5/orgs/64c8fb1c-8673-11e7-a7c7-00163e8edbc5/routers/0b77ca4a-6308-11e7-9d23-00163e07eae6
{
    "id": "0b77ca4a-6308-11e7-9d23-00163e07eae6",
    "name": "My Router",
    "organization_id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
    "created_at": "2017-07-07T11:33:06.137Z",
    "created_by_user": {
        "id": "97abf1ee-6308-11e7-9d09-00163ec04961",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "organization_id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
        "is_bot": false
    },
    "created_by_user_id": "97abf1ee-6308-11e7-9d09-00163ec04961",
    "updated_at": "2017-07-07T11:33:06.137Z",
    "updated_by_user": {
        "id": "97abf1ee-6308-11e7-9d09-00163ec04961",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "organization_id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
        "is_bot": false
    },
    "updated_by_user_id": "97abf1ee-6308-11e7-9d09-00163ec04961",
    "steps": [
        {
            "id": "12cbb144-6308-11e7-92a0-00163e16030c",
            "index": 0,
            "user_ids": [],
            "team_ids": [
                "153be836-630d-11e7-bef1-00163e250c85",
                "a56d5476-630d-11e7-8fa2-00163ec04961"
            ],
            "organization_ids": [],
            "preconditions": []
        },
        {
            "id": "12cbb144-6308-11e7-92a0-00163e16030c",
            "index": 1,
            "user_ids": [],
            "team_ids": [],
            "organization_ids": [
                "9635070c-6311-11e7-9c20-00163edd2ecc"
            ],
            "preconditions": [
                {
                    "type": "task_waited_in_previous_step",
                    "value": 10
                }
            ]
        }
    ]
}

Get a single router object (<router_id>) of an organization (<organization_id>).

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

This endpoint returns:

Update a router

Example request and payload: Update router’s steps with PATCH

PATCH https://service.giosg.com/api/v5/orgs/64c8fb1c-8673-11e7-a7c7-00163e8edbc5/routers/0b77ca4a-6308-11e7-9d23-00163e07eae6
{
    "steps": [
        {
            "user_ids": [],
            "team_ids": [
                "153be836-630d-11e7-bef1-00163e250c85"
            ],
            "organization_ids": [],
            "preconditions": []
        },
        {
            "user_ids": [],
            "team_ids": [
                "a56d5476-630d-11e7-8fa2-00163ec04961"
            ],
            "organization_ids": [],
            "preconditions": [
                {
                    "type": "users_offline",
                    "value": 100
                }
            ]
        }
    ]
}

Update a single router object (<router_id>) of an organization (<organization_id>).

Update specific fields with PATCH:

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

Update the whole router with PUT:

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

This endpoint returns:

Create a new router

Example request and payload: Create a new router with POST

POST https://service.giosg.com/api/v5/orgs/64c8fb1c-8673-11e7-a7c7-00163e8edbc5/routers
{
    "name": "My new router",
    "steps": [
        {
            "user_ids": [],
            "team_ids": [
                "153be836-630d-11e7-bef1-00163e250c85",
                "026e1b80-f7b1-11e4-8e23-00163e0c01f2"
            ],
            "organization_ids": [],
            "preconditions": []
        },
        {
            "user_ids": [],
            "team_ids": [],
            "organization_ids": ["a56d5476-630d-11e7-8fa2-00163ec04961"],
            "preconditions": [
                {
                    "type": "users_absent",
                    "value": 100
                },
                {
                    "type": "user_capacity_load",
                    "value": 80
                }
            ]
        }
    ]
}

Create a new router object (<router_id>) for an organization (<organization_id>).

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

This endpoint returns:

Delete a router

Example request and payload: Delete a router with DELETE

DELETE https://service.giosg.com/api/v5/orgs/64c8fb1c-8673-11e7-a7c7-00163e8edbc5/routers/0b77ca4a-6308-11e7-9d23-00163e07eae6

Delete a router object (<router_id>) of an organization (<organization_id>).

DELETE https://service.giosg.com/api/v5/orgs/<organization_id>/routers/<router_id>

This endpoint returns:

List rooms where a router is in use

Example request and payload: Retrieve rooms which use current router

GET https://service.giosg.com/api/v5/orgs/64c8fb1c-8673-11e7-a7c7-00163e8edbc5/routers/0b77ca4a-6308-11e7-9d23-00163e07eae6/rooms
{
    "id": "0b77ca4a-6308-11e7-9d23-00163e07eae6",
    "organization_id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
    "organization": {
        "id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
        "name": "Giosg.com"
    },
    "domain": "giosg.com",
    "name": "My room",
    "display_name": "Customer service",
    "is_shared": false,
    "language_code": "en",
    "created_at": "2017-07-07T11:33:06.137Z",
    "updated_at": "2017-07-07T11:33:06.137Z",
    "updated_by_user_id": "97abf1ee-6308-11e7-9d09-00163ec04961",
    "updated_by_user": {
        "id": "97abf1ee-6308-11e7-9d09-00163ec04961",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "organization_id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
        "is_bot": false
    },
    "is_online": true,
    "is_deleted": false,
    "is_service_hours_enabled": true,
    "is_open": true
}

Return a paginated collection of all the room resources in which the given router is in use for the given organization.

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

This endpoint returns:

Routing steps

A routing step defines a set of users and teams to whom new pending tasks will be assigned whenever the step becomes in effect.

Routing steps have a meaningful order within the router. The first step will take effect immediately for the pending tasks. Any latter steps will take effect whenever any of their routing preconditions match. In addition, the step can only become in effect if each of their preceding step have become in effect.

Note that task assignments done by routers are always incremental. This means that once a user has been assigned with a pending chat, then that pending chat is being assigned to them even if the pre-conditions are no more in effect, or if the router is modified. However, only one assigned user can actually take and join to the pending chat.

A routing step object contains the following attributes:

Attribute Type Editable Description
id ID read-only The unique identifier of this routing step.
index integer read-only Index of the routing step relative to other routing steps in a router. Index is set automatically when router is created or updated. The first item in the router’s steps array will get index of 0.
preconditions array of objects required Array of routing precondition objects for this step. This should be an empty array for the first step. Otherwise it should contain at least one routing precondition object!
organization_ids array of strings required Array of organization IDs that tasks will be routed to. Can be an empty array.
team_ids array of strings required Array of team IDs that tasks will be routed to. Can be an empty array.
users_ids array of strings required Array of user IDs that tasks will be routed to. Can be an empty array.
created_at date/time read-only When the routing step resource was created.
created_by_user_id ID read-only ID of the user who created this routing step resource.
created_by_user object read-only The user resource that created this routing step resource.
updated_at date/time read-only When the routing step resource was updated last time.
updated_by_user_id ID read-only ID of the user who last updated this routing step resource.
updated_by_user object read-only The user resource that created this routing step resource.

Routing preconditions

A routing precondition describes a possible situation in which the related routing step may become in effect. If a step has multiple preconditions, the step becomes in effect when any of its preconditions match.

Currently, you can choose from the following 4 condition types:

“Are all (or part of) the users, defined in previous steps, offline?”

For example, if no user is logged in to the Giosg Console, or no logged user has become online by pressing the “Start” button, then this condition would match. The type of this condition is users_offline.

“Are all (or part of) the users, defined in previous steps, not present?”

For example, if no user is logged in to the Giosg Console, then this condition would match. The type of this condition is users_absent.

“Is all (or part of) the total user chat capacity in use?”

For example, if there are users online but every one of them has more chats than they are capable to handle, then this condition would match. The type of this condition is user_capacity_load.

“Has the chat task waited too long?”

For example, when the chat is assigned to a step of users, and no one of these users take the chat in more than, let’s say 10 seconds, then this condition would match. The type of this condition is task_waited_in_previous_step.

A routing precondition object contains the following attributes:

Attribute Type Editable Description
type string required Type of precondition. Can be one of the following: users_offline, users_absent, user_capacity_load, task_waited
value integer required Value of precondition. See the table below for explanation.

Routing precondition value

Routing precondition value can have a different meaning depending on the chosen type. See the table below:

Type Value
users_offline Percentage (%) of users that are offline in all previous steps. Value of 100 means that 100% of users are offline in all previous steps. Value of 0 means that all users are online in all previous steps.
users_absent Percentage (%) of users that are absent in all previous steps. Value of 100 means that 100% of users are absent in all previous steps. Value of 0 means that all users are present in all previous steps.
user_capacity_load Percentage (%) of used capacity of all users in all previous steps. Value of 100 means that all users have 100% of their capacity used in all previous steps. Value of 0 means that all users have none of their capacity used in all previous steps.
task_waited How many seconds the task has waited all in all. Value of 100 means that the task has waited for 100 seconds all in all.

Brand API

Brands

Brands represents the UI of chat windows, lead forms, chat buttons, etc. which are shown to visitor (both mobile and desktop). There are some restricted customization options for them. In order to use some specific brand in a room, it can be set by changing the brand attribute in organization room settings API.

A brand has the following attributes:

Attribute Type Editable Description
id ID read-only Unique identifier for the brand.
organization_id ID read-only ID of the organization which owns the brand.
organization object read-only Organization which owns the brand.
created_at date/time read-only When the brand was created.
updated_at date/time read-only When was the last time the brand was updated.
created_by_user_id ID read-only ID of the user which created this brand.
created_by_user object read-only User which created this brand.
updated_by_user_id ID read-only ID of the last user which updated this brand.
updated_by_user object read-only Last user which updated this brand.
name string required Name of this brand.
primary_color_code string required Primary color code in hexadecimal format. If null then the default color is used.
secondary_color_code string required Secondary color code in hexadecimal format. If null then the default color is used.
logo_asset_id ID optional ID of the logo used in this brand. The asset’s kind must be a image.
logo_asset object read-only Logo used in this brand. Supported formats are PNG, JPEG, and GIF. Logo will resized to fit the position.

List organization’s brands

GET https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/brands
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/brands?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
      "organization": {
        "id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "name": "Company X"
      },
      "created_at": "2015-02-13T11:31:36.042",
      "updated_at": "2015-02-13T12:38:36.431",
      "created_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "created_by_user": {
        "id":  "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "updated_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "updated_by_user": {
        "id":  "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "name": "Giosg core brand",
      "primary_color_code": "#549cd9",
      "secondary_color_code": "#f9d656",
      "logo_asset_id": "90967a1e-3cc4-11e8-a67f-8c8590c2eeca",
      "logo_asset": {
        "id": "90967a1e-3cc4-11e8-a67f-8c8590c2eeca",
        "url": "https://giosg.com/logo.png",
        "name": "Company logo",
        "description": null,
        "kind": "image",
        "content_type": "image/jpeg",
        "size": 10000,
        "charset": null,
        "width": 25,
        "height": 25
      }
    }
  ]
}

You can list brands for an organization:

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

This API endpoint returns a paginated collection. They are sorted by the creation time of the brands, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

Creating a new brand

Example request for creating a new brand

POST https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/brands

Example request payload

{
  "name": "Spring sales brand",
  "primary_color_code": "#549cd9",
  "secondary_color_code": "#f9d656",
  "logo_asset_id": "974a6078-3731-11e8-96e9-00143d180066"
}

You can create a new brand for an organization by:

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

This endpoint returns:

Retrieve details of organization’s brand

You can retrieve details of organization’s brand:

GET /api/v5/orgs/<organization_id>/brands/<brand_id>

This endpoint returns:

Update existing brand

Example request for updating primary color of existing brand

PUT https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/brands/58f5055c-56e0-11e5-9354-6c4008c08dfe

Example request payload

{
  "name": "Campaign brand",
  "primary_color_code": "#1c1c1c",
  "secondary_color_code": "#ffffff"
}

You can change the brand’s attributes by:

PUT /api/v5/orgs/<organization_id>/brands/<brand_id>

or

PATCH /api/v5/orgs/<organization_id>/brands/<brand_id>

This endpoint returns:

Delete a brand

Example request for removing a brand

DELETE https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/brands/58f5055c-56e0-11e5-9354-6c4008c08dfe

You can remove a brand by:

DELETE /api/v5/orgs/<organization_id>/brands/<brand_id>

This endpoint returns:

List rooms where a brand is in use

Example request and payload: Retrieve rooms which use current brand

GET https://service.giosg.com/api/v5/orgs/64c8fb1c-8673-11e7-a7c7-00163e8edbc5/brands/0b77ca4a-6308-11e7-9d23-00163e07eae6/rooms
{
    "id": "0b77ca4a-6308-11e7-9d23-00163e07eae6",
    "organization_id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
    "organization": {
        "id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
        "name": "Giosg.com"
    },
    "domain": "giosg.com",
    "name": "My room",
    "display_name": "Customer service",
    "is_shared": false,
    "language_code": "en",
    "created_at": "2017-07-07T11:33:06.137Z",
    "updated_at": "2017-07-07T11:33:06.137Z",
    "updated_by_user_id": "97abf1ee-6308-11e7-9d09-00163ec04961",
    "updated_by_user": {
        "id": "97abf1ee-6308-11e7-9d09-00163ec04961",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "organization_id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
        "is_bot": false
    },
    "is_online": true,
    "is_deleted": false,
    "is_service_hours_enabled": true,
    "is_open": true
}

Return a paginated collection of all the room resources in which the given brand is in use for the given organization.

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

This endpoint returns:

Basket API

Visitors may add products to their baskets (“shopping carts”) and then purchase (“lock”) them.

Shopping carts

A shopping cart resource has the following attributes.

Attribute Type Description
id ID Unique identifier for the shopping cart
visitor_id string The identifier for the visitor to whom the shopping cart belongs
session_id string The ID of the session on which the visitor created this shopping cart.
created_at date/time When this shopping cart was created. In practice, this is just before the very first product is added to the shopping cart.
updated_at date/time When this shopping chart was last time altered.
total_value string Decimal string (e.g. "145.50") of the total value of the products in the shopping cart. This will contain any discounts and delivery costs, and may therefore differ from the sum value of the products in the cart. This does not contain any monthly subscriptions. This value is represented in the currency described by currency attribute.
total_subscription_value string Decimal string (e.g. "19.90") of the total monthly subscription value of any “subscription” products in the cart. For example, if the visitor is about to subscribe the product A with monthly fee 15.50 and the product B with monthly fee 3.00, then the total value would be 18.50. This value is represented in the currency described by currency attribute per month.
currency string The currency of the shopping cart, in which all the values (including values of the products) are represented. Currency is a upper-case ISO 4217 currency code, e.g. EUR.
is_locked boolean Whether or not the cart has been “locked”, meaning that the visitor has actually purchased its contents. If true then the visitor has purchased the contents of the cart. If false, the visitor is still shopping or has abandonded the cart.
locked_at date/time When the cart was locked, or null if the cart is not yet locked.

List shopping carts of a visitor

To list all the shopping carts of a visitor that is a member of a chat, use the following endpoint:

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

This endpoint returns:

List shopping carts of a room visitor

To list all the shopping carts of a visitor in a room, use the following endpoint:

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

This endpoint returns:

Shopping cart products

A shopping cart product resource describes one product that the visitor has added to the basket. A product may have a quantity, so it may represent more than one item. It has the following attributes:

Attribute Type Description
id ID Unique identifier for this product record within the shopping cart. Note that it does not identify the product in the shop.
shopping_cart_id ID ID of the shopping cart to which this product record belongs
created_at date/time When this product was added to the shopping cart
updated_at date/time When this product record was last time modified
is_deleted boolean Whether or not the product was in the cart at some point but was then removed from it. If this is true, you should ignore this record from the value of the cart.
deleted_at date/time When this product record deleted from the shopping cart, or null if it currently exists in the cart.
name string The name of the product
description string The description of the product
category_name string The name of the category to which the product belongs
value string The value of a single piece of this product, as decimal string (e.g. "199.90"). This is represented in the currency of the shopping cart.
subscription_value string The value of a single subscription of this product per month, as a decimal string (e.g. "9.90"). This is represented in the currency of the shopping cart.
product_number string The product number, code or other identifier for this product in the shop.
quantity number How many pieces of this product this record represents. The total value of this record is the value multiplied with the quantity.
monthly_quantity number How many subscriptions of this product this record represents. The total subscription value of this record is the subscription_value multiplied with monthly quantity.
stock_balance number How many items of this product there were in the stock at the time.

List shopping cart products of a visitor

To list all the shopping carts of a visitor that is a member of a chat, use the following endpoint:

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

This endpoint returns:

Partnership API

Partnerships

A partnership object describes a connection between your organization and one of your partner organizations. Partnerships can only be created with partnership invitation resources.

Attribute Type Editable Description
partner_organization_id ID read-only ID of the partner organization
partner_organization object read-only The partner organization resource, with all of its available attributes
organization_id ID read-only ID of your organization, for convenience (matching the <organization_id> in the URL)
organization object read-only Your organization resource, with all of its available attributes
display_name string optional Name that is shown to your organization members for this partner. May be null, in which case the original name is shown
created_at date/time read-only When you became partners

Get a collection of partnerships

Get a paginated collection of all the known partnerships.

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

This end-point accepts the following GET parameters.

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at and -created_at

This endpoint returns:

Retrieve partnership details

Retrieve a single partnership resource for your organization (<organization_id>) by the partner organization’s ID (<partner_organization_id>).

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

This endpoint returns:

Remove a partnership

Being aware of this, you may remove another organization (<partner_organization_id>) from your organization’s (<organization_id>) partners.

DELETE https://service.giosg.com/api/v5/orgs/<organization_id>/partnerships/<partner_organization_id>

This endpoint returns:

Update a partnership

You may update the editable attributes of a partnership for your organization (<organization_id>) by the given partner organization’s ID (<partner_organization_id>).

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

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

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

This endpoint returns:

Partners

A partner object describes a organization resource of your partner organizations. Partners can only be created with partnership invitation resources.

Attribute Type Editable Description
id ID read-only ID of the partner organization
name string read-only The name of the partner organization
created_at date/time read-only When the partner organization was created
is_present boolean read-only Whether or not the partner organization is currently present
is_online boolean read-only Whether or not the partner organization is currently online

Get a collection of partners

Get a paginated collection of all the known partners.

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

This end-point accepts the following GET parameters.

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at and -created_at

This endpoint returns:

Retrieve partner details

Retrieve a single partner resource for your organization (<organization_id>) by the partner organization’s ID (<partner_organization_id>).

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

This endpoint returns:

Partner’s users

A partner user object describes a user resource of your partner organizations.

Attribute Type Editable Description
id ID read-only ID of the user
full_name string read-only Full name of the user
email string read-only The email of the user
current_chat_count integer read-only The number of chats the user has currently, based on the most recent information about the user
avatar_id ID read-only ID of the user’s avatar
avatar object read-only The avatar of the user as an object. It contains attributes idand url. This is null if the user has no avatar
created_at date/time read-only When the user resource was created
is_present boolean read-only Whether or not the user is currently present
is_online boolean read-only Whether or not the user is currently online

Get a collection of partner’s users

Get a paginated collection of all the known users of partner.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/partners/<partner_organization_id>/users

This endpoint takes following GET parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at and -created_at

This endpoint returns:

Retrieve partner details

Retrieve a single partner user resource of your partner organization (<partner_organization_id>) by the your organization’s ID (<organization_id>) and partner organization’s user’s ID (<user_id>).

GET https://service.giosg.com/api/v5/orgs/<organization_id>/partners/<partner_organization_id>/users/<user_id>

This endpoint returns:

Sharing API

Once you have become partners, you may share resources to your partner organization. Resources that are shared by you or are shared to you are represented by shares. Currently there are two types of shares:

Additionally, each type of share are represented as either outgoing or incoming share, depending on whether you are the sharing or the receiving party.

Room shares

A room share represents a room instance share between two organizations. A room share resource has the following attributes:

Attribute Type Editable Description
id ID read-only Unique identifier for the share resource.
organization_id ID required ID of the partner organization to whom the room resource is shared. Must be an existing partner. Cannot be changed after creation.
organization object read-only The organization object to whom the room resource was shared.
room_organization_id ID read-only ID of the organization who shared the room resource.
room_organization object read-only The organization object who shared the room resource.
room_id ID read-only ID of the room resource.
room object read-only The room object.
created_at date/time read-only When the room resource was shared.
updated_at date/time read-only When was the last time the sharing was updated. This cannot change currently after creation.
created_by_user_id ID read-only ID of the user who shared the room resource.
created_by_user object read-only The user room resource who shared the room resource, with all of the available attributes.
updated_by_user_id ID read-only ID of the last user which updated this room resource.
updated_by_user object read-only Last user which updated this room resource. This cannot change currently after creation.

Currently sharing a room between organization can be only done by giosg’s support. If you wish to share a room to your partner, please contact support@giosg.com.

List outgoing room shares of an organization

Example request for listing an organization’s outgoing room shares

GET https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/outgoing_room_shares
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/outgoing_room_shares?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
      "organization": {
        "id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "name": "Company X"
        },
      "room_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "room_organization": {
        "id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "name": "giosg.com"
      },
      "created_at": "2015-02-13T11:31:36.042",
      "updated_at": "2015-02-13T12:38:36.431",
      "created_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "created_by_user": {
        "id":  "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "updated_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "updated_by_user": {
        "id":  "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "room_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "room": {
        "id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "display_name": "Shared room",
        "domain": "giosg.com",
        "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "organization": {
          "id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
          "name": "giosg.com"
        }
      }
    }
  ]
}

You can list outgoing room shares for an organization:

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

This API endpoint returns a paginated collection. They are sorted by the creation time of the room share, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

Retrieve details of room share

You can retrieve details of organization’s room share:

GET /api/v5/orgs/<organization_id>/outgoing_room_shares/<room_share_id>

This endpoint returns:

List incoming room shares

You can list incoming room shares for an organization:

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

This API endpoint returns a paginated collection. They are sorted by the creation time of the room share, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

Retrieve details of incoming room share

You can retrieve details of organization incoming room share:

GET /api/v5/orgs/<organization_id>/incoming_room_shares/<room_share_id>

This endpoint returns:

App shares

A app share represents a giosg app instance share between two organizations. A app share resource has the following attributes:

Attribute Type Editable Description
id ID read-only Unique identifier for the share resource.
organization_id ID required ID of the partner organization to whom the app resource is shared. Must be an existing partner. Cannot be changed after creation.
organization object read-only The organization object to whom the app resource was shared.
app_organization_id ID read-only ID of the organization who shared the app resource.
app_organization object read-only The organization object who shared the app resource.
app_id ID read-only ID of the app resource.
app object read-only The app object.
created_at date/time read-only When the app resource was shared.
updated_at date/time read-only When was the last time the sharing was updated. This cannot change currently after creation.
created_by_user_id ID read-only ID of the user who shared the app resource.
created_by_user object read-only The user app resource who shared the app resource, with all of the available attributes.
updated_by_user_id ID read-only ID of the last user which updated this app resource.
updated_by_user object read-only Last user which updated this app resource. This cannot change currently after creation.

List outgoing app shares of an owned app

Example request for listing an owned app’s shares

GET https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/owned_apps/7f9e9580-095b-42c7-838c-c04e667b26f7/outgoing_app_shares
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/owned_apps/7f9e9580-095b-42c7-838c-c04e667b26f7/outgoing_app_shares?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
      "organization": {
        "id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "name": "Company X"
      },
      "app_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "app_organization": {
        "id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "name": "giosg.com"
      },
      "created_at": "2015-02-13T11:31:36.042",
      "updated_at": "2015-02-13T12:38:36.431",
      "created_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "created_by_user": {
        "id":  "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "updated_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "updated_by_user": {
        "id":  "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "app_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
      "app": {
        "name": "Flappy giosg Balls",
        "description": "My cool application",
        "owned_by_organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
        "owned_by_organization": {
          "id": "7f9e9580-095b-42c7-838c-c04e667b26f7",
          "name": "giosg.com"
        },
        "created_at": "2017-01-01T12:00:00.123Z",
        "updated_at": "2017-01-02T15:00:00.123Z"
      },
    }
  ]
}

You can list outgoing app shares for an organization’s owned app:

GET /api/v5/orgs/<organization_id>/owned_apps/<app_id>/outgoing_app_shares

This API endpoint returns a paginated collection. They are sorted by the creation time of the app share, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

Sharing an owned app to partner organization

Example request for sharing an owned app to partner organization

POST https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/owned_apps/7f9e9580-095b-42c7-838c-c04e667b26f7/outgoing_app_shares

Example request payload

{
  "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
}

You can share an owned app to a partner organization by:

POST /api/v5/orgs/<organization_id>/owned_apps/<app_id>/outgoing_app_shares

This endpoint returns:

Retrieve details of owned app’s share

You can retrieve details of organization’s owned app’s share:

GET /api/v5/orgs/<organization_id>/owned_apps/<app_id>/outgoing_app_shares/<target_organization_id>

This endpoint returns:

Unshare owned app’s share from partner organization

Example request for unsharing an owned app

DELETE https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/owned_apps/7f9e9580-095b-42c7-838c-c04e667b26f7/outgoing_app_shares/e68220e1-9072-11e6-bf95-f45c89c72de3

You can unshare a brand by:

DELETE /api/v5/orgs/<organization_id>/owned_apps/<app_id>/outgoing_app_shares/<app_id>

Note that this will [uninstall][] the app from the partner organization!

This endpoint returns:

List incoming app shares

You can list incoming app shares for an organization:

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

This API endpoint returns a paginated collection. They are sorted by the creation time of the app share, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at.

This endpoint returns:

Retrieve details of incoming app share

You can retrieve details of organization incoming app share:

GET /api/v5/orgs/<organization_id>/incoming_app_shares/<app_id>

This endpoint returns:

Assets API

Assets

Assets are files that you can upload to giosg system and that are publicly available. They are useful to hosts resources for you custom customized giosg products or your website components!

Even though asset contents are publicly available, they can only be accessed with an URL. In other words, only your organization members are able to see the list of your organization assets. When the asset is used somewhere, e.g. on your custom chat dialog or your website, anyone is (and need to be) able to download its contents and see its public attributes.

An asset resource has the following attributes.

Attribute Type Editable Description
id ID read-only UUID string identifier
name string required Short, human-readable name.
description string optional Human-readable description
organization_id ID read-only The ID of the owner organization
file_name string read-only The original file name of the uploaded file
url string read-only The full URL for original, uploaded file. Use this URL to link to your asset!
size integer read-only Size of the uploaded file in bytes
content_type string read-only Content type of the uploaded file, e.g. image/jpeg (or null if unknown)
kind string read-only What kind of file the asset is: "image", "css", "javascript", "font" or null (unknown)
charset string optional Character encoding for a text file, e.g. utf-8 (or null if binary or unknown). Must be a valid encoding name.
created_at date/time read-only When the asset was created
created_by_user_id ID read-only The ID of the person who created this asset
created_by_user object read-only The person resource who created this asset
updated_at date/time read-only When the asset name or description was last time updated
updated_by_user_id ID read-only The ID of the person who last time updated this asset
updated_by_user object read-only The person resource who last time updated this asset
width integer read-only The width of an image in pixels. Available for images only. It is null for other assets.
height integer read-only The height of an image in pixels. Available for images only. It is null for other assets.

Upload a new asset

Upload a file creating a new asset for a organization.

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

Attribute Type Editable Description
upload file required The asset file to be uploaded. File name is required. This field is optional when updating existing asset.
name string optional Name for the newly created asset. If omitted, defaults to the file name. Otherwise, it must be a non-empty string value.
charset string optional Character encoding for a text file, e.g. utf-8. Must be a valid encoding name. Defaults to null, meaning that the encoding is undefined. It is highly recommended to define a correct encoding for the uploaded text files if they are containing special characters, otherwise browsers might not read them correctly.
description string optional Description for this asset.

This endpoint returns:

List assets

Get a paginated collection of all the assets of your organization:

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

The endpoint accepts the following GET parameters.

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at, updated_at, name, kind or content_type in ascending order (- for descending).
kind string (none) If given, returns Assets with the given kind.
content_type string (none) If given, returns Assets with the given content_type.
description string (none) If given, returns Assets with the given description. Note: this is case sensitive.

This endpoint returns:

Retrieve a single asset

GET /api/v5/orgs/<organization_id>/assets/<asset_id>

This endpoint returns:

Update an asset

You may update the name and/or description attributes of an asset. Alternatively you may also upload new file by providing upload in payload. In this case you may also change the charset attribute. Note that charset can only be changed when uploading content for the asset.

PUT /api/v5/orgs/<organization_id>/assets/<asset_id>

PATCH /api/v5/orgs/<organization_id>/assets/<asset_id>

This endpoint returns:

Delete an asset

You may delete your assets. Their size is freed for new asset uploads.

DELETE /api/v5/orgs/<organization_id>/assets/<asset_id>

NOTE: Any previous URL (the url attribute) for the asset will stop working and the files won’t be available for download any more. However, this might take a while to take effect.

This endpoint returns:

Retrieve organization’s storage information

You may check your organization’s current asset storage space usage:

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

This returns an object with the following attributes:

Attribute Type Description
free_space integer Total free space for new assets, in bytes
usage integer Sum of all your organization asset sizes, in bytes
limit integer The maximun allowed sum of your organization asset sizes, in bytes

This endpoint returns:

Lead API

Leads

Lead forms can be used to gather information about the potential lead. Leads can be processed by using Lead API.

A lead object has the following attributes::

Attribute Type Editable Description
id ID read-only Unique identifier of this lead.
lead_form_id ID read-only ID of the lead form.
organization_id ID read-only ID of the organization which owns the lead.
room_id ID read-only ID of the room in which the lead was gathered.
assigned_user_id ID optional ID of the user who is responsible to handle this lead. null if no user is assigned to handle this lead. This field normally changed as the user’s id who picked lead in swimlane.
assigned_user object read-only The user object.
visitor_id string read-only ID of the visitor.
is_closed boolean optional Whether the lead has been closed or not.
is_processable boolean read-only true if lead is meant to be processed by third party application, false if it’s shown in the Console.
page_url string read-only The url of the page where the lead was collected.
page_title string read-only The title of the page where the lead was collected.
data object read-only The data which was collected in lead form. Data object’s keys are names of the collected fields and values are from corresponding field. The object only consists of fields which visitor has filled, this might cause some keys to be missing if the visitor did not provide anything to these fields.
created_at date/time read-only When the lead was created.
updated_at date/time read-only When the lead was last time updated.
closed_at date/time read-only When the lead was closed.
sensitive_data_purged_at date/time read-only When the lead’s sensitive data was purged. This means that the data is set to as an empty object. This is null if the data was not purged.

List organization’s leads

You can get a paginated collection of all leads for the organization. They are sorted by the creation time of the lead, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at
is_processable boolean (none) If true, then return only leads which are processed by third party. If false, return only leads which are shown in the Console.

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

This endpoint returns:

Retrieve organization’s lead’s details

You may retrieve a single lead object by its ID (<lead_id>) that organization (<organization_id>) is eligible for:

GET /api/v5/orgs/<organization_id>/leads/<lead_id>

This endpoint returns:

Update organization’s lead’s details

You may update your organization’s leads by:

PUT /api/v5/orgs/<organization_id>/leads/<lead_id>

PATCH /api/v5/orgs/<organization_id>/leads/<lead_id>

This endpoint returns:

List user’s assigned leads

GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/assigned_leads
{
  "next": "https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/leads",
  "previous": null,
  "results": [
    {
      "id": "4d0648b8-9074-11e6-963e-f45c89c72de3",
      "lead_form_id": "700f38ba-9529-11e6-b202-f45c89c72de3",
      "organization_id": "7c99425e-9529-11e6-8107-f45c89c72de3",
      "room_id": "9f3d51a8-9529-11e6-80e7-f45c89c72de3",
      "assigned_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
      "assigned_user": {
        "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
        "full_name": "Bill Giosg",
        "first_name": "Bill",
        "last_name": "Giosg",
        "organization_id": "7c99425e-9529-11e6-8107-f45c89c72de3"
      },
      "visitor_id": "08119566026a4e1194a7a3244c90f925",
      "is_closed": false,
      "is_processable": false,
      "page_url": "https://giosg.com",
      "page_title": "Giosg - intelligent conversion marketing platform",
      "data": {
        "phone": "+123654789",
        "name": "Lead Man",
        "email": "lead.man@superheroes.gov"
      },
      "created_at": "2016-09-01T11:31:36.042Z",
      "updated_at": "2016-09-01T15:31:36.042Z",
      "closed_at": null,
      "sensitive_data_purged_at": null
    },
  ]
}

You can get a paginated collection of all assigned leads for the user. They are sorted by the creation time of the lead, in ascending order.

This endpoint takes the following GET-parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at or -created_at
is_processable boolean (none) If true, then return only leads which are processed by third party. If false, return only leads which are shown in the Console.

GET /api/v5/users/<user_id>/assigned_leads

This endpoint returns:

List user’s pending leads

You can get a paginated collection of all pending leads for the user. They are sorted by the creation time of the lead, in ascending order.

This endpoint takes the same GET-parameters as the other list endpoints.

GET /api/v5/users/<user_id>/pending_leads

This endpoint returns:

Retrieve user’s lead’s details

Example request for retrieving pending lead’s details

GET https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/pending_leads/4d0648b8-9074-11e6-963e-f45c89c72de3

Example response

{
  "id": "4d0648b8-9074-11e6-963e-f45c89c72de3",
  "lead_form_id": "700f38ba-9529-11e6-b202-f45c89c72de3",
  "organization_id": "7c99425e-9529-11e6-8107-f45c89c72de3",
  "room_id": "9f3d51a8-9529-11e6-80e7-f45c89c72de3",
  "assigned_user_id": null,
  "assigned_user": null,
  "visitor_id": "08119566026a4e1194a7a3244c90f925",
  "is_closed": false,
  "is_processable": false,
  "page_url": "https://giosg.com",
  "page_title": "Giosg - intelligent conversion marketing platform",
  "data": {
    "phone": "+123654789",
    "name": "Lead Man",
    "email": "lead.man@superheroes.gov"
  },
  "created_at": "2016-09-01T11:31:36.042Z",
  "updated_at": "2016-09-01T15:31:36.042Z",
  "closed_at": null,
  "sensitive_data_purged_at": null
}

You may retrieve a single lead object by its ID (<lead_id>) that user (<user_id>) is eligible for. Assigned leads by:

GET /api/v5/users/<user_id>/assigned_leads/<lead_id>

And pending leads:

GET /api/v5/users/<user_id>/pending_leads/<lead_id>

This endpoint returns:

Update user’s lead’s details

Example request that updates pending lead to be handled by user.

PATCH https://service.giosg.com/api/v5/users/ac83d426-be80-4d75-8c62-49a77f98468e/pending_leads/f8a3917d-9073-11e6-b96f-f45c89c72de3
{
  "assigned_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e"
}
{
  "id": "4d0648b8-9074-11e6-963e-f45c89c72de3",
  "lead_form_id": "700f38ba-9529-11e6-b202-f45c89c72de3",
  "organization_id": "7c99425e-9529-11e6-8107-f45c89c72de3",
  "room_id": "9f3d51a8-9529-11e6-80e7-f45c89c72de3",
  "assigned_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
  "assigned_user": {
    "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
    "full_name": "Bill Giosg",
    "first_name": "Bill",
    "last_name": "Giosg",
    "organization_id": "7c99425e-9529-11e6-8107-f45c89c72de3"
  },
  "visitor_id": "08119566026a4e1194a7a3244c90f925",
  "is_closed": false,
  "is_processable": false,
  "page_url": "https://giosg.com",
  "page_title": "Giosg - intelligent conversion marketing platform",
  "data": {
    "phone": "+123654789",
    "name": "Lead Man",
    "email": "lead.man@superheroes.gov"
  },
  "created_at": "2016-09-01T11:31:36.042Z",
  "updated_at": "2016-09-01T15:31:36.042Z",
  "closed_at": null,
  "sensitive_data_purged_at": null
}

You may update your assigned leads by:

PUT /api/v5/users/<user_id>/assigned_leads/<lead_id>

PATCH /api/v5/users/<user_id>/assigned_leads/<lead_id>

And pending leads:

PUT /api/v5/users/<user_id>/pending_leads/<lead_id>

PATCH /api/v5/users/<user_id>/pending_leads/<lead_id>

These endpoint returns:

Canned Answers API

Canned Answers

Canned answers are organization wide chat messages which can be made beforehand or at the moment. They track the usage count of whole organization, user and in room.

A canned answer resource has the following attributes.

Attribute Type Editable Description
id ID read-only UUID string identifier
organization_id ID read-only The UUID of the owner organization.
message string required The answer in string format.
organization_count integer read-only Answer usage count by whole organization.
room_count integer read-only Answer usage count in current room.
created_at date/time read-only When the answer was created.
updated_at date/time read-only When the answer updated last time.

List user’s canned answers at a room

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

{
  "next": "https://service.giosg.com/api/v5/users/7f9e9580-095b-42c7-838c-c04e667b26f7/rooms/9926bdfa-56e0-11e5-b98c-6c4008c08dfe/canned_answers?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "organization_id": "398b5138-3224-11e6-987e-f45c89c72de3",
      "message": "How can I help you?",
      "organization_count": 5,
      "room_count": 1,
      "created_at": "2015-02-13T11:31:36.042",
      "updated_at": "2015-02-13T12:38:36.431"
    }
  ]
}

This API endpoint returns a paginated collection of canned answers. They are sorted by the creation time of the canned answers, in ascending order.

This endpoint takes the following optional GET parameters:

Parameter Type Default Description
ordering ordering created_at Ordering of results with options created_at, updated_at, organization_count (ascending). All options work also in descending ordering with line before option e.g. -created_at

This endpoint returns:

Create a new canned answer

POST /api/v5/users/<user_id>/rooms/<room_id>/canned_answers

The user´s organization will be set as the organization_id.

{
  "message": "An example canned answer"
}

This endpoint returns:

Retrieve a single canned answer

You can to retrieve a canned answer’s details.

GET /api/v5/users/<user_id>/rooms/<room_id>/canned_answers/<canned_answer_id>

This endpoint returns:

Update a canned answer

You may update the message attribute of a canned answer.

PUT /api/v5/users/<user_id>/rooms/<room_id>/canned_answers/<canned_answer_id>

PATCH /api/v5/users/<user_id>/rooms/<room_id>/canned_answers/<canned_answer_id>

This endpoint returns:

Delete a canned answer

You may delete the canned answer. It will be deleted from the owner organization.

DELETE /api/v5/users/<user_id>/rooms/<room_id>/canned_answers/<canned_answer_id>

This endpoint returns:

Increment the canned answer counter

Request to this endpoint will increment counters (organization, user, room) of canned answer by one.

POST /api/v5/users/<user_id>/rooms/<room_id>/canned_answers/<canned_answer_id>/increment

This endpoint returns:

Real-time Reporting API

Room real-time statistics

Return a paginated collection of real-time statistics for the rooms you have access to

GET https://service.giosg.com/api/v4/reporting/realtime/rooms

This endpoint accepts the following GET parameters.

Parameter Type Default Description
room_id string filter results to only these (comma delimited) rooms
include_shared boolean false include shared rooms to the results
timezone string UTC Name of the timezone to use for time based aggregation e.g. Europe/Helsinki

A response contains following fields:

{
  "results": [
    {
      "room_id": "e6a850ca-e1d3-11e4-9706-38b1dbe48b5b",
      "room_name": "domain.com",
      "currently_open_chats": 8,
      "free_capacity": 4,
      "waiting_chats": 3,
      "average_wait_time": 14.6,
      "max_wait_time": 24.2,
      "missed_chats": 2,
      "real_chats": 76,
      "current_visitors": 123
    },
  ]
}
Attribute Type Description
room_id string UUID string identifier
room_name string Room name.
currently_open_chats integer Currently open chats.
free_capacity integer Free capacity across all online operator in the room.
waiting_chats integer Currently waiting chats.
average_wait_time float Average wait time of the currently waiting visitors.
max_wait_time float Maximum wait time of the currently waiting visitors.
real_chats integer Real chat conversations today.
missed_chats integer Chats missed by operators today.
current_visitors integer Currently active visitors on the webpage.
daily_avg_chat_wait_time float Daily average wait time of the waiting visitors.
daily_max_chat_wait_time float Daily maximum wait time of the waiting visitors.

This endpoint returns:

User real-time statistics

Return a paginated collection of real-time statistics for operators

GET https://service.giosg.com/api/v4/reporting/realtime/users

This endpoint accepts the following GET parameters.

Parameter Type Default Description
user_id integer filter results to only these (comma delimited) users

A response contains following fields:

{
  "results": [
    {
      "user_id": 1,
      "email": "name@domain.com",
      "is_logged_id": true,
      "is_online": true,
      "currently_open_chats": 3,
      "free_capacity": 2,
      "rooms": [
        {
          "room_id": "e6a850ca-e1d3-11e4-9706-38b1dbe48b5b",
          "room": {
            "currently_open_chats": 2,
            "id": "e6a850ca-e1d3-11e4-9706-38b1dbe48b5b",
            "name": "domain.com"
          }
        },
      ],
      "teams": [
        {
          "team_id": 1
        },
      ]
    },
  ]
}
Attribute Type Description
user_id integer ID integer identifier of user.
email string The email address of user.
currently_open_chats integer Currently open chats.
free_capacity integer Free capacity.
rooms array of objects Array of room objects.
teams array of objects Array of team objects.

This endpoint returns:

Rules API

Rules

The rule resource has the following attributes

Attribute  Type  Editable  Description
id  ID  read-only The unique identifier of this rule
organization_id ID read-only ID of the organization where this rule is configured
organization object  read-only The organization where this rule is configured
name string  required Name of the rule. Must be a non-empty string
is_enabled boolean required  Whether the rule is currently enabled.
type string optional Type of the Rule. Choices normal or target. Defaults to normal.
is_triggered_once_per_page boolean required Whether the rule can match only once on page. Defaults to false
is_triggered_once_per_session boolean required Whether the rule can match only once in session. Defaults to false.
is_triggered_once_per_visitor boolean required  Whether the rule can match only once for a visitor. Defaults to false.
created_at date/time  read-only When this rule was created
updated_at  date/time read-only When this rule was last updated
updated_by_user_id ID  read-only  ID of the user last updated this rule, or null if unknown
updated_by_user object read-only The person resource who last time updated this asset
auto_created boolean read-only Whether this rule was created automatically (e.g. as part of a custom button creation) instead of being created from the Rule management UI
conditions array of objects required Ordered list of conditions of this rule. The list order defines the matching order.
actions array of objects required  Ordered list of actions of this rule. The list order defines the execution order.
goal_id  ID  optional  ID of the goal of this rule
goal  object read-only The goal set for this rule

Rule Condition object

A rule condition object contains the following fields.

Attribute  Type Editable  Description
type integer required The type of the condition. See condition types below.
value string/integer optional The value related to the type. Required with most types. See choices below.
negate boolean optional  Whether or not the condition should be considered negated. That is, match becomes non-match and vice versa. Default false
settings object optional Other condition settings. Required with some condition types.

Condition types

type Description value settings
1 Visitor’s city  City name null
2 CSS selector matching elements on the web page  CSS selector null
3  Previous page URL matching a JavaScript regular expression  JavaScript regular expression  null
4  Visitor’s source URL matching a JavaScript regular expression  JavaScript regular expression null
5  Full page URL matching a JavaScript regular expression  JavaScript regular expression  null
6  Visitor’s country  Country name null
7  Visitor has visited the page more than the number Visit count  null
8  Shopping cart size being more than the value  Cart size null
9  Shopping cart size being less than the value  Cart size null
10  Shopping cart containing a product with the name Product name  null
11 Pipeline step number Pipeline step  null
12 Evaluate JavaScript expression  JavaScript expression null
13 Visitor has visited the page less than the number  Visit count  null
14 Visitor’s purchase count is more than the number  Number of purchases null
15  Visitor IP address matching JavaScript regular expression JavaScript regular expression null
16  Full page URL containing the string  Part of the URL null
17  Operator online presence  Either online (meaning any operator is online) or offline (all operators are offline) null
18  Visitor has been on the page a number of seconds  Number of seconds null
19  Click on an element matching the CSS selector  CSS selector null
20  Click on an button ID of the custom button object null
21 Visitor is using a device type  desktop or mobile or tablet or mobile,tablet null
22 Weekly schedule null array of schedule objects
23  Visitor’s priority is more than  Priority value  null
24 Visitor’s priority is less than Priority value null
25 Visitor was targeted null null

Rule Action object

Attribute  Type Editable  Description
type  integer required Type of the action. See choices below.
value string/integer optional The value related to the type. Required with most types. See choices below.
settings  object optional Other action settings. Required with some types.

Action types

type Description
1 Autosuggest autosuggest
2  Join the visitor to a list of rooms
5  Disable chat button
6  Disable autosuggest
7  Run a custom JavaScript
8 Enable chat button
9  Show elements matching CSS selector
10  Hide elements matching CSS selector
11  Go to a web page
13  Use a Lead Form when operators are offline
14 Change chat button text
15  Change chat button target room
16  Change chat window language
17  Show a Lead Form
18  Use a Lead Form processor
19 Show a button element
20 Show chat window
21 Set visitor priority
22 Disable autosuggest capacity check
23  Apply CSS to the web page

Goals API

Goals

Goals are events that can be triggered for a visitor. Goals are used for reporting and for Targeting.

A goal object contains the following attributes.

Attribute Type Editable Description
id ID read-only UUID string identifier
name string required Human readable name of the goal.
organization_id ID read-only The ID of the owner organization
organization object read-only The organization who owns this team.
is_any_room_allowed boolean required Can this goal match in any room
allowed_rooms array of ID required If is_any_room_allowed is false then this goal can match only in the allowed_rooms. Allowed rooms only allows rooms that the organization owns. Organization’s rooms can be fetched using the Rooms API
default_value float optional Default value of the goal. For example 14.15
conditions array of objects  required List of rule condition that are used for matching this goal.
created_at date/time read-only When the goal was created
created_by_user_id ID read-only The ID of the user who created this goal
created_by_user object read-only The user resource who created this goal
updated_at date/time read-only When the goal name or description was last time updated
updated_by_user_id ID read-only The ID of the user who last time updated this goal
updated_by_user object read-only The user resource who last time updated this goal

List goals for organization

Get a paginated collection of all the goals of your organization:

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

{
  "next": "https://service.giosg.com/api/v5/orgs/ac83d426-be80-4d75-8c62-49a77f98468e/goals",
  "previous": null,
  "results": [
    {
      "id": "4d0648b8-9074-11e6-963e-f45c89c72de3",
      "name": "User sent a lead",
      "allowed_rooms": ["e6a850ca-e1d3-11e4-9706-38b1dbe48b5b"],
      "allow_any_room": false,
      "default_value": "10.00",
      "conditions": [{
        "negate": false,
        "settings": {},
        "type": 27,
        "value": ""
      }],
      "organization_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
      "organization": {
        "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
        "name": "Example Ltd."
      },
      "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": "ac83d426-be80-4d75-8c62-49a77f98468e",
        "is_bot": false
      },
      "created_at": "2016-09-01T11:31:36.042Z",
      "updated_at": "2016-09-01T15:31:36.042Z",
      "updated_by_user_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
      "updated_by_user": {
        "id": "ac83d426-be80-4d75-8c62-49a77f98468e",
        "full_name": "Bill Giosg",
        "first_name": "Bill",
        "last_name": "Giosg",
        "organization_id": "ac83d426-be80-4d75-8c62-49a77f98468e",
        "is_bot": false
      }
    }
  ]
}

You can get a paginated collection of all assigned goals for the organization. They are sorted by the creation time of the goal, in ascending order.

This endpoint returns:

Creating a new goal

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

{
  "name": "A new goal",
  "allow_any_room": true,
  "allowed_rooms": [],
  "conditions": [{
    "negate": false,
    "settings": {},
    "type": 1,
    "value": "Helsinki"
  }]
}

This endpoint returns:

Retrieve a single goal

GET /api/v5/orgs/<organization_id>/goals/<goal_id>

This endpoint returns:

Update a goal

You may update goals for your organization. Fields name, allowed_any_room, allowed_rooms or conditions can be updated.

PUT /api/v5/orgs/<organization_id>/goals/<goal_id>

PATCH /api/v5/orgs/<organization_id>/goals/<goal_id>

This endpoint returns:

Goal Match API

This API was renamed. See External Goal Match API below.

External Goal Match API

You can use this endpoint to create goal matches from events that happen outside of the webpage where giosg is installed.

When this API should be used

This endpoint should only be used for tracking offline goals. The offline tracking workflow is explained here.

If you want to track goals while the visitor is on the webpage you can use Javascript SDK’s Goal Match API

Post new external goal match

{
    "visitor_identity": "customer-12345678",
    "goal_matched_at": "2016-10-10T22:00:49.123Z",
    "goal_value": "123.45",
    "rooms": ["ac83d426-be80-4d75-8c62-49a77f98468h", "ac83d426-be80-4d75-8c62-49a77f98468g"]
}

POST /api/v5/orgs/<organization_id>/goals/<goal_id>/matches

The external goal matching requires the following attributes.

Attribute Type Editable Description
visitor_identity string required Identifier for the visitor. This must be submitted beforehand using Visitor Identifier API
goal_matched_at date/time required The timestamp for the goal. It is used to link the goal with the visitor’s session.
rooms array of UUID’s required An array of room uuid’s where the goal matched.
goal_value decimal optional Value for this goal event. If not given then the default value for the Goal is used. If there is no default value, the value is left empty.

This endpoint returns:

Linking the goal to correct visitor session

The selected session is the most recent session for the given visitor_identity, that happened before the goal_matched_at.

When the correct session for the given visitor_identity is found.

Target API

Targets

A Target object represents a single Target setup in an organization. Currently a Target operates in one room of the organization, where it attempts to optimize goal conversion for a treatment.

Target resource has following attributes:

Attribute Type Editable Description
id ID read-only The unique identifier of this Target
organization_id ID read-only ID of the organization who owns this Target.
organization object read-only The organization who owns this Target.
room_id ID read-only ID of the room for which this Target is configured
room object read-only The room for which this Target is configured
is_enabled boolean read-only true if the Target is active, false if not
created_at date/time read-only When this Target was created.
created_by_user_id ID read-only ID of the user who created this Target, or null if unknown.
created_by_user object read-only Details of the user who created this Target, or null if unknown.
updated_at date/time read-only When this Target was updated last time.
updated_by_user_id ID read-only ID of the user who last updated this Target, or null if unknown.
updated_by_user object read-only Details of the user who last updated this Target, or null if unknown.

List Targets for organization

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

This endpoint returns:

Retrieve a Target

GET /api/v5/orgs/<organization_id>/targets/<target_id>

This endpoint returns:

TargetExperiments

A TargetExperiment represents an experiment in a Target context. An experiment is required for Target to function properly and also to provide indicators on the performance of the Target.

TargetExperiment resource has following attributes:

Attribute Type Editable Description
id ID read-only The unique identifier of this TargetExperiment
target_id object read-only ID of the Target for which this Experiment belongs to
experiment object read-only An experiment object
target_mode string read-only The name of the mode of the Target for this Experiment, choices: ab_test or data_collection
created_at date/time read-only When this TargetExperiment was created.
updated_at date/time read-only When this TargetExperiment was updated last time.

List Target experiments for organization and Target

GET /api/v5/orgs/<organization_id>/targets/<target_id>/experiments

This endpoint returns:

Retrieve a Target experiment

GET /api/v5/orgs/<organization_id>/targets/<target_id>/experiments/<target_experiment_id>

This endpoint returns:

Experiments API

Experiments

An experiment represents an A/B test. It has a goal and multiple groups with different treatments. Experiments can be limited duration or indefinite.

An experiment resource has following attributes:

Attribute Type Editable Description
id ID read-only The unique identifier of this Experiment
organization_id ID read-only ID of the organization who owns this Experiment.
created_at date/time read-only When this Experiment was created.
updated_at date/time read-only When this Experiment was updated last time.
starts_at date/time read-only When this Experiment starts being active.
ends_at date/time read-only When this Experiment stops being active, null for indefinite experiments.
name string read-only Name of this Experiment
group_reset_interval string read-only How often the groups are reset, choices: 1d for daily resets, 1w for weekly and full for no reset, i.e. a visitor’s group stays the same for the whole duration of the Experiment
goal_id ID read-only ID of the goal of this Experiment
groups array of objects read-only The groups of this experiment

Experiment groups

An experiment group represents a group, or a bucket, in an experiment. All the visitors in the same group will be given the same variation or treatment.

Attribute Type Editable Description
id ID read-only The unique identifier of this experiment group
name string read-only Name of this group
order integer read-only The index of this group in the order of groups within the experiment
percentage integer read-only The percentage this group has within the experiments group distribution.
treatment string read-only The name of the treatment rule that is used with this group. Can be null
group_type string read-only Type of the group. Choices currently are: control for the control group and target_algorithm, target_random which are used in the Target cases

Apps API

Public apps

Public apps include giosg Apps from any organization that are made available for everyone. Public apps can be installed by any organization.

An app is considered “public” if these conditions are true:

A public app resource has the following attributes

Attribute Type Editable Description
id ID read-only The ID of the app.
name string read-only Name of the app.
description string read-only Description for the app
owned_by_organization_id ID read-only The ID of the organization that the app belongs to.
owned_by_organization object read-only The organization resource to which the app belongs to.
icon_asset_id ID read-only The ID of the icon asset that the app is using.
icon_asset object read-only The icon asset resource that the app is using.
created_at date/time read-only When the app was created.
updated_at date/time read-only When the app was updated.

List all the public apps

Example request for listing public apps

GET https://service.giosg.com/api/v5/public_apps
{
  "next": "https://service.giosg.com/api/v5/public_apps?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "d8287ad2-7e07-44e3-b533-5a178cafecc1",
      "name": "Flappy giosg Balls",
      "description": "An awesome game!\nPlay it now!",
      "icon_asset_id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
      "icon_asset": {
          "id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
          "url": "https://giosg-chat-public-eu.s3.amazonaws.com/assets/1/4sBqqExlHlSmREGxmZLVt1QUwK2jtX.jpg",
          "width": 301,
          "height": 301
      },
      "owned_by_organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
      "owned_by_organization": {
          "id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
          "name": "giosg.com"
      },
      "created_at": "2017-01-01T12:00:00.123Z",
      "updated_at": "2017-01-02T15:00:00.123Z"
    }
  ]
}

Get a paginated collection of public apps:

GET /api/v5/public_apps

This returns a paginated collection of app(s) which are public. The results are ordered by created_at, in a descending order.

This endpoint returns:

Retrieve a single public app

A single public app can be retrieved with:

GET /api/v5/public_apps/<app_id>

This endpoint returns:

Partner apps

Partner apps are apps that your partner organizations in your network have made available to the whole network. They can be installed by the organization.

An app is considered a “partner app” of the organization if these conditions are true:

A partner app resource has the following attributes

Attribute Type Editable Description
id ID read-only The ID of the app.
name string read-only Name of the app.
description string read-only Description for the app
owned_by_organization_id ID read-only The ID of the organization that the app belongs to.
owned_by_organization object read-only The organization resource to which the app belongs to.
icon_asset_id ID read-only The ID of the icon asset that the app is using.
icon_asset object read-only The icon asset resource that the app is using.
created_at date/time read-only When the app was created.
updated_at date/time read-only When the app was updated.

List all the partner apps

Example request for listing partner apps

GET https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/partner_apps
{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/partner_apps?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "d8287ad2-7e07-44e3-b533-5a178cafecc1",
      "name": "Flappy giosg Balls",
      "description": "An awesome game!\nPlay it now!",
      "icon_asset_id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
      "icon_asset": {
          "id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
          "url": "https://giosg-chat-public-eu.s3.amazonaws.com/assets/1/4sBqqExlHlSmREGxmZLVt1QUwK2jtX.jpg",
          "width": 301,
          "height": 301
      },
      "owned_by_organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
      "owned_by_organization": {
          "id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
          "name": "giosg.com"
      },
      "created_at": "2017-01-01T12:00:00.123Z",
      "updated_at": "2017-01-02T15:00:00.123Z"
    }
  ]
}

Get a paginated collection of partner apps:

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

This returns a paginated collection of app(s) which are shared by organization’s partner. The results are ordered by created_at, in a descending order.

This endpoint returns:

Retrieve a single partner app

A single partner app can be retrieved with:

GET /api/v5/orgs/<organization_id>/partner_apps/<app_id>

This endpoint returns:

Owned apps

When an organization creates a new app, it becomes an “owner” organization of that app and have the ultimate authority to the app and its installations. Apps created by an organization are therefore referred as owned apps. The owner organization can always install any of their owned apps.

An owned app resource has the following attributes:

Attribute Type Editable Description
id ID read-only The ID of the app.
name string required Name of the app.
description string required Description for the app.
owned_by_organization_id ID read-only The ID of the organization that the app belongs to.
owned_by_organization object read-only The organization resource to which the app belongs to.
icon_asset_id ID optional The ID of the icon asset that the app is using.
icon_asset object read-only The icon asset resource that the app is using.
is_available_to_anyone boolean read-only Whether the application is public for all organization’s in giosg system. Currently only giosg can provide public applications.
is_available_to_partners boolean optional Whether the application is public for your partner organizations.
is_app_user_required boolean required Whether the app requires a bot user for the installing organization. This is done automatically when the app is installed.
app_user_default_first_name string optional Default first name for the bot user. This is required if is_app_user_required is set as true. This field is nullable but blank string is not allowed.
app_user_default_last_name string optional Default last name for the bot user. This is required if is_app_user_required is set as true. This field is nullable but blank string is not allowed.
app_user_default_alias string optional Default alias for the bot user. This field is nullable but blank string is not allowed.
terms_of_service_url string required URL for application’s terms of service.
privacy_policy_url string required URL for application’s privacy policy.
trigger_url string optional URL which is used whenever one of the given trigger_conditions match.
trigger_conditions list of strings optional List of trigger conditions in string format. These are always sorted alphabetically. See supported trigger conditions below.
created_at date/time read-only When the app was created.
updated_at date/time read-only When the app was updated.
created_by_user_id ID read-only ID of the user who created this app.
created_by_user object read-only The user resource created this app.
updated_by_user_id ID read-only ID of the user who last updated this app.
updated_by_user object read-only The user resource who last updated this app.
secret string read-only The secret key of the app.

Supported trigger conditions

Here’s the list of supported trigger conditions:

Condition Description
chat_start Run on background when chat starts.
chat_end Run on background when chat ends.
chat_open Run when chat window is opened.
chat_close Run when chat window is closed.
chat_focus Run when chat window is focused.
console_load Run on background when console loads.
manual_dialog Run manually from chat dialog.
manual_nav Run manually from top navigation.
setup Run when clicking the “Setup” link from “Installed apps”.

List apps owned by an organization

Example request for listing owned apps

GET https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps
{
  "next": "https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "d8287ad2-7e07-44e3-b533-5a178cafecc1",
      "name": "Flappy giosg Balls",
      "description": "An awesome game!\nPlay it now!",
      "icon_asset_id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
      "icon_asset": {
          "id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
          "url": "https://giosg-chat-public-eu.s3.amazonaws.com/assets/1/4sBqqExlHlSmREGxmZLVt1QUwK2jtX.jpg",
          "width": 301,
          "height": 301
      },
      "owned_by_organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
      "owned_by_organization": {
          "id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
          "name": "giosg.com"
      },
      "secret": "fb612fac0e6e4550b6c24d15ffa0d4b5",
      "is_available_to_anyone": false,
      "is_available_to_partners": false,
      "terms_of_service_url": "https://www.giosg.com/terms-of-service",
      "privacy_policy_url": "https://www.giosg.com/privacy-policy",
      "trigger_url": "https://ktkiiski.github.io/giosg-balls/?mode=app",
      "trigger_conditions": [
          "chat_start",
          "chat_end",
          "chat_open",
          "chat_close",
          "chat_focus",
          "console_load",
          "manual_dialog",
          "manual_nav",
          "setup"
      ],
      "is_app_user_required": false,
      "app_user_default_first_name": "Robotti",
      "app_user_default_last_name": "Ruttunen",
      "app_user_default_alias": "Chat bot",
      "created_at": "2017-01-01T12:00:00.123Z",
      "created_by_user_id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
      "created_by_user": {
          "id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
          "first_name": "Kimmo",
          "last_name": "Kiiski",
          "full_name": "Kimmo Kiiski",
          "organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a"
      },
      "updated_at": "2017-01-02T15:00:00.123Z",
      "updated_by_user_id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
      "updated_by_user": {
          "id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
          "first_name": "Kimmo",
          "last_name": "Kiiski",
          "full_name": "Kimmo Kiiski",
          "organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a"
      }
    }
  ]
}

Get a paginated collection of organization’s owned apps:

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

This returns a paginated collection of app(s) which are owned by organization. The results are ordered by created_at, in a descending order.

This endpoint returns:

Create a new app for an organization

Example request for creating new owned app

POST https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps

Example request payload

{
  "name": "Flappy giosg Balls",
  "description": "An awesome game!\nPlay it now!",
  "icon_asset_id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
  "is_available_to_partners": false,
  "is_app_user_required": false,
  "terms_of_service_url": "https://www.giosg.com/terms-of-service",
  "privacy_policy_url": "https://www.giosg.com/privacy-policy",
  "trigger_url": "https://ktkiiski.github.io/giosg-balls/?mode=app",
  "trigger_conditions": ["chat_start", "chat_end", "chat_open", "chat_close", "chat_focus", "console_load", "manual_dialog", "manual_nav"]
}

A new owned app can be created with:

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

Note that it won’t be automatically installed for your organization or any other organization.

This endpoint returns:

Retrieve an app owned by an organization by the app’s ID

A single owned app can be retrieved with:

GET /api/v5/orgs/<organization_id>/owned_apps/<app_id>

This endpoint returns:

Update an app owned by an organization

A single owned app can be updated with:

PUT /api/v5/orgs/<organization_id>/owned_apps/<app_id>

OR

PATCH /api/v5/orgs/<organization_id>/owned_apps/<app_id>

Note that changing the publicity attributes won’t uninstall the app from organizations’ which have already installed it.

This endpoint returns:

Delete an owned app

A single owned app can be deleted with:

DELETE /api/v5/orgs/<organization_id>/owned_apps/<app_id>

Note that deleting owned app will uninstall it from everyone.

This endpoint returns:

Installed apps

Apps that are installed for an organization, being “in effect” for the organization. Usually the apps are owned by some other organization, but the organization can of course install their own apps, in which case the owner organization equals to the one in the URL.

An installed app resource has the following attributes:

Attribute Type Editable Description
id ID read-only The ID of the app.
name string read-only Name of the app.
description string read-only Description for the app
owned_by_organization_id ID read-only The ID of the organization that the app belongs to.
owned_by_organization object read-only The organization resource to which the app belongs to.
icon_asset_id ID read-only The ID of the icon asset that the app is using.
icon_asset object read-only The icon asset resource that the app is using.
trigger_conditions list of strings read-only List of trigger conditions. These were defined under owned apps section.
created_at date/time read-only When the app was created.
updated_at date/time read-only When the app was updated.

To add or remove installed apps, use app installations.

List all the installed apps

Example request for listing installed apps

GET https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/installed_apps
{
  "next": "https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/installed_apps?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "d8287ad2-7e07-44e3-b533-5a178cafecc1",
      "name": "Flappy giosg Balls",
      "description": "An awesome game!\nPlay it now!",
      "icon_asset_id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
      "icon_asset": {
          "id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
          "url": "https://giosg-chat-public-eu.s3.amazonaws.com/assets/1/4sBqqExlHlSmREGxmZLVt1QUwK2jtX.jpg",
          "width": 301,
          "height": 301
      },
      "owned_by_organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
      "owned_by_organization": {
          "id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
          "name": "giosg.com"
      },
      "created_at": "2017-01-01T12:00:00.123Z",
      "updated_at": "2017-01-02T15:00:00.123Z",
      "trigger_conditions": [
          "chat_start",
          "chat_end",
          "chat_open",
          "chat_close",
          "chat_focus",
          "console_load",
          "manual_dialog",
          "manual_nav",
          "setup"
      ]
    }
  ]
}

Get a paginated collection of organization’s installed apps:

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

This returns a paginated collection of app(s) which are installed by organization. The results are ordered by created_at, in a descending order.

This endpoint returns:

Retrieve a single installed app

A single owned app can be retrieved with:

GET /api/v5/orgs/<organization_id>/installed_apps/<app_id>

This endpoint returns:

App installations

When an app is activated, i.e. installed, to an organization, an app installation resource is created. The installation resource exists until the app is uninstalled. Installation resources are unique to the app and the organization, in other words, a single app can only be installed once to an organization, until uninstalled.

An app installation resource has the following attributes:

Attribute Type Editable Description
organization_id ID read-only The ID of the organization that has installed the app.
organization object read-only The organization resource to which the app.
app_id ID read-only The ID of the [installed app][].
app object read-only The [installed app][] resource that the app is using.
app_user_id ID read-only The ID of the app user.
app_user object read-only The app user resource.
created_at date/time read-only When the app installation was created.
updated_at date/time read-only When the app installation was updated.

List all the app installations for an organization

Example request for listing app installations

GET https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/app_installations
{
  "next": "https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/app_installations?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "organization_id": "a019708a-7889-419d-87ee-6ae2be73e8d5",
      "organization": {
          "id": "a019708a-7889-419d-87ee-6ae2be73e8d5",
          "name": "Another Organization Ltd."
      },
      "app_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
      "app": {
          "name": "Flappy giosg Balls",
          "description": "My cool application",
          "owned_by_organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
          "owned_by_organization": {
              "id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
              "name": "giosg.com"
          },
          "created_at": "2017-01-01T12:00:00.123Z",
          "updated_at": "2017-01-02T15:00:00.123Z"
      },
      "created_at": "2017-01-03T13:00:00.123Z",
      "updated_at": "2017-01-04T13:00:00.123Z",
      "app_user_id": "44a3300c-500f-4edf-853e-a3e9536db16c",
      "app_user": {
          "id": "44a3300c-500f-4edf-853e-a3e9536db16c",
          "first_name": "Bob",
          "last_name": "The Bot",
          "full_name": "Bob The Bot",
          "organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a"
      }
    }
  ]
}

Get a paginated collection of organization’s app installations:

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

This returns a paginated collection of organization’s app installation(s). The results are ordered by created_at, in a descending order.

This endpoint returns:

Retrieve an app installation for an organization

A single app installation can be retrieved with:

GET /api/v5/orgs/<organization_id>/app_installations/<app_id>

This endpoint returns:

Owned app installations

Apps owned by your organization may be installed by you or any other organization. These installation will be available to your organization as owned app installations. Owned app installations only include resources that relate to apps provided by your organization.

An owned app installation resource has the following attributes:

Attribute Type Editable Description
organization_id ID read-only The ID of the organization that has installed the app.
organization object read-only The organization resource to which the app.
app_id ID read-only The ID of the [installed app][].
app object read-only The [installed app][] resource that the app is using.
app_user_id ID read-only The ID of the app user.
app_user object read-only The app user resource.
created_at date/time read-only When the app installation was created.
updated_at date/time read-only When the app installation was updated.

List all the installations for an app owned by an organization

Example request for listing installations of one of your owned apps

GET https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps/4e961cde-79e1-4b46-813c-73996659926c/installations
{
  "next": "https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps/4e961cde-79e1-4b46-813c-73996659926c/installations?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "app_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
      "app": {
          "name": "Flappy giosg Balls",
          "description": "My cool application",
          "owned_by_organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
          "owned_by_organization": {
              "id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
              "name": "giosg.com"
          },
          "created_at": "2017-01-01T12:00:00.123Z",
          "updated_at": "2017-01-02T15:00:00.123Z"
      },
      "organization_id": "a019708a-7889-419d-87ee-6ae2be73e8d5",
      "organization": {
          "id": "a019708a-7889-419d-87ee-6ae2be73e8d5",
          "name": "giosg.com"
      },
      "created_at": "2017-01-03T13:00:00.123Z",
      "updated_at": "2017-01-04T13:00:00.123Z",
      "app_user_id": "44a3300c-500f-4edf-853e-a3e9536db16c",
      "app_user": {
          "id": "44a3300c-500f-4edf-853e-a3e9536db16c",
          "first_name": "Bob",
          "last_name": "The Bot",
          "full_name": "Bob The Bot",
          "organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a"
      }
    }
  ]
}

Get a paginated collection of organization’s app installations:

GET /api/v5/orgs/<organization_id>/owned_apps/<app_id>/installations

This returns a paginated collection of organization’s owned app’s installation(s). The results are ordered by created_at, in a descending order.

This endpoint returns:

Retrieve a single installation of an owned app to a single organization

A single owned app installation can be retrieved with:

GET /api/v5/orgs/<organization_id>/owned_apps/<app_id>/installations/<installer_organization_id>

This endpoint returns:

Uninstall the app from another organization

An owned app installation can be uninstalled with:

DELETE /api/v5/orgs/<organization_id>/owned_apps/<app_id>/installations/<installer_organization_id>

This endpoint returns:

Installing apps

Your organization must have the giosg Apps feature enabled by giosg support. giosg Apps can be installed by navigating a user (who has the settings permissions) to the following address:

https://service.giosg.com/apps/<app_id>/install?next=<redirect_uri>

User is prompted to log in if they are not already. The user will be confirmed that the app with ID <app_id> will be installed to their organization. After installed successfully, the user will be redirected to the given URI <redirect_uri>.

NOTE: For now, the next URI can only be located at the origin https://service.giosg.com. Ability to redirect to external websites may be added in the future.

If the app requires an app user, the user will be prompted for the basic information for the app user to be created.

A successful installation will result in creating a app installation, adding the app to the organization’s installed apps, and possibly creating an app user (initially without any additional permissions).

If required by the app (their is_app_user_required is true), installing an app creates an app user that belongs to the organization which installed the app.

By default, the app user has regular access to the organization, without any additional permissions. The organization users with users permissions can add additional permissions to the app user at User management if necessary.

To list all the app installations, including any app users created for them, see App installations.

App users

Apps whose is_app_user_required attribute is true are installed with a new app user. An app user is a user account usually controlled by a “machine”, e.g. a web service. A typical example of an app user is a chat bot.

App users belong to the organization who installed the app. Therefore they have, by default, the regular access to the organization. However, app users can be controlled by the provider of the giosg App, as they are able to create API tokens on their behalf. For example, the web server of a chat bot provider may join chats and send messages as the chat bot “app user” that was created on installation.

App users are bound to app installations so you can fetch them by listing the installations of your owned apps. If there is no app user, the app_user attribute will be null.

Webhooks

You may define webhooks for your app that allow your server to receive real-time notifications about changes in the organization who have installed your app. For example, when implementing a chat bot, you most probably need to define webhooks for any chats and chat messages being sent to your servers, so that the bot can react to them.

A webhook describes an URL to which notifications will be sent with POST HTTP requests. To have any effect, the webhook should have at least one channel subscription to receive notifications.

IMPORTANT: It might take a short while for the changes in webhooks to take effect!

A webhook resource has the following attributes:

Attribute Type Editable Description
id ID read-only The ID of the app.
organization_id ID read-only The ID of the organization that owns the webhook.
organization object read-only The organization resource to which owns the webhook.
app_id ID read-only The ID of the app which uses this webhook.
app object read-only The app resource that is using the webhook.
endpoint_url string required URL to which the webhook is sent.
channel_subscriptions list of objects optional List of channel subscriptions objects. See supported attributes below. Also please read more detailed section about webhook channel subscriptions.
created_at date/time read-only When the webhook was created.
updated_at date/time read-only When the webhook was updated.
created_by_user_id ID read-only ID of the user who created this webhook.
created_by_user object read-only The user resource created this webhook.
updated_by_user_id ID read-only ID of the user who last updated this webhook.
updated_by_user object read-only The user resource who last updated this webhook.

A webhook channel subscription resource has the following attributes:

Attribute Type Editable Description
channel_pattern string required The channel pattern i.e. basically some API endpoint in specific format. The format is explained better in webhook channel subscriptions section.
is_additions_subscribed boolean required Whether a webhook is sent when new resource is added to the collection.
is_changes_subscribed boolean required Whether a webhook is sent when resource changes happen for a item.
is_removals_subscribed boolean required Whether a webhook is sent when a resource is removed from the collection.

List all webhooks for your app

Example request for listing webhooks

GET https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps/4e961cde-79e1-4b46-813c-73996659926c/webhooks
{
  "next": "https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps/4e961cde-79e1-4b46-813c-73996659926c/webhooks?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "8deb52f9-6824-4c84-96d4-1a3a4f3d88ad",
      "created_at": "2017-01-01T12:00:00.123Z",
      "updated_at": "2017-01-02T15:00:00.123Z",
      "created_by_user_id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
      "created_by_user": {
          "id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
          "first_name": "Kimmo",
          "last_name": "Kiiski",
          "full_name": "Kimmo Kiiski",
          "organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a"
      },
      "updated_by_user_id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
      "updated_by_user": {
          "id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
          "first_name": "Kimmo",
          "last_name": "Kiiski",
          "full_name": "Kimmo Kiiski",
          "organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a"
      },
      "app_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
      "app": {
          "name": "Flappy giosg Balls",
          "description": "My cool application",
          "owned_by_organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
          "owned_by_organization": {
              "id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
              "name": "giosg.com"
          },
          "created_at": "2017-01-01T12:00:00.123Z",
          "updated_at": "2017-01-02T15:00:00.123Z"
      },
      "organization_id": "a019708a-7889-419d-87ee-6ae2be73e8d5",
      "organization": {
          "id": "a019708a-7889-419d-87ee-6ae2be73e8d5",
          "name": "giosg.com"
      },
      "endpoint_url": "https://www.example.com/messages",
      "channel_subscriptions": [{
          "channel_pattern": "/api/v5/users/{user_id}/chats/*/messages",
          "is_additions_subscribed": true,
          "is_changes_subscribed": false,
          "is_removals_subscribed": false
      }]
    }
  ]
}

Get a paginated collection of organization’s owned app’s webhooks:

GET /api/v5/orgs/<organization_id>/owned_apps/<app_id>/webhooks

This returns a paginated collection of organization’s owned app’s webhook(s). The results are ordered by created_at, in a descending order.

This endpoint returns:

Retrieve a single webhook of your app

A single webhook can be retrieved with:

GET /api/v5/orgs/<organization_id>/owned_apps/<app_id>/webhooks/<webhook_id>

This endpoint returns:

Create a new webhook to your app

Example request for creating new webhook

POST https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps/f2238fae-2080-49bd-a4a5-8adef8b45b9a/webhooks

Example request payload

{
  "endpoint_url": "https://ktkiiski.github.io/giosg-balls/chat-messages",
  "channel_subscriptions": [{"channel_pattern": "/api/v5/users/{user_id}/chats/*/messages", "is_additions_subscribed": true, "is_changes_subscribed": false, "is_removals_subscribed": false}]
}

A new webhook for owned app can be created with:

POST /api/v5/orgs/<organization_id>/owned_apps/<app_id>/webhooks

This endpoint returns:

Update a single webhook of your app

A single webhook of owned app can be updated with:

PUT /api/v5/orgs/<organization_id>/owned_apps/<app_id>/webhooks/<webhook_id>

OR

PATCH /api/v5/orgs/<organization_id>/owned_apps/<app_id>/webhooks/<webhook_id>

This endpoint returns:

Delete a webhook, including all of its channel subscriptions

An owned app’s webhook can be deleted with:

DELETE /api/v5/orgs/<organization_id>/owned_apps/<app_id>/webhooks/<webhook_id>

This endpoint returns:

Webhook channel subscriptions

Your webhooks need to contain at least one channel subscription defining which channels should be notified to the webhook URL. These are defined in the channel_subscriptions array, including objects containing channel_pattern attributes.

If you want to deliver notifications from different channels to different URLs, you should create separate webhooks with different endpoint_url attribute and the list of channel_subscriptions.

A webhook channel subscription channel_pattern must start with one of the following exact strings:

In these patterns, the {organization_id} placeholder will match the organization that have installed the app. The {user_id} placeholder will match the app user of the installation.

In addition to these, the following exact patterns are allowed:

This will allow your servers get notifications about any new installs (is_additions_subscribed) or uninstalls (is_removals_subscribed) of your app! For example, when receiving an added message, you may then create an API token for the app user of the new installation, or perform any other setup.

IMPORTANT: This section will improve soon and will contain information how the App User’s API Token will be provided for the app provider.

Webhook log entries

Each webhook request is logged. Log entries contain information about the request status and response. The entries are stored for 7 days.

Webhook log entry resource has the following attributes.

Attribute Type Editable Description
created_at date/time read-only When the log entry was created.
app_id ID read-only The ID of the app.
organization_id ID read-only The ID of the app owner organization.
webhook_id ID read-only The ID of the webhook.
endpoint_url string read-only The request URL of the webhook.
action string read-only Resource action, either added, removed or changed.
resource_id string read-only The ID of the resource.
channel string read-only Channel that has been about the resource action.
status string read-only Status of the webhook request, either pending, started, successful or failed.
retry_index integer read-only How many times the request has been retried.
reason string read-only The reason for failure if status is failed, otherwise null.
response_status_code integer read-only Status code of a completed request, null if in progress.
response_body string read-only Response body of a completed request, null if in progress.
response_headers dict read-only Key-value map containing response headers of a completed request, null if in progress.
duration integer read-only How many milliseconds lasted to get a response for the request, null if in progress.
completed_at date/time read-only When the request was completed.

List webhook log entries

Get a paginated collection of webhook log entries for owned app:

GET /api/v5/orgs/<organization_id/owned_apps/<app_id>/webhook_log_entries

This returns a paginated collection of webhook log entries for the given app_id. The results are ordered by created_at, in descending order.

This endpoint returns:

Scheduled Email Reporting API

Scheduled email reports

By configuring a scheduled email report you will receive an email containing the selected information. You may configure the email to be sent daily, weekly or monthly.

A scheduled email report object has the following attributes::

Attribute Type Editable Description
id ID read-only Unique identifier of this scheduled email report.
organization_id ID read-only ID of the organization which owns the scheduled email report.
organization object read-only The organization object which owns the scheduled email report.
rooms array of ids required List of room object ids that are configured for the report.
updated_by_user_id ID read-only Which user object has modified this scheduled email report last.
schedule string optional Schedule can be dailyweekly/monthly. Defaults to daily.
email_type string optional Email type can be statistics or exports.
export_config object read-only If email type is export then this field will show the export configuration.
export_config_id ID optional ID of the export which is connected this scheduled email report. Required when creating export type scheduled email.
name string required Name of the scheduled email report
created_at date/time read-only When the scheduled email report was created.
updated_at date/time read-only When the scheduled email report was last time updated.
report_runs array of objects read-only Array of report run objects giving information about when the report has been sent and was the sending of the email successful.

Create organization’s scheduled email reports

You may create new scheduled email report for your organization by:

Example request

{
    "rooms": [
        "1e934307-d421-11e7-860c-2816ad4d2a7e"
    ],
    "name": "daily report",
    "schedule": "daily",
    "email_type": "statistics",
    "export_config_id": "1e9342fe-d421-11e7-86hc-2816ah4d2a7e"
}

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

This endpoint returns:

List organization’s scheduled email reports

Example request for retrieving list of scheduled email report objects

GET https://service.giosg.com/api/v5/orgs/ac83d426-be80-4d75-8c62-49a77f98468e/email_reports

Example response

{
    "next": null,
    "previous": null,
    "results": [
        {
            "email_type":"export",
            "schedule":"daily",
            "created_at": "2018-01-02T11:39:58.690309",
            "updated_at": "2018-01-02T11:39:58.690320",
            "updated_by_user_id": "e4d4539b-efa0-11e7-8da0-2816ad4d2a9a",
            "organization_id":"e4d4539b-efa0-11e7-8da0-2816ad4d2a7e",
            "rooms":[
                "e4d453a2-efa0-11e7-8da0-2816ad4d2a7e"
            ],
            "export_config":{
                "file_name":"test_report_aljESMtlfi.csv",
                "format":"csv",
                "type":"Chat logs",
                "id":"e4d453a4-efa0-11e7-8da0-2816ad4d2a7e",
                "fields": [
                    "room",
                    "chatsession",
                    "operator",
                    "chatlog"
                ]
            },
            "organization":{
                "id":"e4d4539b-efa0-11e7-8da0-2816ad4d2a7e",
                "name":"CompanyqdryFZ"
            },
            "report_runs": [
                {
                    "completed_at": "2017-08-02T10:10:10",
                    "started_at": "2017-08-01T00:00:00",
                    "id": "6c8643b8-efc0-11e7-8da0-2816ad4d2a7e",
                    "timeslot": "2017-07-01_2017-08-02"
                },
                {
                    "completed_at": "2017-08-02T10:10:10",
                    "started_at": "2017-08-01T00:00:00",
                    "id": "6c8643b7-efc0-11e7-8da0-2816ad4d2a7e",
                    "timeslot": "2017-07-01_2017-08-01"
                }
            ],
            "id":"e4d453a8-efa0-11e7-8da0-2816ad4d2a7e",
            "name":"daily stats"
        },
        {
            "email_type":"export",
            "schedule":"weekly",
            "created_at": "2018-01-02T11:39:58.690309",
            "updated_at": "2018-01-02T11:39:58.690320",
            "updated_by_user_id": "e4d4539b-efa0-11e7-8da0-2816ad4d2a9a",
            "organization_id":"e4d4539b-efa0-11e7-8da0-2816ad4d2a7e",
            "rooms":[
                "e4d453a2-efa0-11e7-8da0-2816ad4d2a7e"
            ],
            "export_config":{
                "file_name":"test_report_aljESMtlfi.csv",
                "format":"csv",
                "type":"Chat logs",
                "id":"e4d453a4-efa0-11e7-8da0-2816ad4d2a7e",
                "fields": [
                    "room",
                    "chatsession",
                    "operator",
                    "chatlog"
                ]
            },
            "report_runs": [],
            "organization":{
                "id":"e4d4539b-efa0-11e7-8da0-2816ad4d2a7e",
                "name":"CompanyqdryFZ"
            },
            "id":"e4d453a8-efa0-11e7-8da0-2816ad4d2a7e",
            "name":"weekly stats"
        }
    ]
}

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

This endpoint returns:

Retrieve organization’s scheduled email reports

You may retrieve a single scheduled email report object by its ID (<report_id>) that organization (<organization_id>) is eligible for:

GET /api/v5/orgs/<organization_id>/email_reports/<report_id>

Example request for retrieving single scheduled email report object

GET https://service.giosg.com/api/v5/orgs/ac83d426-be80-4d75-8c62-49a77f98468e/email_reports

This endpoint returns:

Update organization’s scheduled email reports

You may update your organization’s scheduled email reports by:

Example request

{
    "rooms": [
        "1e934307-d421-11e7-860c-2816ad4d2a7e",
        "1e934307-d421-11e7-860c-2816ad4d2a7s"
    ],
    "name": "old stats",
    "schedule": 2,
    "email_type": 2,
    "export_id": "1e9342fe-d421-11e7-86hc-2816ah4d2a7e"
}

PUT /api/v5/orgs/<organization_id>/email_reports/<report_id>

PATCH /api/v5/orgs/<organization_id>/email_reports/<report_id>

This endpoint returns:

Delete organization’s scheduled email reports

You may update your organization’s scheduled email reports by:

DELETE /api/v5/orgs/<organization_id>/email_reports/<report_id>

This endpoint returns:

Scheduled email report subscriptions

By creating and configuring scheduled email report subscription objects you may specify users which will receive the emails periodically.

A scheduled email report subscription object has the following attributes::

Attribute Type Editable Description
id ID read-only Unique identifier of this scheduled email report subscription.
user_id ID required ID of the subscribed user.
user object read-only Subscribed user.
report_id ID required ID of the scheduled email report for the subscription.

Create subscription for scheduled email report

You may create new scheduled email subscription for your organization by:

Example request

{
    "user_id": "1e934307-d421-11e7-860c-2816ad4d2a7e"
}

POST /api/v5/orgs/<organization_id>/email_reports/<report_id>/subscriptions

This endpoint returns:

List subscriptions for scheduled email report

Example request for retrieving list of scheduled email subscription objects

GET https://service.giosg.com/api/v5/orgs/ac83d426-be80-4d75-8c62-49a77f98468e/email_reports/subscriptions/

Example response

{
    "next": null,
    "previous": null,
    "results": [
        {
            "user": {
                "first_name": "HewmTUOJLZ",
                "last_name": "tfjskBOwaS",
                "id": "5c5fce87-efba-11e7-8da0-2816ad4d2a7e",
                "full_name": "HewmTUOJLZ tfjskBOwaS",
                "email": "arpxqczgoj@example.com"
            },
            "id": "5c5fce8f-efba-11e7-8da0-2816ad4d2a7e",
            "report_id": "5c5fce8e-efba-11e7-8da0-2816ad4d2a7e"
        },
        {
            "user": {
                "first_name": "NzeUGlnEdG",
                "last_name": "TtvaniGFar",
                "id": "5c5fce88-efba-11e7-8da0-2816ad4d2a7e",
                "full_name": "NzeUGlnEdG TtvaniGFar",
                "email": "riapswfvld@example.com"
            },
            "id": "5c5fce90-efba-11e7-8da0-2816ad4d2a7e",
            "report_id": "5c5fce8e-efba-11e7-8da0-2816ad4d2a7e"
        }
    ]
}

GET /api/v5/orgs/<organization_id>/email_reports/<report_id>/subscription

This endpoint returns:

Delete subscription for scheduled email report

You may delete your organization’s scheduled email subscriptions by:

DELETE /api/v5/orgs/<organization_id>/email_reports/<report_id>/subscription/<subscription_id>

This endpoint returns:

Scheduled email report external subscriptions

By creating and configuring scheduled email report external subscription objects you may specify external email addresses which will receive the emails periodically.

A scheduled email report external subscription object has the following attributes:

Attribute Type Editable Description
id ID read-only Unique identifier of this scheduled email report external subscription.
email string required Email address where the subscriped report will be sent.
report_id ID required ID of the scheduled email report for the external subscription.

Create external subscription for scheduled email report

You may create new scheduled email external subscription for your organization by:

Example request

{
    "email": "test@example.com"
}

POST /api/v5/orgs/<organization_id>/email_reports/<report_id>/external_subscriptions

This endpoint returns:

List external subscriptions for scheduled email report

Example request for retrieving list of scheduled email external subscription objects

GET https://service.giosg.com/api/v5/orgs/ac83d426-be80-4d75-8c62-49a77f98468e/email_reports/ac83d426-be80-4d75-8c62-49a77f98468e/external_subscriptions

Example response

{
    "next": null,
    "previous": null,
    "results": [
        {
            "email": "test@example.com",
            "id": "5c5fce8f-efba-11e7-8da0-2816ad4d2a7e",
            "report_id": "5c5fce8e-efba-11e7-8da0-2816ad4d2a7e"
        },
        {
            "email": "another@example.com",
            "id": "5c5fce90-efba-11e7-8da0-2816ad4d2a7e",
            "report_id": "5c5fce8e-efba-11e7-8da0-2816ad4d2a7e"
        }
    ]
}

GET /api/v5/orgs/<organization_id>/email_reports/<report_id>/external_subscriptions

This endpoint returns:

Delete external subscription for scheduled email report

You may delete your organization’s scheduled email external subscriptions by:

DELETE /api/v5/orgs/<organization_id>/email_reports/<report_id>/external_subscriptions/<external_subscription_id>

This endpoint returns: