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 | |
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:
- Go to your account's room settings
- Select the room that you are using for your widget
- Ensure that "Always require signatures for visitor data and chat URLs" checkbox is checked
- Click "Save changes"
Your account must also contain at least one signing key. To create one for you web/mobile app:
- Go to your account's Signing key settings
- Click "Generate new signing key"
- 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-6c4008c08dfeand room ID isb96b2099-43bb-11e8-8011-6c4008c08dfe, the chosen algorithm issha1, and the chat expires 2018-04-19 at 11:27 (UTC).
1 | |
Example string to hash when the signing key is 12b3b0a95ae4609e578e1a70b62a00c5591f002c
1 | |
Example hexadecimal hash got from the above string using the selected SHA1 algorithm
1 | |
Example final, signed cat widget URL
1 | |
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:
- Build your full chat widget URL, including the protocol, host, path,
algparameter, and all other query parameters exceptsigparameter. - 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!
- Concatenate the signing key after the URL string
- Calculate the checksum using your selected algorithm (as defined by
algparameter). - Get the hexadecimal representation of the signature
- Append the hexadecimal signature as the
sigquery parameter to the URL as the last parameter.