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:

• Authenticate your user by prompting their email and password, and store the access token.
• Authorize all your following API requests with the access token.
• Renew the access token when it's about to expire.
• Register user's client, and start listening for real-time changes via Google Cloud Messaging
• Retrieve the authenticated user for showing their information in the UI.
• Update the user. For example, allow them to be online or switch them to offline, when user clicks a "Start"/"Stop" button.
• Retrieve or update user's preferences. For example: change the user's chat capacity.
• List the rooms of the user.
• Retrieve a room overview, e.g. for showing how many visitors there are currently present at the user's rooms.
• List the user's chats, probably filtering only those where they are currently a participating member.
• List the user's pending chats. They except that someone would respond to them!
• Join the user to a pending chat, letting the user to participate the chat and to "take" this chat to themselves.
• List chat messages of your chat.
• Send a new chat message to your chat.
• Update the user's chat membership, for example when they open or close chats, or when typing a message.

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

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:

• 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

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

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

GET /api/v5/endpoints

An example response

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