Brands API

Brands

Brands represents the UI of chat windows, lead forms, chat buttons, etc. which are shown to visitor (both mobile and desktop). There are some restricted customization options for them. In order to use some specific brand in a room, it can be set by changing the brand attribute in organization room settings API.

Warning

Currently Brands are affecting only mobile chat windows!

A brand has the following attributes:

Attribute	Type	Editable	Description
id	UUID	read-only	Unique identifier for the brand.
organization_id	UUID	read-only	ID of the organization which owns the brand.
organization	object	read-only	Organization which owns the brand.
created_at	datetime	read-only	When the brand was created.
updated_at	datetime	read-only	When was the last time the brand was updated.
created_by_user_id	UUID	read-only	ID of the user which created this brand.
created_by_user	object	read-only	User which created this brand.
updated_by_user_id	UUID	read-only	ID of the last user which updated this brand.
updated_by_user	object	read-only	Last user which updated this brand.
name	string	required	Name of this brand.
primary_color_code	string	required	Primary color code in hexadecimal format. If null then the default color is used.
secondary_color_code	string	required	Secondary color code in hexadecimal format. If null then the default color is used.
logo_asset_id	UUID	optional	ID of the logo (asset) used in this brand. The asset's kind must be a image.
logo_asset	object	read-only	logo (asset) used in this brand. Supported formats are PNG, JPEG, and GIF. Logo will resized to fit the position.

List organization's brands

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

{
  "next": "https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/brands?cursor=171cfd0d7ce542be86221f01d2823cb1",
  "previous": null,
  "results": [
    {
      "id": "58f5055c-56e0-11e5-9354-6c4008c08dfe",
      "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
      "organization": {
        "id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "name": "Company X"
      },
      "created_at": "2015-02-13T11:31:36.042",
      "updated_at": "2015-02-13T12:38:36.431",
      "created_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "created_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "updated_by_user_id": "006ff599-9073-11e6-a887-f45c89c72de3",
      "updated_by_user": {
        "id": "006ff599-9073-11e6-a887-f45c89c72de3",
        "full_name": "Robotti Ruttunen",
        "first_name": "Robotti",
        "last_name": "Ruttunen",
        "organization_id": "e68220e1-9072-11e6-bf95-f45c89c72de3",
        "avatar_id": null,
        "avatar": null,
        "is_bot": false
      },
      "name": "Giosg core brand",
      "primary_color_code": "#549cd9",
      "secondary_color_code": "#f9d656",
      "logo_asset_id": "90967a1e-3cc4-11e8-a67f-8c8590c2eeca",
      "logo_asset": {
        "id": "90967a1e-3cc4-11e8-a67f-8c8590c2eeca",
        "url": "https://giosg.com/logo.png",
        "name": "Company logo",
        "description": null,
        "kind": "image",
        "content_type": "image/jpeg",
        "size": 10000,
        "charset": null,
        "width": 25,
        "height": 25
      }
    }
  ]
}

You can list brands for an organization:

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

This API endpoint returns a paginated collection. They are sorted by the creation time of the brands, in ascending order.

This endpoint takes the following GET-parameters:

Parameter	Type	Default	Description
ordering	ordering	created_at	Ordering of results with options created_at or -created_at.

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

Creating a new brand

Example request for creating a new brand

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

Example request payload

{
  "name": "Spring sales brand",
  "primary_color_code": "#549cd9",
  "secondary_color_code": "#f9d656",
  "logo_asset_id": "974a6078-3731-11e8-96e9-00143d180066"
}

You can create a new brand for an organization by:

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

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

Retrieve details of organization's brand

You can retrieve details of organization's brand:

GET /api/v5/orgs/<organization_id>/brands/<brand_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 the brand was not found

Update existing brand

Example request for updating primary color of existing brand

PUT https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/brands/58f5055c-56e0-11e5-9354-6c4008c08dfe

Example request payload

{
  "name": "Campaign brand",
  "primary_color_code": "#1c1c1c",
  "secondary_color_code": "#ffffff"
}

You can change the brand's attributes by:

PUT /api/v5/orgs/<organization_id>/brands/<brand_id>

or

PATCH /api/v5/orgs/<organization_id>/brands/<brand_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 the brand was not found

Delete a brand

Example request for removing a brand

DELETE https://service.giosg.com/api/v5/orgs/7f9e9580-095b-42c7-838c-c04e667b26f7/brands/58f5055c-56e0-11e5-9354-6c4008c08dfe

You can remove a brand by:

DELETE /api/v5/orgs/<organization_id>/brands/<brand_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 organization
• 403 if you do not have settings permission
• 404 if the brand was not found

List rooms where a brand is in use

Example request and payload: Retrieve rooms which use current brand

GET https://service.giosg.com/api/v5/orgs/64c8fb1c-8673-11e7-a7c7-00163e8edbc5/brands/0b77ca4a-6308-11e7-9d23-00163e07eae6/rooms

{
  "id": "0b77ca4a-6308-11e7-9d23-00163e07eae6",
  "organization_id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
  "organization": {
    "id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
    "name": "Giosg.com"
  },
  "domain": "giosg.com",
  "name": "My room",
  "display_name": "Customer service",
  "is_shared": false,
  "language_code": "en",
  "created_at": "2017-07-07T11:33:06.137Z",
  "updated_at": "2017-07-07T11:33:06.137Z",
  "updated_by_user_id": "97abf1ee-6308-11e7-9d09-00163ec04961",
  "updated_by_user": {
    "id": "97abf1ee-6308-11e7-9d09-00163ec04961",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "organization_id": "64c8fb1c-8673-11e7-a7c7-00163e8edbc5",
    "is_bot": false
  },
  "is_online": true,
  "is_deleted": false,
  "is_service_hours_enabled": true,
  "is_open": true
}

Return a paginated collection of all the room resources in which the given brand is in use for the given organization.

GET https://service.giosg.com/api/v5/orgs/<organization_id>/brands/<brand_id>/rooms

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 the brand was not found