App

An app is the test environment or the live environment of your TalkJS project. These endpoints let you change app metadata:

custom: global custom fields for the entire app. Can be used in themes and notification settings as {{ app.custom.fieldName }}.
defaultLocale: An IETF language tag for the app's default locale. Must be one of the supported languages. You can override this locale for each user.

All resource URLs below include an {appId}, which you can find on the Settings page of your TalkJS dashboard.

GETPUT/v1/{appId}

Getting app metadata

GET/v1/{appId}

Response Structure

Example Response


1type App = {
2  id: string;
3  custom?: { [name: string]: string };
4  defaultLocale?: string;
5};


1{
2  "custom": {},
3  "defaultLocale": "en-US",
4  "id": "123456789"
5}

Changing app metadata

PUT/v1/{appId}

Payload Structure

Example Payload


1{
2  id?: string,
3  custom?: Map<string, string>,
4  defaultLocale?: string
5}


1{
2  "custom": {"some": "data"},
3  "defaultLocale": "en-US",
4}

All the parameters in the payload are optional.

Note that id can't be changed. If given, the id must correspond to the appId found in the URL.

Managing themes

Each theme is based on one of our preset themes, which is set as the theme's base, plus the contents of any files you add or modify from the base theme. All component file names must end in .template, and the theme can have a layout.json file. Files with any other extensions will be ignored. When you manage themes via the editor in the dashboard, you can only directly edit themes for your test environment. You then have the option to publish the theme, copying the changes to your live environment. This ensures that the theme stays in sync between both environments. This API has no such guardrails, so if you import changes to your theme into your live app, they won't show up in the theme editor on the dashboard. It's best to either import themes into both environments, or only to your test environment, to avoid them getting out of sync.

Exporting themes

GET/v1/{appId}/themes

Response Structure

Example Response


1type Themes = {
2  [themeName: string]: {
3    base: string;
4    files: { [fileName: string]: string };
5  };
6};


1{
2  "theme1": {
3    "base": "default_v7",
4    "files": {
5      "File1.template": "content1"
6    }
7  },
8  "theme2": {
9    "base": "default_dark_v2",
10    "files": {
11      "File1.template": "content2"
12    }
13  }
14}

Adding, updating and deleting themes

We have a single endpoint for making changes to themes. For each key in the object:

If the value is a theme object, a theme with that name will be created or, updated if it already exists. Updating a theme completely overwrites it, meaning that a file that's omitted from the files object in the request, will no longer be present in the overwritten theme.
If the value is null, the theme with that name is deleted, if it exists.

PUT/v1/{appId}/themes

Payload Structure

Example Payload


1{
2  [themeName: string]: {
3    base: string;
4    files: { [fileName: string]: string };
5  } | null;
6}


1{
2  "theme1": {
3    "base": "default_v7",
4    "files": {
5      "File1.template": "content1"
6    }
7  },
8  "theme2": {
9    "base": "default_dark_v2",
10    "files": {
11      "File2.template": "content2"
12    }
13  },
14  "theme3": null
15}

Base versions

Sometimes, we make changes to our preset theme that quite drastically change the preset's look and feel, or introduce new functionality that we don't want to add into your chat without your explicit consent. When that happens, we introduce a new version of the preset.

When re-importing existing themes to make changes, you should pass the base including the version that was provided when you exported it. When importing a newly created theme, we recommend specifying the base without a version. This means the latest version of that preset will be used.

Available base themes

The following base themes are available for use when importing themes.

default
default_dark
team_chat
livestream
comments
email

Error handling

When importing, updating or deleting themes, th endpoint returns an object with the result for each theme. Each of the result objects will have a status value with an HTTP status value, and an errorCode field with the following error codes:

400 BAD_REQUEST: The theme data structure is invalid or the base theme does not exist.
401 UNAUTHORIZED: Authorization is required to import themes.
404 NOT_FOUND: The theme to be deleted does not exist.