Email themes

Email themes are available on the Growth plan and higher.

An email theme renders a notification email message. You can edit an email theme from the Themes page of your TalkJS dashboard, in the section Email themes.

Each email theme has a single built-in component, Email. You can use HTML and CSS to customize the built-in Email component. The markup and styling are rendered directly into the body of the notification email.

In addition, you can also create your own custom components for your notification emails, which you can use from inside the Email component.

Props

The Email component receives the following props:

Name	Type	Description
messages	`Message`	The messages that the user is notified about
app	`App`	App metadata configured in your TalkJS dashboard
sender	`User`	Sender of the message that triggered this notification
recipient	`User`	The recipient of the notification
conversation	`Conversation`	The conversation that the messages were sent in

Types

User

Represents a user.


1type User = {
2  id: string;
3  name: string;
4  role: string | null;
5  photoUrl: string | null;
6  custom: Record<string, string>;
7};

Conversation

Represents a conversation.


1type Conversation = {
2  id: string;
3  subject: string | null;
4  participants: User[];
5  photoUrl: string | null;
6  custom: Record<string, string>;
7};

Message

Represents a message in a conversation.


1type Message = {
2  id: string;
3  type: 'UserMessage' | 'SystemMessage';
4  formattedText: HTML; // The formatted content of the message. For attachments, this consists of a link. For replies, this markup also includes the referenced message.
5  referencedMessage: Message | null; // If this message is a reply, referencedMessage points to the referenced message.
6  previousMessage: Message | null; // The previous message in the list. previousMessage is null for the first message in a conversation, and for referenced messages.
7  custom: Record<string, string>;
8  body: {
9    type: 'text' | 'file' | 'location';
10    isVoiceMessage: boolean;
11    file: File; // Only for messages of type `file`.
12    location: [number, number]; // Coordinates giving the latitude and longitude of the location. Only for messages of type `location`.
13    rawText: string; // Only for messages of type `text`.
14    formattedText: Element; // Only for messages of type `text`.
15  };
16};

File

Represents a file attached to a message.


1type File = {
2  filename: string;
3  url: string;
4  size: number; // Size of the file in bytes
5};

CSS

TalkJS converts all CSS classes to inline styles using a library called juice. This means that you can freely use classes, and the result usually works, even inside quirky email clients.

Headers

You can customize the headers of an email notification from the Headers tab of your email theme editor.

Overview of the email theme editor, with the section 'Headers' selected. An panel with 'Email headers' is open, in which the 'From' and 'Subject' headers can be customized. Below the panel is an arrow to a preview of how the headers would show up in an email.

You can use the following macros in the email notification header.

app.name
app.id
app.locale
app.custom.<CUSTOM_FIELD>
sender.id
sender.name
sender.custom.<CUSTOM_FIELD>
recipient.id
recipient.name
recipient.custom.<CUSTOM_FIELD>
conversation.id
conversation.subject
conversation.topicId
conversation.custom.<CUSTOM_FIELD>

Replace <CUSTOM_FIELD> with the name of the custom field that you would like to use. For details about app.* macros, see App metadata and translations below.

App Metadata and Translations

The app prop contains metadata for your TalkJS app:


1type App = {
2  id: string;
3  name: string;
4  locale: string;
5  custom: Record<string, string>;
6};

You can use app.name, app.locale, and app.custom.<CUSTOM_FIELD> in both email themes and in the email notification header macros. Custom fields come from the app metadata custom fields configured in your TalkJS dashboard.

To localize an app custom field, add custom fields with locale suffixes:


1{
2  "newMessagesText": "You have new messages",
3  "newMessagesText:fr": "Vous avez de nouveaux messages",
4  "newMessagesText:zh-TW": "你有新訊息"
5}

You can then use the unlocalized field name in your theme:


1{{app.custom.newMessagesText}}

When TalkJS renders an email for a recipient, it first tries the user's locale. For regional locales, TalkJS tries the full locale and then the language code, so zh-TW first tries newMessagesText:zh-TW and then newMessagesText:zh. If no matching user-locale value exists, TalkJS falls back to your app's default locale, and finally the unlocalized custom field such as newMessagesText.