Skip to content

General

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 (user) belongs to a certain organization.
visitor Visitor (room 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 (room visitor) and there may be multiple of both of them in one chat conversation.
lead lead(s) 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

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.

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. room(s) 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

1
GET /api/v5/languages

An example response

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

  • 403 if the authentication credentials were incorrect

Supported time zones

All common time zones are supported by giosg. The format for time zone is standard 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

1
GET /api/v5/timezones

An example response

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

API endpoints

All API endpoints provided by giosg. Can be used as a cheat sheet what endpoints giosg provides. Contains also the information about the supported HTTP methods and what permission scopes are required for the method.

Endpoint object consists:

Attribute Type Description
url_pattern string URL pattern of the endpoint.
methods object Contains information about supported HTTP methods and required permission scopes.
comment string Additional information about the endpoint.

List API endpoints

An example request

1
GET /api/v5/endpoints

An example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
{
  "next": null,
  "previous": null,
  "results": [
    {
      "url_pattern": "/api/v5/currencies",
      "methods": [
        {
          "name": "GET",
          "scopes": []
        },
        {
          "name": "OPTIONS",
          "scopes": []
        }
      ],
      "comment": ""
    },
    {
      "url_pattern": "/api/v5/endpoints",
      "methods": [
        {
          "name": "GET",
          "scopes": []
        },
        {
          "name": "OPTIONS",
          "scopes": []
        }
      ],
      "comment": ""
    },
    {
      "url_pattern": "/api/v5/orgs/<organization_id>/overview",
      "methods": [
        {
          "name": "GET",
          "scopes": ["settings", "reports"]
        },
        {
          "name": "OPTIONS",
          "scopes": ["settings", "reports"]
        }
      ],
      "comment": "This API endpoint requires 'settings' permission for unsafe methods while 'reports' permission is sufficient for safe methods."
    }
  ]
}

You may list API endpoints by:

GET /api/v5/endpoints

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