Giosg Apps

Developing apps

giosg apps allows the development of 3rd-party applications on giosg platform. Apps can be also be shared and installed on other giosg accounts. Some examples of apps are:

• chatbots
• UI components embedded to giosg UI (similar to canvas apps in Facebook)
• integrations to external systems

Apps can use the giosg HTTP API to get and change the information in the giosg system. They can, for example, fetch chats, chat messages or leads, send new chat messages as a bot user, or attach additional information to visitors.

If you are interested in developing any kind of apps to giosg, then you are on the right page! After you have read and understood this, you may continue with the following pages:

• A guide to developing chatbots
• HTTP API reference

Steps for app development

To develop an app, the following steps are required:

• Get a giosg account. If you don't already have one, please contact us in the chat, or email us at support@giosg.com if you need any help with your account.
• Develop a web server application. It should be able to respond to HTTP requests. Depending on your use case, giosg will either redirect users to a web page hosted by your server, and/or make server-to-server HTTP requests to your server (webhooks).
• Configure your app. This is done to your giosg account so that the giosg system knows how to interact with your app.
• Install the app. The app can be installed to your organization's account, or it can be shared to your partner organizations allowing them to install it. The app can only be used after it has been installed.

App interaction methods

There are two kinds of interactions which the giosg system uses to communicate with your app. You can use either one of them, or both of them, depending on your use case:

• Webhooks provide server-to-server HTTP requests delivering information about almost any change in the giosg system. Your app can then react to these changes in any way it likes, typically making some API request back to the giosg system. For example, the chatbot receives a webhook about a new chat message, and the bot server reacts by sending back a response to that message.
• Triggers enable your app to be used directly from the user's browser client. You can choose one or more trigger conditions from the options. Depending on the chosen conditions, your app may be…
• embedded as an HTML page into an iframe
• opened as a new web page in the browser
• requested as an Ajax request from giosg UI
• requested with a server-to-server HTTP request, similar to webhooks

Configuring apps

Creating an app

To create a new app, the first step is to log in to giosg and navigate to:

Settings → giosg apps → Create new app

Note that creating or updating the apps can also be done programmatically with our app APIs.

When configuring an app, the following fields are required:

Field	Description
Name	Name of the app as shown to users. The name is used e.g. in the app listings, and when launching the app. The maximum length for this is 75 characters.
Description	A brief description what the app does and what purpose it does cover.
Terms of Service URL	A link to your Terms of Service page that your app users will be provided. They need to accept these Terms of Service in order to install this app. SSL is not required but highly recommended for this URL.
Privacy Policy URL	A link to your Privacy Policy page that your app users will be provided. The page should describe how your app processes and stores their data. SSL is not required but highly recommended for this URL.

Also, we recommend to upload an icon for your app that is shown to the users. The icon should be a square JPEG, PNG, or GIF image. The recommended size is 300 x 300 px. Note that in most contexts the icon will be shown as a circle.

In addition to these basic configuration settings, the following sections exist. They are used to define how the giosg system will interact with your app, and how it will be published to your partner organizations. These sections are described in more detail in the following sections:

• Triggers
• Bot users
• Sharing apps
• Webhooks

Editing an app

After the app has been created, you can edit its properties and configuration later from:

Settings → giosg apps → Find your app from the list → Owner tools → Edit

You can also edit triggers, bot users, sharing apps, and webhooks even while the app is already installed to organizations.

Deleting an app

You can permanently remove your app, disabling all of its usage from:

Settings → giosg apps → Find your app from the list → Owner tools → Edit → Delete app → Confirm the deletion

When deleting app, all existing installations will be removed as well. Also, all webhooks, bot users related to this app are removed and can no longer be used.

Apps can also be deleted programmatically with using our API for deleting an owned app.

Permissions

Permissions can be defined for the app for two reasons:

1. The app may need permissions for listening webhooks
2. If the app requires a bot user, the selected permissions are given as user permissions for the bot user

When installing the app, the installer accepts that these permissions are given for the app.

There are three different permission scopes:

Scope	Description
reports	Ability to read organization chats and reports
settings	Ability to modify organization settings
users	Ability to create/modify/delete organization users and teams

You can check which permission scopes are required for each API from this cheat sheet

Note

If your app is using OAuth2 Implicit flow or Authorization Code Grant Flow for authentication, all users may be able to authenticate to your app despite their permissions. In that case, if your app is using APIs that require permission scopes the user does not have, 403 responses are returned.

Permissions can also be modified programmatically with using our API for updating an owned app.

Triggers

Triggers are mainly used for apps that are embedded to the UI as web pages, in an iframe. They are also used in some situations where the app is notified directly from the user's browser when certain events occur.

App triggers are HTTP requests made to your servers when certain conditions are met. In all situations, the request is made to the URL you define in this UI, but the parameters depend on the condition.

Using triggers is optional. Typically, if you are implementing a chatbot or other server-focused app, it is recommended to use webhooks instead!

If you select to use this then "Application trigger URL" has to be provided, starting with https:// since only secure URLs are permitted. You also need to define which conditions should trigger the requests.

Trigger conditions

Here's the full list of supported trigger conditions, and how they make requests to your app:

Condition	Triggered when…	Origin of the request	type
Run on background when chat starts	a new chat starts	giosg servers	chat_start
Run on background when chat ends	a chat ends permanently	giosg servers	chat_end
Run on background when chat with visitor messages ends	a chat ends permanently and has visitor messages	giosg servers	chat_end_with_msgs
Run when chat window is opened	a chat window is opened	user's browser (AJAX)	chat_open
Run when chat window is closed	a chat window is closed	user's browser (AJAX)	chat_close
Run when chat window is focused	a chat window is focused	user's browser (AJAX)	chat_focus
Run on background when console loads	giosg console UI is loaded for a user	user's browser (AJAX)	console_load
Run manually from chat dialog	selected from chat window	web page in an iframe	manual_dialog
Run manually from top navigation	selected from giosg UI top navigation bar	web page in an iframe	manual_nav
Run when clicking the "Setup" link from "Installed apps"	a "Setup" button is clicked	web page in a new browser tab	setup
Run when the app is installed	app is installed to any organization	web page redirection in a browser	install
Run when the app is uninstalled	app is uninstalled by any organization	giosg servers	uninstall

Trigger requests

Example of a trigger request to the app server when your configured trigger URL is https://myapp.com/app.html

GET https://myapp.com/app.html?type=chat_start&data=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb21pY191cmwiOiJodHRwOi8veGtjZC5jb20vMTM2MC8ifQ.BsjBt9a9imoj9P5_7aIAe5nuhPd5jb8HGvAJKPCwm6A&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjb21pY191cmwiOiJodHRwOi8veGtjZC5jb20vMTM2MC8ifQ.BsjBt9a9imoj9P5_7aIAe5nuhPd5jb8HG

When any of the chosen conditions are triggered, an HTTP request is made to the configured URL (using the GET HTTP method), and the following query parameters are added to the URL:

Parameter	Type	Description
type	string	Type of the trigger condition that caused this request. See the list of supported trigger conditions for the possible values.
data	JWT	A JSON web token signed with the app secret. This contains data that app can use, see below.
token	JWT	An access token your app needs to use when using giosg HTTP API endpoints.
redirect_uri	URL	Only available with type install! When the app is installed and the installer user is redirected to your web page, then you should redirect the user back to this specific URL once the installation is complete!

Because all the trigger conditions are requested to the same base URL, you can use the type parameter if you are using more than one of them and want to separate them from each other.

You can find information about the triggering context by decoding the JSON Web token from the data parameter. How this is done depends on your programming language and available libraries, but most languages have some kind of standard libraries for this purpose. The decoded token contains an object with the following attributes:

Field	Type	Description
sub	string	Always service.giosg.com.
exp	timestamp	Token expiration timestamp. Automatically used by most JWT implementations to make sure that token is not expired
user_id	UUID	ID of the current user or null if not applicable
org_id	UUID	ID of the organization/company where the user_id belongs to
chat_id	UUID	ID of the related chat, if any, otherwise null
visitor_id	string	ID of the related visitor, if available, otherwise null
inst_id	UUID	ID of the app instance/installation.
app_id	UUID	ID of the app
app_user_id	UUID	ID of any related bot user, or null if no such user was created on app installation
app_user_code	string	An "Authorization Code" for getting an access token for your bot user, if any, otherwise null. More details below.

You should verify the token by using the app secret of your app, to ensure that the data is valid and originates from the giosg system, and not from some malicious party.

You can find your app secret by finding your app from the listing, clicking "Edit" and then "Show app secret".

If your app has a bot user installed to the user's organization, the data also includes information of the bot user, including an "Authorization Code" that you can exchange to a persistent access token for that bot user, so that you can perform actions any time as the bot user from your servers!

Please note the difference between the user_id and app_user_id: the first identifies an actual user who is currently interacting with your app, but the app_user_id is a bot user that is created to that specific organization (org_id).

Using HTTP API from app triggers

Example: The token parameter is abcdefghiklmopqrstuvwxyz0213456789 and the app secret is axyz0213456bcdelmopqrstuvw789fghik. In this case, the following HTTP header needs to be included to the API requests:

Authorization: GIOSGAPP abcdefghiklmopqrstuvwxyz0213456789 axyz0213456bcdelmopqrstuvw789fghik

Apps are likely to perform some actions after the app has been triggered, by using the giosg HTTP API. For example:

• When app server is notified, the app would like to perform requests to the API
• When opened in an iframe, the app would like to make AJAX requests to their server, which will then perform requests to the API

The API requests are done as described in HTTP API usage documentation, but the authentication is done by using the token parameter in the request as well as the app secret! The request needs to include the following HTTP header:

Authorization: GIOSGAPP <token> <app_secret>

The <token> needs to be replaced with the token parameter passed to the trigger URL. The <app_secret> needs to be replaced with the app secret of your app, which you can find from your app settings, as described earlier.

Warning

Never make your app secret public! You should not make the API requests directly from a web client (e.g. from the iframe) with AJAX, as you would need to expose the app secret to your users. Instead, only perform the API requests from your servers, where your app secrets are stored securely.

Bot users

You can choose whether or not your app will be installed with a bot user. This is essential for server-side applications that will act on their own, e.g. chatbots. For these kind of apps, you should enable the setting "Automatically create a bot user on installation".

Bot users are techically very similar to normal users. They have names, profile pictures, they can chat and they can be included to routers. However, they differ from normal users with the following properties:

• Bot users are controlled programmatically by the app provider, not by a real human being
• Bot users do not have an email address nor password, and therefore they cannot log in a traditional sense
• Bot users optionally have user permissions (reports, settings, users), these can be enabled during app creation
• Bot users are created when an app is installed, and deleted when the app is uninstalled (or otherwise removed)

For example, after installing an app, the installer can then edit the details of the bot user and choose where the chatbot is allowed to chat. On the other hand, when the app provider makes HTTP requests to giosg API, they authenticate themselves as the bot user, which gives them limited access to the organization who installed the app.

When enabling a bot user, you need to fill the following default properties for every created bot user.

Field	Description
First name	First name for the bot, as shown to other users
Last name	Last name for the bot, as shown to other users
Chat display name (alias)	Display name for the bot when in chat conversation, as shown to visitors

NOTE: Note that these are mere default values. The installer may change them from their default values.

Info

Please note that a new bot user will be created whenever your app is installed to any organization, and your app is responsible for managing each of them! In other words this means that you need to be able to handle as many bot users as there are app installations.

Controlling bot users

There are two primary ways of using bot users:

• Reacting to webhook notifications. This is an easy way as you get a temporary access token with each webhook to perform actions as the bot user. You should define at least one webhook for your app.
• Perform actions with a persistent access token. This enables you to perform actions whenever you want in the name of a bot user, but you need to first get an "Authorization Code", exchange it to an access token, and store it to your server databases.

Persistent access tokens for bot users

For very simple bots it might be enough to just react to webhooks. In those cases you can, in theory, implement a stateless bot server without any database.

However, in many cases you need to perform actions as a bot even when it is not a direct reaction to a notification from a giosg system. For example, your chatbot may have an internal logic when it wants to be online, and change this state whenever it wishes. In these cases, you need a persistent access token for a bot user.

There are some important aspects for persistent access tokens:

• Your bot has a chance to get the access token whenever an app is installed. Your bot must retrieve and store this token, e.g. to its database, for any further use.
• Because bot users are per installation (not per app), so are bot access tokens. In other words, you will get a different access token each time your app is installed to a new organization and a new bot user is created. You must therefore be able to store multiple access tokens, and choose the one depending on which bot user you want to control.
• Persistent tokens do not expire, but they will stop working if the app is uninstalled or the access is otherwise revoked
• Persistent access tokens must always kept private to your servers, and never expose to any client-side code, e.g. used in client-side JavaScript or in compiled mobile apps. Never hard-code the tokens to any publicly available code either.

After enabling bot users for your app, and after an organization has installed the app, you will get the app_user_id and app_user_code included in all Trigger requests to your servers.

Even though this code is included in every trigger request, you probably want to enable "Run when the app is installed" (install) trigger condition for your app! When enabled, the installing user's browser is redirected to your web page.

Info

For the best user experience, when the user is redirected to your app's web page on installation, you should redirect the user back to giosg when you are done handling the new installation! Please use the redirect_uri parameter.

When handing the trigger request, you need to parse the "Authorization Code" from the app_user_code that is included in the JSON Web Token in the data parameter. You then need to exchange it to a persistent access token. This is done by performing a Token request, as specified by OAuth2 / OpenID Connect:

POST https://service.giosg.com/identity/token

You need to provide the following parameters, encoded in application/x-www-form-urlencoded:

Parameter	Required	Description
grant_type	required	This must be exactly authorization_code
code	required	This is the "Authorization Code" from app_user_code.
client_id	required	The ID of your Giosg App as registered to giosg
client_secret	required	The secret string generated to your app and only known by your app servers

As a response you will get a JSON response with the following attributes:

Attribute	Description
access_token	The persistent access token for the user bot that you need to store securely and use with the API requests.
token_type	Tells which keyword you must use in the Authorization header of your following API requests as a prefix for the access token. Currently, this value is always Token.
user_id	ID of the bot user to which the access token grants an access
organization_id	ID of the organization in which the bot is installed
app_id	ID of your app, matching the client_id that was defined as a parameter

For more details about the Token request and responses see the Authentication documentation!

Example API request header with a persistent access token

Authorization: Token 8ajjx980937h8fshxnba1700dshjfncm

After getting the access_token, you need to store it securely so that you can easily find it by the bot user's ID (or by the organization ID). You then use this access token with API requests in the same way that you would use "API tokens".

Info

Note that you need to use Token keyword in your Authorization header with persistent tokens, not Bearer nor GIOSGAPP.

Sharing apps

Apps can be shared to your partner organizations. This will make your app available for installation for them and will show in their giosg apps listing. You may select to share your app to your whole partner network or only for selected partner organizations. If your app is only for your own organization, no sharing is needed.

Note

that in order to share your app to another organization, you need to form a partnership between the two organizations via Network.

Notice

Currently the only way to create partnership between companies is by requesting it from support@giosg.com.

Apps can be shared programmatically by using our API for sharing an owned app and unshared by using our API for unsharing owned app from partner organization.

App sharing options:

Selection	Description
Private - No sharing	App is only available to your organization.
Public - Whole partner network	App is available to your whole partner network.
Public - Selected organizations	App is available to selected partner organizations.

If you have enabled sharing for your app, you can also copy a link to your app's installation page, which you can deliver to your partners, e.g. by email. Please note that the link only works for users who have logged in to your partner organizations' accounts.

Webhooks

If you want your server-side app to be notified by HTTP requests when there are changes in the system, you should define at least one webhook. You need to enter the URL that will be requested, as well as which changes you want to receive as channel patterns. Note that giosg only accepts secure URLs as webhook endpoints starting with https://.

Webhooks can also be created and edited programmatically by using our API for creating a webhook for owned app or the API for updating owned app's webhook.

The webhook's required fields:

Field	Description
Endpoint URL	URL to which webhook should be sent to.
Subscription channels	List of channel patterns from which you want to get webhook notifications.

The webhook channel subscription's required fields:

Field	Description
Channel pattern	Channel pattern describing what changes you want to receive, see below.
Subscribe to additions	Whether a webhook should be sent when a new item is added to channel pattern's collection.
Subscribe to changes	Whether a webhook should be sent when there has been changes in channel pattern's collection.
Subscribe to removals	Whether a webhook should be sent when an item is removed from channel pattern's collection.

Webhook channels

giosg system broadcasts real-time changes to "channels". You can choose about what changes you want to receive notifications by defining channel patterns to your webhooks, as described below.

Channels in giosg system are equal to the URL paths of API endpoints! Here are some examples:

Example channel	What it represents
/api/v5/orgs/f9a3c249-736e-4361-b2f5-0e48a1e5795c	Represents changes to the specific organization
/api/v5/orgs/f9a3c249-736e-4361-b2f5-0e48a1e5795c/users	Represents changes to any user of the specific organization
/api/v5/users/4f63a5bd-7f9b-42ce-8764-965f30806534/chats	Represents changes to any chat of the specific user

You can use the HTTP API reference documentation as a catalog for the supported channels. Almost all the endpoints support webhook notifications, with some exceptions.

To receive notifications about some set of channels, you have to define one or more channel pattern to your webhooks. Here are the most used examples:

Example channel pattern	Descripition
/api/v5/users/{user_id}/routed_chats	Matches any change in any of the chats routed to the bot user
/api/v5/users/{user_id}/pending_chats	Matches any change in the pending chats available to the bot user
/api/v5/users/{user_id}/routed_chats/*/messages	Matches any change in chat messages in any of the chats routed to the bot user
/api/v5/users/{user_id}/chats/*/messages	Matches any change in chat messages in any of the chats to which the bot user has been joined earlier
/api/v5/users/{user_id}/rooms	Matches any change in the rooms in which the bot is allowed to chat
/api/v5/orgs/{organization_id}/teams	Matches any changes in any team belonging to the organization to which the app has been installed

The {user_id} and {organization_id} placeholders will automatically match the bot user or the organization to which your app has been installed! You don't have to know the exact ID of the bot user or the organization. The system will replace these placeholders automatically with actual IDs.

Important

The {user_id} placeholder only works if you have enabled bot users for your app, which is what you most likely want when using webhooks! The {organization_id} placeholder can be used even without bot users, but in this case you are not able to react to webhooks.

As you noticed in the examples, you may use the asterisk character (*) in the pattern to match any sub-resource ID in the URL pattern, e.g. chat IDs.

NOTE: The channels and patterns always start with a trailing slash and never end with a trailing slash. Channel do not include any URL query parameters, such as filtering or ordering criteria.

Also note that for obvious security reasons, all the channel patterns must start with one of the following strings:

• /api/v5/users/{user_id}/
• /api/v5/orgs/{organization_id}/

This ensures that you are only allowed to receive notifications about changes that are related to the organization (or its bot user) who has installed your app.

Webhook requests

Example webhook request object's JSON, when notifying about a new chat being routed to the user

{
  "channel": "/api/v5/users/dabfd452-cbc0-4eff-aaac-f4e125db0fe4/routed_chats",
  "action": "added",
  "resource_id": "e1549f4d-d2a6-4efb-b64c-e977b0a5ba96",
  "app_user_auth": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.JsxySWmKqmsd7BTXRi3JnmkFS4kJJTU_NYUN2NcfsP8",
    "token_type": "Bearer",
    "expires_in": 300,
    "user_id": "dabfd452-cbc0-4eff-aaac-f4e125db0fe4",
    "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7"
  },
  "resource": {
    "id": "e1549f4d-d2a6-4efb-b64c-e977b0a5ba96",
    "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"
  }
}

After you have defined the webhooks, and your app has been installed by at least one organization, your servers will start receiving HTTP POST requests to the URL you defined. The notification details are included in the request payload as JSON. Therefore, the Content-Type header of the request is always application/json.

The request payload is a JSON-encoded object with the following attributes:

Attribute	Description
channel	Channel of this notification, which matches one of the patterns you defined
action	Describes what kind of change occurred, either added, changed or removed
resource_id	Identifier of the resource within the collection related to the channel. For example, if you received a notification about a new chat, then this is the ID of the chat.
resource	If action is added, then this is the complete representation (with all attributes) of the resource being added. If action is changed, then this contains the changed attributes of the resources. If action is removed, then this attribute is not available.
app_user_auth	If you have enabled bot users for your app, then this object contains the details of the bot user, e.g. its ID (user_id) and the organization (organization_id). If also contains authorization details for reacting to the webhook.

When configuring a webhook channel pattern, you were allowed to choose which action types you want to receive. It depends on these settings whether or not you receive the different action types:

Action	Setting name	Description
added	"Subscribe to additions"	Notify if the resource did not previously exist in the collection (related to the channel), but now it does
changes	"Subscribe to changes"	Notify if one or more resource attributes have been changed from their previous values
removed	"Subscribe to removals"	Notify if the resource no longer exists in the collection (related to the channel)

Note that "additions" and "removals" indicate the presence of the resource in the collection related to the channel. For example, if you receive a added notification from a channel /api/v5/users/579f3072-e6b8-47a3-b67e-2c4739e2c8d3/pending_chats, it means that a chat has become pending or just became available to you. The chat itself may have existed earlier but was not part of this collection. Similarly, if you receive a removed notification from a the same channel, it means that the chat is no longer pending or not available to you, but the chat itself probably still exists. It may actually be re-added to this collection later at some point.

Important

Your server must respond to a webhook request in 5 seconds! If your server takes longer time to respond, the giosg system will assume that there are issues with the connection to your servers. This is likely to cause problems with the interaction with your app.

If your server is likely to take a longer than 5 seconds to process the request, e.g. by making a lot of sequential API requests, it should return a response to the webhook request first, and then continue performing other tasks probably on some background process. This might not be trivial with the most web frameworks, and it is up to you which technology you use for this purpose. As one example, if you are using some Python-based server-side solution (e.g. the Django framework), then you could use Celery asynchronous task queue.

Reacting to webhooks

Example authentication information in the app_user_auth attribute:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.JsxySWmKqmsd7BTXRi3JnmkFS4kJJTU_NYUN2NcfsP8",
  "token_type": "Bearer",
  "expires_in": 300,
  "user_id": "dabfd452-cbc0-4eff-aaac-f4e125db0fe4",
  "organization_id": "7f9e9580-095b-42c7-838c-c04e667b26f7"
}

With this information, you should use the following HTTP header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmb28iOiJiYXIifQ.JsxySWmKqmsd7BTXRi3JnmkFS4kJJTU_NYUN2NcfsP8

When you receive a webhook notification, you probably want to perform some actions or fetch some additional information using giosg HTTP API. In order to make requests to these API endpoints, you need to authenticate yourself.

If you have enabled bot users for your app, the webhook notification request will contain authentication information that you can use to authorize requests to the HTTP API!

This information is available in the app_user_auth attribute in the request payload object, and it contains the following attributes:

Attribute	Description
access_token	A token that you can use to authorize API requests shortly after receiving the notification
token_type	A keyword that you need to use in the Authorization HTTP header, i.e. Bearer
expires_in	How many seconds the token can be used before it expires
user_id	ID of the bot user belonging to the organization which have installed your app
organization_id	ID of the organization which have installed your app

To authorize the API requests, get the values of token_type and access_token, separate them with a single whitespace, and use the result as a value for the Authorization HTTP header in the request:

Authorization: <token_type> <access_token>

Warning

IMPORTANT: The access tokens can be used only a short amount of time after receiving the webhook! Currently, they are valid for 5 minutes. There should be no need to store them in a long-term storage, as you will always receive a fresh token with the next webhook! The whole idea of these tokens is to "react" to the webhooks after a fairly short time.

REMEMBER: Even though the access tokens are valid for several minutes, your server must respond to a webhook request in 5 seconds, as described earlier!

It is possible that your bot needs to perform actions in other cases than just by reacting to changes in giosg system. In this case, you need to receive and store a persistent access token for each of your bot users.

Troubleshooting webhooks

The giosg system keeps log of all webhook requests made to each app. You might find this log useful for troubleshooting issues with the webhooks of your app! Logs are stored for 7 days, and are then removed.

You can find the webhooks for the app that you have created from: Settings → giosg apps → Find your app from the list → Owner tools → Webhook logs

Whenever you feel that your app might not be notified correctly with webhooks, first check your app's webhook log! Then check this list for different issues and their possible reasons:

Entries are missing from the log:

This means that giosg has not even attempted to send webhooks to your server.

• Ensure that your app is installed to desired organizations. Webhooks only work for installations.
• Check your channel patterns. Webhooks are only delivered when changes to the matching patterns are broadcasted by the system. Check that the pattern format is correct, and that they match an existing API endpoint.
• Check that you have enabled at least one type of change to your webhook channel subscriptions: additions, changes, and/or removals. Webhooks only work if at least one of them is enabled.
• It's possible that organization who has installed the app has not added the bot user to any router. This might be the case if your channel pattern includes …/routed_chats/…. The installer organization must add your bot to one or more of their routers.

Log entries are marked as "failed":

This means that giosg has tried to send webhooks to your server, but the sending has failed. Check the "reason", "response status code" and "response body" of the log entries, as they will describe the reason for the failure!

• Check that you have entered a valid URL for your webhooks
• Check that your server is available from the public Internet
• Ensure that you have a valid and non-expired SSL certificate for your server! Webhooks are only sent with a secure connection.
• Check if your server responded with a 4XX or a 5XX response code. These usually indicate, that webhooks have been sent successfully, but your server failed to handle them correctly.
• Check if the error indicates a timeout. In this case, either your server cannot be reached (check the availability of your servers), or your server takes too long (over 5 seconds) to respond.

Log entries are marked as "successful":

The gisog system has successfully sent the webhooks to your system. You should check the functionality of your servers, e.g. by going through the server logs, or using some debugging tools.

Log entries are marked as "started" or "pending":

If a lot of entries show up as "started" or "pending", and they are more than a few minutes old, then this indicates a problem in giosg system! Please contact our support either on our chat or by emailing to support@giosg.com.

Using apps

Installing apps

You can list all the apps that are available to your organization from the giosg apps listing in your organization's Settings.

This list includes the apps that your organization has created itself, or any apps that has been made available to your organization. For example, your partners may have shared an app for you.

To install an app, click the "Install" button, and follow the instructions.

The installation page shows app's information e.g. name of the app and the app's owner organization. For some apps, you are also required to fill in some details for the bot user that the installation will create to your organization's account:

Field	Description
First name	First name for the bot.
Last name	Last name for the bot.
Chat display name	Display name (alias) for the bot when in chat conversation, as shown to visitors
Router	Router in which the bot is automatically added in the first router step.

There are default values for these provided by the app's owner organization.

You are also required to accept the app provider's Terms of Service and Privacy Policy. You can view them by clicking the links provided in app installation process.

Routing chats to the bot user

If the app you installed has a bot user that interacts with chats, you probably need to route chats to the bot. This is done by including the bot to one or more of your routers, which are in use in your rooms. You can select one router when installing an app, or later by editing your existing routers.

If you wish to use the bot in a specific room, you can just select the bot to be part of the router which is used in that room and vice versa if you wish to "deactivate" the bot, you can easily remove the bot from the router. This will ensure that the bot user will not get any chats routed to it and so cannot interact with them.

Setting up apps

Some app provide you a "Setup" link that you can use to set up some app-specific configuration. First navigate to giosg apps listing in your organization's Settings, and then find the "Setup" link for the app. Clicking this button will open a new browser tab that will navigate to the app provider's own setup page. The app may have some integration related settings such as managing etc. If the settings are not available, the app does not require any additional setup.

To enable a "Setup" link to your own app, enable the following trigger condition for your app: Run when clicking the "Setup" link from "Installed apps"

Uninstalling apps

If you wish to uninstall the app, then navigate to giosg apps listing in your organization's Settings. Find the app that you would like to uninstall, and click the "Uninstall" button. This will open a new uninstallation page with warnings what will happen during the uninstallation. After uninstalling the app will stop working, and may remove some permanently stored data (depending on the app). Any bot users will be deleted from your organization. The bot users will still remain in your reports.

Further reading

You can find more information for developing apps from the following pages:

• HTTP API reference, describing how to use giosg HTTP API and all the endpoints that are supported.
• A guide to developing chatbots, explaining in more detail the basic principles how apps should work when developing a bot interacting with chats.

Here are some example apps that you can use when you start building your own app. All of the apps are open source and can be used any way you wish.

• A demo chatbot for giosg
• An integration for sending chat to mail