App

An app is the test environment or the live environment of your TalkJS project. These endpoints let you manage your app metadata and your app's theme.

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

GETPUT/v1/{appId}

Manage your app metadata

You can get or update the following 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.

Get your 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}

Update your 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.

Manage your theme

You can export or change your app's theme. You may want to do this to transfer a theme between different TalkJS projects.

The data for each theme consists of a versioned base theme (the preset theme that you modified to create your theme), plus a list of the contents of the files for any theme components where you have made changes to the base theme.

These files will have a name ending in .template. If you made changes to the Layout section of your theme, it will also contain a layout.json file.

For example, if you create a new theme, my_theme, by modifying the ChatHeader component and Layout section of the default_v6 theme, your data for that theme will look like:


1"my_theme": {
2    "base": "default_v6",
3    "files": {
4      "ChatHeader.template": "... chat header file content ...",
5      "layout.json": "... layout file content ...",
6    }
7  },

If you don't specify a version when calling the change your theme endpoint, it will use the latest one. You only need to specify the version if you are updating or importing an existing theme that uses an older version of the base theme.

Export your theme

This endpoint returns a list of the data for each of your 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}

Change your theme

This single endpoint covers creating, updating and deleting themes. You can use it to import exported theme data from another project.

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}

The body of your request should be an object with theme names as keys. 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 any file 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.

The base theme in each theme object should be one of the following preset themes:

default
default_dark
team_chat
livestream
comments
email

By default, this will be the latest version of the theme. To use an older version, you must also specify the version of the base theme (for example, default_v5). We introduce new versions of a preset theme when we make significant changes to the look and feel of the theme, or introduce new functionality that we don't want to add into your chat without your explicit consent.

When importing an exported 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.

This endpoint does not prevent you from making changes to your live app theme that are not in your test app. This is different to the Theme Editor in the dashboard, where you can only directly edit themes for your test environment and then publish the changes to your live environment, ensuring that the theme stays in sync between both environments. If you use this endpoint to 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.

Error handling

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