NAV

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:

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:

Steps for app development

To develop an app, the following steps are required:

App interaction methods

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

Configuring apps

Creating an app

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

Settingsgiosg appsCreate 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:

Editing an app

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

Settingsgiosg apps → Find your app from the list → Owner toolsEdit

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:

Settingsgiosg apps → Find your app from the list → Owner toolsEditDelete 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.

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
Run on background when chat starts a new chat starts giosg servers
Run on background when chat ends a chat ends permanently giosg servers
Run when chat window is opened a chat window is opened user’s browser (AJAX)
Run when chat window is closed a chat window is closed user’s browser (AJAX)
Run when chat window is focused a chat window is focused user’s browser (AJAX)
Run on background when console loads giosg console UI is loaded for a user user’s browser (AJAX)
Run manually from chat dialog selected from chat window web page in an iframe
Run manually from top navigation selected from giosg UI top navigation bar web page in an iframe
Run when clicking the “Setup” link from “Installed apps” a “Setup” button is clicked in the app listing UI web page in a new browser tab

Trigger requests

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

GET https://myappp.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.

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

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”.

TODO: Screenshot here showing where the app secret can be found!

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:

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.

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”.

For simple UI-based apps using just triggers, bot users provide no additional benefit and and this setting should be disabled.

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:

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.

Using the bot users is done by reacting to webhook notifications. Therefore, if you enable bot users you most likely also need to define at least one webhook for your app. Reacting to webhooks as a bot user is described later in this documentation!

These bot user only have same permissions as normal users. They do not have any management permissions (reports, settings, or users). This is to provide secure installation for the application installer organization without any fear of the bot user making drastic changes.

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.

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.

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 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:

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.

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>

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!

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: Settingsgiosg apps → Find your app from the list → Owner toolsWebhook 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.

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!

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:

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.