Apps API

Public apps

Public apps include giosg Apps from any organization that are made available for everyone. Public apps can be installed by any organization.

An app is considered "public" if these conditions are true:

• Their owner has set its is_available_to_anyone attribute to true
• The app has been approved by giosg to be public (TO BE IMPLEMENTED LATER)

A public app resource has the following attributes

Attribute	Type	Editable	Description
id	UUID	read-only	The ID of the app.
name	string	read-only	Name of the app.
description	string	read-only	Description for the app
owned_by_organization_id	UUID	read-only	The ID of the organization that the app belongs to.
owned_by_organization	object	read-only	The organization resource to which the app belongs to.
icon_asset_id	UUID	read-only	The ID of the icon asset that the app is using.
icon_asset	object	read-only	The icon asset resource that the app is using.
is_app_user_required	boolean	read-only	Whether the app requires a bot user for the installing organization. This is done automatically when the app is installed.
required_scopes	list of strings	read-only	List of permission scopes the app requires in order to work. The permissions are needed for listening webhooks and for bot user permissions. See list of different permission scopes.
installation_count	integer	read-only	How many installations of this app there are.
created_at	[date/time]	read-only	When the app was created.
updated_at	[date/time]	read-only	When the app was updated.

List all the public apps

Example request for listing public apps

GET https://service.giosg.com/api/v5/public_apps

{
  "next": "https://service.giosg.com/api/v5/public_apps?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "d8287ad2-7e07-44e3-b533-5a178cafecc1",
      "name": "Flappy giosg Balls",
      "description": "An awesome game!\nPlay it now!",
      "icon_asset_id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
      "icon_asset": {
        "id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
        "url": "https://giosg-chat-public-eu.s3.amazonaws.com/assets/1/4sBqqExlHlSmREGxmZLVt1QUwK2jtX.jpg",
        "width": 301,
        "height": 301
      },
      "is_app_user_required": false,
      "owned_by_organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
      "owned_by_organization": {
        "id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
        "name": "giosg.com"
      },
      "required_scopes": [],
      "installation_count": 0,
      "created_at": "2017-01-01T12:00:00.123Z",
      "updated_at": "2017-01-02T15:00:00.123Z"
    }
  ]
}

Get a paginated collection of public apps:

GET /api/v5/public_apps

This returns a paginated collection of app(s) which are public. The results are ordered by created_at, in a descending order.

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have settings permission

Retrieve a single public app

A single public app can be retrieved with:

GET /api/v5/public_apps/<app_id>

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have settings permission
• 404 if no public app is found with the given ID

Partner apps

Partner apps are apps that your partner organizations in your network have made available to the whole network. They can be installed by the organization.

An app is considered a "partner app" of the organization if these conditions are true:

• App owner has set its is_available_to_partners attribute to true
• The owner organization is a partner of the given organization

A partner app resource has the following attributes

Attribute	Type	Editable	Description
id	UUID	read-only	The ID of the app.
name	string	read-only	Name of the app.
description	string	read-only	Description for the app
owned_by_organization_id	UUID	read-only	The ID of the organization that the app belongs to.
owned_by_organization	object	read-only	The organization resource to which the app belongs to.
icon_asset_id	UUID	read-only	The ID of the icon asset that the app is using.
icon_asset	object	read-only	The icon asset resource that the app is using.
is_app_user_required	boolean	read-only	Whether the app requires a bot user for the installing organization. This is done automatically when the app is installed.
required_scopes	list of strings	read-only	List of permission scopes the app requires in order to work. The permissions are needed for listening webhooks and for bot user permissions. See list of different permission scopes.
installation_count	integer	read-only	How many installations of this app there are.
created_at	[date/time]	read-only	When the app was created.
updated_at	[date/time]	read-only	When the app was updated.

List all the partner apps

Example request for listing partner apps

GET https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/partner_apps

{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/partner_apps?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "d8287ad2-7e07-44e3-b533-5a178cafecc1",
      "name": "Flappy giosg Balls",
      "description": "An awesome game!\nPlay it now!",
      "icon_asset_id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
      "icon_asset": {
        "id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
        "url": "https://giosg-chat-public-eu.s3.amazonaws.com/assets/1/4sBqqExlHlSmREGxmZLVt1QUwK2jtX.jpg",
        "width": 301,
        "height": 301
      },
      "is_app_user_required": false,
      "owned_by_organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
      "owned_by_organization": {
        "id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
        "name": "giosg.com"
      },
      "required_scopes": [],
      "installation_count": 0,
      "created_at": "2017-01-01T12:00:00.123Z",
      "updated_at": "2017-01-02T15:00:00.123Z"
    }
  ]
}

Get a paginated collection of partner apps:

GET /api/v5/orgs/<organization_id>/partner_apps

This returns a paginated collection of app(s) which are shared by organization's partner. The results are ordered by created_at, in a descending order.

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have settings permission

Retrieve a single partner app

A single partner app can be retrieved with:

GET /api/v5/orgs/<organization_id>/partner_apps/<app_id>

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have settings permission
• 404 if no partner app is found with the given ID

Owned apps

When an organization creates a new app, it becomes an "owner" organization of that app and have the ultimate authority to the app and its installations. Apps created by an organization are therefore referred as owned apps. The owner organization can always install any of their owned apps.

An owned app resource has the following attributes:

Attribute	Type	Editable	Description
id	UUID	read-only	The ID of the app.
name	string	required	Name of the app.
description	string	required	Description for the app.
owned_by_organization_id	UUID	read-only	The ID of the organization that the app belongs to.
owned_by_organization	object	read-only	The organization resource to which the app belongs to.
icon_asset_id	UUID	optional	The ID of the icon asset that the app is using.
icon_asset	object	read-only	The icon asset resource that the app is using.
is_available_to_anyone	boolean	read-only	Whether the application is public for all organization's in giosg system. Currently only giosg can provide public applications.
is_available_to_partners	boolean	optional	Whether the application is public for your partner organizations. Can be set to true only if the organization has "App provider" feature(s).
is_app_user_required	boolean	required	Whether the app requires a bot user for the installing organization. This is done automatically when the app is installed.
app_user_default_first_name	string	optional	Default first name for the bot user. This is required if is_app_user_required is set as true. This field is nullable but blank string is not allowed.
app_user_default_last_name	string	optional	Default last name for the bot user. This is required if is_app_user_required is set as true. This field is nullable but blank string is not allowed.
app_user_default_alias	string	optional	Default alias for the bot user. This field is nullable but blank string is not allowed.
terms_of_service_url	string	required	URL for application's terms of service.
privacy_policy_url	string	required	URL for application's privacy policy.
trigger_url	string	optional	URL which is used whenever one of the given trigger_conditions match.
trigger_conditions	list of strings	optional	List of trigger conditions in string format. These are always sorted alphabetically. See supported trigger conditions below.
required_scopes	list of strings	optional	List of permission scopes the app requires in order to work. The permissions are needed for listening webhooks and for bot user permissions. See list of different permission scopes below.
allowed_redirect_uris	list of strings	optional	List of URLs where the app can redirect the app installer to. The URLs must start with https://
installation_count	integer	read-only	How many installations of this app there are.
created_at	[date/time]	read-only	When the app was created.
updated_at	[date/time]	read-only	When the app was updated.
created_by_user_id	UUID	read-only	ID of the user who created this app.
created_by_user	object	read-only	The user resource created this app.
updated_by_user_id	UUID	read-only	ID of the user who last updated this app.
updated_by_user	object	read-only	The user resource who last updated this app.
secret	string	read-only	The secret key of the app.

Note! Even if is_available_to_partners is set to false, app may still have app shares for partner organizations.

Supported trigger conditions

Here's the list of supported trigger conditions:

Condition	Description
chat_start	Run on background when chat starts.
chat_end	Run on background when chat ends.
chat_end_with_msgs	Run on background when chat with visitor messages ends.
chat_open	Run when chat window is opened.
chat_close	Run when chat window is closed.
chat_focus	Run when chat window is focused.
console_load	Run on background when console loads.
manual_dialog	Run manually from chat dialog.
manual_nav	Run manually from top navigation.
setup	Run when clicking the "Setup" link from "Installed apps".
install	Run when the app is installed to any new organization.
uninstall	Run when the app is uninstalled by any organization.

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

List apps owned by an organization

Example request for listing owned apps

GET https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps

{
  "next": "https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "d8287ad2-7e07-44e3-b533-5a178cafecc1",
      "name": "Flappy giosg Balls",
      "description": "An awesome game!\nPlay it now!",
      "icon_asset_id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
      "icon_asset": {
        "id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
        "url": "https://giosg-chat-public-eu.s3.amazonaws.com/assets/1/4sBqqExlHlSmREGxmZLVt1QUwK2jtX.jpg",
        "width": 301,
        "height": 301
      },
      "owned_by_organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
      "owned_by_organization": {
        "id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
        "name": "giosg.com"
      },
      "secret": "fb612fac0e6e4550b6c24d15ffa0d4b5",
      "is_available_to_anyone": false,
      "is_available_to_partners": false,
      "terms_of_service_url": "https://www.giosg.com/terms-of-service",
      "privacy_policy_url": "https://www.giosg.com/privacy-policy",
      "trigger_url": "https://ktkiiski.github.io/giosg-balls/?mode=app",
      "trigger_conditions": [
        "chat_start",
        "chat_end",
        "chat_end_with_msgs",
        "chat_open",
        "chat_close",
        "chat_focus",
        "console_load",
        "manual_dialog",
        "manual_nav",
        "setup"
      ],
      "allowed_redirect_uris": [
        "https://secure-url.com",
        "https://www.secure-url.com"
      ],
      "required_scopes": ["settings"],
      "is_app_user_required": false,
      "app_user_default_first_name": "Robotti",
      "app_user_default_last_name": "Ruttunen",
      "app_user_default_alias": "Chat bot",
      "installation_count": 0,
      "created_at": "2017-01-01T12:00:00.123Z",
      "created_by_user_id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
      "created_by_user": {
        "id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
        "first_name": "Kimmo",
        "last_name": "Kiiski",
        "full_name": "Kimmo Kiiski",
        "organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a"
      },
      "updated_at": "2017-01-02T15:00:00.123Z",
      "updated_by_user_id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
      "updated_by_user": {
        "id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
        "first_name": "Kimmo",
        "last_name": "Kiiski",
        "full_name": "Kimmo Kiiski",
        "organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a"
      }
    }
  ]
}

Get a paginated collection of organization's owned apps:

GET /api/v5/orgs/<organization_id>/owned_apps

This returns a paginated collection of app(s) which are owned by organization. The results are ordered by created_at, in a descending order.

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the organization
• 403 if you do not have settings permission

Create a new app for an organization

Example request for creating new owned app

POST https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps

Example request payload

{
  "name": "Flappy giosg Balls",
  "description": "An awesome game!\nPlay it now!",
  "icon_asset_id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
  "is_available_to_partners": false,
  "is_app_user_required": false,
  "terms_of_service_url": "https://www.giosg.com/terms-of-service",
  "privacy_policy_url": "https://www.giosg.com/privacy-policy",
  "trigger_url": "https://ktkiiski.github.io/giosg-balls/?mode=app",
  "trigger_conditions": [
    "chat_start",
    "chat_end",
    "chat_open",
    "chat_close",
    "chat_focus",
    "console_load",
    "manual_dialog",
    "manual_nav"
  ],
  "allowed_redirect_uris": ["https://secure-url.com"],
  "required_scopes": ["users"]
}

A new owned app can be created with:

POST /api/v5/orgs/<organization_id>/owned_apps

Note that it won't be automatically installed for your organization or any other organization.

This endpoint returns:

• 201 if the request was successful
• 400 if required attributes are missing from the request
• 400 if the request payload is in wrong format
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the organization
• 403 if you do not have settings permission
• 404 if no owned app is found with the given ID

Retrieve an app owned by an organization by the app's ID

A single owned app can be retrieved with:

GET /api/v5/orgs/<organization_id>/owned_apps/<app_id>

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the organization
• 403 if you do not have settings permission
• 404 if no owned app is found with the given ID

Update an app owned by an organization

A single owned app can be updated with:

PUT /api/v5/orgs/<organization_id>/owned_apps/<app_id>

OR

PATCH /api/v5/orgs/<organization_id>/owned_apps/<app_id>

Note that changing the publicity attributes to false will uninstall the app from all organizations for which you haven't shared the app. If you want to set your app private, you have to remove those shares.

This endpoint returns:

• 200 if the request was successful
• 400 if required attributes are missing from the request
• 400 if the request payload is in wrong format
• 401 if you are not authenticated
• 402 if the organization does not have "App provider" feature(s) when trying to update is_available_to_anyone or is_available_to_network to true
• 403 if you do not have active subscription
• 403 if you do not have access to the organization
• 403 if you do not have settings permission
• 404 if no owned app is found with the given ID

Delete an owned app

A single owned app can be deleted with:

DELETE /api/v5/orgs/<organization_id>/owned_apps/<app_id>

Note that deleting owned app will uninstall it from everyone.

This endpoint returns:

• 204 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the organization
• 403 if you do not have settings permission
• 404 if no owned app is found with the given ID

Installed apps

Apps that are installed for an organization, being "in effect" for the organization. Usually the apps are owned by some other organization, but the organization can of course install their own apps, in which case the owner organization equals to the one in the URL.

An installed app resource has the following attributes:

Attribute	Type	Editable	Description
id	UUID	read-only	The ID of the app.
name	string	read-only	Name of the app.
description	string	read-only	Description for the app
owned_by_organization_id	UUID	read-only	The ID of the organization that the app belongs to.
owned_by_organization	object	read-only	The organization resource to which the app belongs to.
icon_asset_id	UUID	read-only	The ID of the icon asset that the app is using.
icon_asset	object	read-only	The icon asset resource that the app is using.
is_app_user_required	boolean	read-only	Whether the app requires a bot user for the installing organization. This is done automatically when the app is installed.
trigger_conditions	list of strings	read-only	List of trigger conditions. These were defined under owned apps section.
installation_count	integer	read-only	How many installations of this app there are.
created_at	[date/time]	read-only	When the app was created.
updated_at	[date/time]	read-only	When the app was updated.

To add or remove installed apps, use app installations.

List all the installed apps

Example request for listing installed apps

GET https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/installed_apps

{
  "next": "https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/installed_apps?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "d8287ad2-7e07-44e3-b533-5a178cafecc1",
      "name": "Flappy giosg Balls",
      "description": "An awesome game!\nPlay it now!",
      "icon_asset_id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
      "icon_asset": {
        "id": "828299a7-2001-45e0-9e03-cf865ef0eb8a",
        "url": "https://giosg-chat-public-eu.s3.amazonaws.com/assets/1/4sBqqExlHlSmREGxmZLVt1QUwK2jtX.jpg",
        "width": 301,
        "height": 301
      },
      "is_app_user_required": false,
      "owned_by_organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
      "owned_by_organization": {
        "id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
        "name": "giosg.com"
      },
      "created_at": "2017-01-01T12:00:00.123Z",
      "updated_at": "2017-01-02T15:00:00.123Z",
      "trigger_conditions": ["chat_end_with_msgs", "chat_open"],
      "installation_count": 2
    }
  ]
}

Get a paginated collection of organization's installed apps:

GET /api/v5/orgs/<organization_id>/installed_apps

This returns a paginated collection of app(s) which are installed by organization. The results are ordered by created_at, in a descending order.

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the organization
• 403 if you do not have settings permission

Retrieve a single installed app

A single owned app can be retrieved with:

GET /api/v5/orgs/<organization_id>/installed_apps/<app_id>

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the organization
• 403 if you do not have settings permission
• 404 if no owned app is found with the given ID

App installations

When an app is activated, i.e. installed, to an organization, an app installation resource is created. The installation resource exists until the app is uninstalled. Installation resources are unique to the app and the organization, in other words, a single app can only be installed once to an organization, until uninstalled.

An app installation resource has the following attributes:

Attribute	Type	Editable	Description
id	UUID	read-only	The ID of the app installation.
organization_id	UUID	read-only	The ID of the organization that has installed the app.
organization	object	read-only	The organization resource to which the app.
app_id	UUID	read-only	The ID of the installed app.
app	object	read-only	The installed app resource that the app is using.
app_user_id	UUID	read-only	The ID of the app user.
app_user	object	read-only	The app user resource.
allowed_scopes	list of strings	read-only	Which permissions have been accepted for the app. This maps to app required_scopes (see permission scopes).
created_at	[date/time]	read-only	When the app installation was created.
updated_at	[date/time]	read-only	When the app installation was updated.

List all the app installations for an organization

Example request for listing app installations

GET https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/app_installations

{
  "next": "https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/app_installations?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "0ff6bd51-e08b-4952-bc1f-c350757040fa",
      "organization_id": "a019708a-7889-419d-87ee-6ae2be73e8d5",
      "organization": {
        "id": "a019708a-7889-419d-87ee-6ae2be73e8d5",
        "name": "Another Organization Ltd."
      },
      "app_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
      "app": {
        "name": "Flappy giosg Balls",
        "description": "My cool application",
        "owned_by_organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
        "owned_by_organization": {
          "id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
          "name": "giosg.com"
        },
        "is_app_user_required": true,
        "required_scopes": ["settings"],
        "installation_count": 102,
        "created_at": "2017-01-01T12:00:00.123Z",
        "updated_at": "2017-01-02T15:00:00.123Z"
      },
      "created_at": "2017-01-03T13:00:00.123Z",
      "updated_at": "2017-01-04T13:00:00.123Z",
      "app_user_id": "44a3300c-500f-4edf-853e-a3e9536db16c",
      "app_user": {
        "id": "44a3300c-500f-4edf-853e-a3e9536db16c",
        "first_name": "Bob",
        "last_name": "The Bot",
        "full_name": "Bob The Bot",
        "organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a"
      },
      "allowed_permissions": ["settings"]
    }
  ]
}

Get a paginated collection of organization's app installations:

GET /api/v5/orgs/<organization_id>/app_installations

This returns a paginated collection of organization's app installation(s). The results are ordered by created_at, in a descending order.

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the organization
• 403 if you do not have settings permission

Retrieve an app installation for an organization

A single app installation can be retrieved with:

GET /api/v5/orgs/<organization_id>/app_installations/<installation_id>

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the organization
• 403 if you do not have settings permission
• 404 if no app installation is found with the given ID

Owned app installations

Apps owned by your organization may be installed by you or any other organization. These installation will be available to your organization as owned app installations. Owned app installations only include resources that relate to apps provided by your organization.

An owned app installation resource has the following attributes:

Attribute	Type	Editable	Description
id	UUID	read-only	The ID of the app installation.
organization_id	UUID	read-only	The ID of the [organization] that has installed the app.
organization	object	read-only	The organization resource to which the app.
app_id	UUID	read-only	The ID of the installed app.
app	object	read-only	The installed app resource that the app is using.
app_user_id	UUID	read-only	The ID of the app user.
app_user	object	read-only	The app user resource.
allowed_scopes	list of strings	read-only	Which permissions have been accepted for the app. This maps to app required_scopes (see permission scopes).
created_at	[date/time]	read-only	When the app installation was created.
updated_at	[date/time]	read-only	When the app installation was updated.

List all the installations for an app owned by an organization

Example request for listing installations of one of your owned apps

GET https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps/4e961cde-79e1-4b46-813c-73996659926c/installations

{
  "next": "https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps/4e961cde-79e1-4b46-813c-73996659926c/installations?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "0ff6bd51-e08b-4952-bc1f-c350757040fa",
      "app_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
      "app": {
        "name": "Flappy giosg Balls",
        "description": "My cool application",
        "owned_by_organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
        "owned_by_organization": {
          "id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
          "name": "giosg.com"
        },
        "is_app_user_required": true,
        "required_scopes": ["settings", "users"],
        "installation_count": 102,
        "created_at": "2017-01-01T12:00:00.123Z",
        "updated_at": "2017-01-02T15:00:00.123Z"
      },
      "organization_id": "a019708a-7889-419d-87ee-6ae2be73e8d5",
      "organization": {
        "id": "a019708a-7889-419d-87ee-6ae2be73e8d5",
        "name": "giosg.com"
      },
      "created_at": "2017-01-03T13:00:00.123Z",
      "updated_at": "2017-01-04T13:00:00.123Z",
      "app_user_id": "44a3300c-500f-4edf-853e-a3e9536db16c",
      "app_user": {
        "id": "44a3300c-500f-4edf-853e-a3e9536db16c",
        "first_name": "Bob",
        "last_name": "The Bot",
        "full_name": "Bob The Bot",
        "organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a"
      },
      "allowed_scopes": ["settings", "users"]
    }
  ]
}

Get a paginated collection of organization's app installations:

GET /api/v5/orgs/<organization_id>/owned_apps/<app_id>/installations

This returns a paginated collection of organization's owned app's installation(s). The results are ordered by created_at, in a descending order.

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the app owner organization
• 403 if you do not have settings permission

Retrieve a single installation of an owned app to a single organization

A single owned app installation can be retrieved with:

GET /api/v5/orgs/<organization_id>/owned_apps/<app_id>/installations/<installation_id>

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the app owner organization
• 403 if you do not have settings permission
• 404 if no owned app installation is found with the given ID

Uninstall the app from another organization

Warning

This endpoint is not yet implemented! This documentation is a draft.

An owned app installation can be uninstalled with:

DELETE /api/v5/orgs/<organization_id>/owned_apps/<app_id>/installations/<installer_organization_id>

This endpoint returns:

• 204 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the app owner organization
• 403 if you do not have settings permission
• 404 if no owned app installation is found with the given ID

Installing apps

Your organization must have the giosg Apps feature enabled by giosg support. giosg Apps can be installed by navigating a user (who has the settings permissions) to the following address:

https://service.giosg.com/apps/<app_id>/install?next=<redirect_uri>

User is prompted to log in if they are not already. The user will be confirmed that the app with ID <app_id> will be installed to their organization. After installed successfully, the user will be redirected to the given URI <redirect_uri>.

NOTE: For now, the next URI can only be located at the origin https://service.giosg.com. Ability to redirect to external websites may be added in the future.

If the app requires an app user, the user will be prompted for the basic information for the app user to be created.

A successful installation will result in creating a app installation, adding the app to the organization's installed apps, and possibly creating an app user (initially without any additional permissions).

If required by the app (their is_app_user_required is true), installing an app creates an app user that belongs to the organization which installed the app.

By default, the app user has regular access to the organization, without any additional permissions. The organization users with users permissions can add additional permissions to the app user at User management if necessary.

To list all the app installations, including any app users created for them, see App installations.

App users

Apps whose is_app_user_required attribute is true are installed with a new app user. An app user is a user account usually controlled by a "machine", e.g. a web service. A typical example of an app user is a chat bot.

App users belong to the organization who installed the app. Therefore they have, by default, the regular access to the organization. However, app users can be controlled by the provider of the giosg App, as they are able to create API tokens on their behalf. For example, the web server of a chat bot provider may join chats and send messages as the chat bot "app user" that was created on installation.

App users are bound to app installations so you can fetch them by listing the installations of your owned apps. If there is no app user, the app_user attribute will be null.

Webhooks

You may define webhooks for your app that allow your server to receive real-time notifications about changes in the organization who have installed your app. For example, when implementing a chat bot, you most probably need to define webhooks for any chats and chat messages being sent to your servers, so that the bot can react to them.

A webhook describes an URL to which notifications will be sent with POST HTTP requests. To have any effect, the webhook should have at least one channel subscription to receive notifications.

IMPORTANT: It might take a short while for the changes in webhooks to take effect!

A webhook resource has the following attributes:

Attribute	Type	Editable	Description
id	UUID	read-only	The ID of the webhook.
organization_id	UUID	read-only	The ID of the organization that owns the webhook.
organization	object	read-only	The organization resource to which owns the webhook.
app_id	UUID	read-only	The ID of the app which uses this webhook.
app	object	read-only	The app resource that is using the webhook.
endpoint_url	string	required	URL to which the webhook is sent.
channel_subscriptions	list of objects	optional	List of channel subscriptions objects. See supported attributes below. Also please read more detailed section about webhook channel subscriptions.
created_at	[date/time]	read-only	When the webhook was created.
updated_at	[date/time]	read-only	When the webhook was updated.
created_by_user_id	UUID	read-only	ID of the user who created this webhook.
created_by_user	object	read-only	The user resource created this webhook.
updated_by_user_id	UUID	read-only	ID of the user who last updated this webhook.
updated_by_user	object	read-only	The user resource who last updated this webhook.

A webhook channel subscription resource has the following attributes:

Attribute	Type	Editable	Description
channel_pattern	string	required	The channel pattern i.e. basically some API endpoint in specific format. The format is explained better in webhook channel subscriptions section.
is_additions_subscribed	boolean	required	Whether a webhook is sent when new resource is added to the collection.
is_changes_subscribed	boolean	required	Whether a webhook is sent when resource changes happen for a item.
is_removals_subscribed	boolean	required	Whether a webhook is sent when a resource is removed from the collection.

List all webhooks for your app

Example request for listing webhooks

GET https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps/4e961cde-79e1-4b46-813c-73996659926c/webhooks

{
  "next": "https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps/4e961cde-79e1-4b46-813c-73996659926c/webhooks?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "8deb52f9-6824-4c84-96d4-1a3a4f3d88ad",
      "created_at": "2017-01-01T12:00:00.123Z",
      "updated_at": "2017-01-02T15:00:00.123Z",
      "created_by_user_id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
      "created_by_user": {
        "id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
        "first_name": "Kimmo",
        "last_name": "Kiiski",
        "full_name": "Kimmo Kiiski",
        "organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a"
      },
      "updated_by_user_id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
      "updated_by_user": {
        "id": "7c03e169-6e6a-4516-a5f1-57d84d56e4d1",
        "first_name": "Kimmo",
        "last_name": "Kiiski",
        "full_name": "Kimmo Kiiski",
        "organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a"
      },
      "app_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
      "app": {
        "name": "Flappy giosg Balls",
        "description": "My cool application",
        "owned_by_organization_id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
        "owned_by_organization": {
          "id": "f2238fae-2080-49bd-a4a5-8adef8b45b9a",
          "name": "giosg.com"
        },
        "is_app_user_required": false,
        "required_scopes": [],
        "installation_count": 0,
        "created_at": "2017-01-01T12:00:00.123Z",
        "updated_at": "2017-01-02T15:00:00.123Z"
      },
      "organization_id": "a019708a-7889-419d-87ee-6ae2be73e8d5",
      "organization": {
        "id": "a019708a-7889-419d-87ee-6ae2be73e8d5",
        "name": "giosg.com"
      },
      "endpoint_url": "https://www.example.com/messages",
      "channel_subscriptions": [
        {
          "channel_pattern": "/api/v5/users/{user_id}/chats/*/messages",
          "is_additions_subscribed": true,
          "is_changes_subscribed": false,
          "is_removals_subscribed": false
        }
      ]
    }
  ]
}

Get a paginated collection of organization's owned app's webhooks:

GET /api/v5/orgs/<organization_id>/owned_apps/<app_id>/webhooks

This returns a paginated collection of organization's owned app's webhook(s). The results are ordered by created_at, in a descending order.

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the app owner organization
• 403 if you do not have settings permission

Retrieve a single webhook of your app

A single webhook can be retrieved with:

GET /api/v5/orgs/<organization_id>/owned_apps/<app_id>/webhooks/<webhook_id>

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the app owner organization
• 403 if you do not have settings permission
• 404 if no owned app is found with the given ID

Create a new webhook to your app

Example request for creating new webhook

POST https://service.giosg.com/api/v5/orgs/f2238fae-2080-49bd-a4a5-8adef8b45b9a/owned_apps/f2238fae-2080-49bd-a4a5-8adef8b45b9a/webhooks

Example request payload

{
  "endpoint_url": "https://ktkiiski.github.io/giosg-balls/chat-messages",
  "channel_subscriptions": [
    {
      "channel_pattern": "/api/v5/users/{user_id}/chats/*/messages",
      "is_additions_subscribed": true,
      "is_changes_subscribed": false,
      "is_removals_subscribed": false
    }
  ]
}

A new webhook for owned app can be created with:

POST /api/v5/orgs/<organization_id>/owned_apps/<app_id>/webhooks

This endpoint returns:

• 201 if the request was successful
• 400 if required attributes are missing from the request
• 400 if the request payload is in wrong format
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the organization
• 403 if you do not have settings permission
• 404 if no owned app is found with the given ID

Update a single webhook of your app

A single webhook of owned app can be updated with:

PUT /api/v5/orgs/<organization_id>/owned_apps/<app_id>/webhooks/<webhook_id>

OR

PATCH /api/v5/orgs/<organization_id>/owned_apps/<app_id>/webhooks/<webhook_id>

This endpoint returns:

• 200 if the request was successful
• 400 if required attributes are missing from the request
• 400 if the request payload is in wrong format
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the organization
• 403 if you do not have settings permission
• 404 if no owned app's webhook is found with the given ID

Delete a webhook, including all of its channel subscriptions

An owned app's webhook can be deleted with:

DELETE /api/v5/orgs/<organization_id>/owned_apps/<app_id>/webhooks/<webhook_id>

This endpoint returns:

• 204 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the app owner organization
• 403 if you do not have settings permission
• 404 if no owned app's webhook is found with the given ID

Webhook channel subscriptions

Your webhooks need to contain at least one channel subscription defining which channels should be notified to the webhook URL. These are defined in the channel_subscriptions array, including objects containing channel_pattern attributes.

If you want to deliver notifications from different channels to different URLs, you should create separate webhooks with different endpoint_url attribute and the list of channel_subscriptions.

A webhook channel subscription channel_pattern must start with one of the following exact strings:

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

In these patterns, the {organization_id} placeholder will match the organization that have installed the app. The {user_id} placeholder will match the app user of the installation.

In addition to these, the following exact patterns are allowed:

• /api/v5/orgs/{app_organization_id}/owned_apps/{app_id}/installations

This will allow your servers get notifications about any new installs (is_additions_subscribed) or uninstalls (is_removals_subscribed) of your app! For example, when receiving an added message, you may then create an API token for the app user of the new installation, or perform any other setup.

IMPORTANT: This section will improve soon and will contain information how the App User's API Token will be provided for the app provider.

Webhook log entries

Each webhook request is logged. Log entries contain information about the request status and response. The entries are stored for 7 days.

Webhook log entry resource has the following attributes.

Attribute	Type	Editable	Description
created_at	datetime	read-only	When the log entry was created.
app_id	UUID	read-only	The ID of the app.
organization_id	UUID	read-only	The ID of the app owner organization.
webhook_id	UUID	read-only	The ID of the webhook.
endpoint_url	string	read-only	The request URL of the webhook.
action	string	read-only	Resource action, either added, removed or changed.
resource_id	string	read-only	The ID of the resource.
channel	string	read-only	Channel that has been about the resource action.
status	string	read-only	Status of the webhook request, either pending, started, successful or failed.
retry_index	integer	read-only	How many times the request has been retried.
reason	string	read-only	The reason for failure if status is failed, otherwise null.
response_status_code	integer	read-only	Status code of a completed request, null if in progress.
response_body	string	read-only	Response body of a completed request, null if in progress.
response_headers	dict	read-only	Key-value map containing response headers of a completed request, null if in progress.
duration	integer	read-only	How many milliseconds lasted to get a response for the request, null if in progress.
completed_at	[date/time]	read-only	When the request was completed.

List webhook log entries

Get a paginated collection of webhook log entries for owned app:

GET /api/v5/orgs/<organization_id/owned_apps/<app_id>/webhook_log_entries

This returns a paginated collection of webhook log entries for the given app_id. The results are ordered by created_at, in descending order.

This endpoint returns:

• 200 if the request was successful
• 401 if you are not authenticated
• 403 if you do not have active subscription
• 403 if you do not have access to the organization
• 403 if you do not have settings permission