Skip to content

Setting up giosg Widgets

Introduction

Welcome to giosg API documentation's Widgets section!

In this section we are going to guide you through some different basic scenarios how you might want to use our widgets in your application. In case the documented guide is misleading or confusing, 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.
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.
lead lead(s) are potential customers on a client's website and you may use our APIs to gather information about them.

What are widgets

Widgets are stand-alone web pages that can be accessed using URL links. They provide some basic functionality of Giosg. For example, you may use a chat widget to easily embed a chat to your app, or link to it from your native app. This way the developer doesn't have to implement all on own in native application if a direct link to for chatting is enough. These endpoints are aimed to be LTS and will receive deprecation notifications long before dropping support for them.

Info

Widget URLs are meant to be opened in browser, web view, or an iframe! In contrast to HTTP API endpoints, they will always return HTML page responses instead of JSON.

Visitor chat widget

Visitor chat widget provides an easy way for anonymous users to initiate a chat conversation with your chat agents. For example you might need a link for starting a chat session in a specific organization's room without setting up giosg script on your website.

Example visitor side chat widget URL

1
https://service.giosg.com/widgets/v1/public/orgs/899042d4-4aaf-11e7-899c-f45c89c72de3/rooms/9d25ef9d-26ed-40e8-8d74-a6a17039195d/chat

You can start a chat as a visitor in organization's room by redirecting them to the following address in the browser:

https://service.giosg.com/widgets/v1/public/orgs/<organization_id>/rooms/<room_id>/chat

This widget endpoint initiates Chat. <organization_id> is the ID of your organization. This can be viewed from the Account settings. <room_id> is the ID of the room in which the chat will take place.

You can find out your organization ID from your account information page at the "Account UUID" field. You can find the room ID by selecting the room from the room settings page at the "Room UUID" field.

The room ID in the URL must be one of your organization's rooms or shared to it, otherwise the chat link won't work and 404 error response is returned.

This endpoint takes the following GET-parameters:

Parameter name Description
exp The date/time when the URL stops working. You may use this parameter to prevent visitors re-using a signed URL after some time period. The value must be an Unix timestamp, in seconds.
alg If you are using a signature, then this must be one of the supported signing algorithms. Otherwise it should be omitted.
sig Signature for the information in the URL. See below how this signature should be created.
var.xxx Sets the visitor variable named xxx to the given value. You may define any number of variables as their own parameters. For example, to add a parameter name with value John Smith, you can add var.name=John%20Smith parameter to the URL.

Warning

Remember to URL-encode any URL parameter names and values that contain special characters! In most programming languages there are standard functions for this purpose!

Securing chat widget URL

Success

You can prevent the widget chat page to be used unless linked from your own app or website.

This can be done by enabling the setting that requires signed URLs (see below) containing the sig and alg parameters. If enabled, the chat widget page will show an error page instead if attempted to access using an unsigned URL. This is especially useful when used together with the expiration time parameter (exp).

To enforce signatures for a specific room, do the following steps:

  1. Go to your account's room settings
  2. Select the room that you are using for your widget
  3. Ensure that "Always require signatures for visitor data and chat URLs" checkbox is checked
  4. Click "Save changes"

Your account must also contain at least one signing key. To create one for you web/mobile app:

  1. Go to your account's Signing key settings
  2. Click "Generate new signing key"
  3. Copy the generated key and use it in your app as described below.

Signing chat widget URLs

Example base URL when organization ID is b9690e9c-43bb-11e8-84ba-6c4008c08dfe and room ID is b96b2099-43bb-11e8-8011-6c4008c08dfe, the chosen algorithm is sha1, and the chat expires 2018-04-19 at 11:27 (UTC).

1
https://service.giosg.com/widgets/v1/public/orgs/b9690e9c-43bb-11e8-84ba-6c4008c08dfe/rooms/b96b2099-43bb-11e8-8011-6c4008c08dfe/chat?exp=1524133626&alg=sha1

Example string to hash when the signing key is 12b3b0a95ae4609e578e1a70b62a00c5591f002c

1
https://service.giosg.com/widgets/v1/public/orgs/b9690e9c-43bb-11e8-84ba-6c4008c08dfe/rooms/b96b2099-43bb-11e8-8011-6c4008c08dfe/chat?exp=1524133626&alg=sha112b3b0a95ae4609e578e1a70b62a00c5591f002c

Example hexadecimal hash got from the above string using the selected SHA1 algorithm

1
c7d3de8daba3b84d4177faab829a0cdb99456562

Example final, signed cat widget URL

1
https://service.giosg.com/widgets/v1/public/orgs/b9690e9c-43bb-11e8-84ba-6c4008c08dfe/rooms/b96b2099-43bb-11e8-8011-6c4008c08dfe/chat?exp=1524133626&alg=sha1&sig=c7d3de8daba3b84d4177faab829a0cdb99456562

If you want to secure your chat widget acces, then in your app or website, you must implement functionality that signs the URL. Your code should perform the following steps:

  1. Build your full chat widget URL, including the protocol, host, path, alg parameter, and all other query parameters except sig parameter.
  2. Ensure that the path includes actual room ID and organization ID, and all the query parameters should be correctly URL-encoded at this point. Note that the order of query parameters matter!
  3. Concatenate the signing key after the URL string
  4. Calculate the checksum using your selected algorithm (as defined by alg parameter).
  5. Get the hexadecimal representation of the signature
  6. Append the hexadecimal signature as the sig query parameter to the URL as the last parameter.