Email notifications

When a user has been offline for a while, they can receive email notifications for any messages they missed. You can modify the email notification that TalkJS sends directly from the Notifications page on your dashboard, under Email settings.

Example email notification. The notification shows messages that the user may have missed while they were offline, and a link to click and join the chat.
Example notification email

TalkJS automatically handles sending email notifications to users who go offline, using customizable templates and themes. You can adjust when emails are sent, who receives them, and what they look like, all from your dashboard.

TalkJS groups missed messages into a single email notification and sends it after a defined period of user inactivity. You can specify the period of inactivity after which TalkJS should send a notification in the Timeout (in seconds) field on the Notifications page of your dashboard.

Enable email notifications

To enable email notifications for a user, make sure that the user has at least one valid email address on record. Any user with an email address automatically starts receiving email notifications as soon as they have been offline for a while. Users can have more than one email address, and TalkJS notifies all email addresses on record.

Dedicated domain

You can optionally set up a dedicated domain for email notification purposes, for example chat.example.com or notificationsdomain.com. Using a dedicated domain helps prevent conflicts if your main domain already has its own mail server, and can improve deliverability.

Custom sender address

By default all email notifications come from the address [email protected]. If you’re using a custom email domain, you can customize the local part of the sender address (the part before the @-symbol) directly from your TalkJS dashboard.

To customize your sender address:

  1. On your TalkJS dashboard, from the top right menu, select Email domains.
  2. From the list of domains, find the email domain for which you'd like to change the local part, and select Details.
  3. On the details page, under Sender addresses, update the email details and select Save sender addresses.

Your email notifications are now sent from the custom sender address you specified.

If the details page doesn’t show any settings for the local part, and your notification emails come from an address with a long, random-looking sender name, then custom sender addresses likely aren’t enabled for your account. Get in touch and a member of the TalkJS team can get this set up for you.

Email themes

Custom email notification themes are available on the Growth plan and higher.

TalkJS lets you fully customize the look and layout of your notification emails. You can customize your email notifications directly from the Themes page on your TalkJS dashboard, under Email themes. You can use HTML and CSS to customize the built-in Email component, or add your own custom components.

To activate your custom email notification theme from your TalkJS dashboard:

  1. Go to NotificationsEmail settings and ensure that Enable email is toggled on.
  2. Set Email type to Custom theme.
  3. Choose your preferred theme from the Theme list.

Your custom email theme is now active for your email notifications.

You can create multiple custom email themes, and apply these for different user groups, by creating a different role for each user group and adjust the email notification settings per role. Check out the guide on showing different email notifications for different users.

For more on customizing email themes, see: Email themes.

Customize content with macros

You can use a limited macro syntax to customize your email notifications, for example Hello {{recipient.name}}!. You can use macros directly in various fields on the Notifications page of your TalkJS dashboard.

You can also pass your metadata for users or conversations using the macro syntax. For example, you can specify a custom special token {{sender.custom.specialToken}}. The custom field has to be an object with strings as values.

For example, you can specify a special token for Alice in your code:

JavaScript
1session.currentUser.set({ custom: { specialToken: "jd71ba91n" }});

Note that custom user data is publicly visible (for example, in the browser), so don't use this for sensitive data.

Similarly, you can customize a conversation:

JavaScript
1const conversation = session.conversation('order_83562938');
2conversation.set({
3 subject: 'Hair Wax 5 Gallons',
4 custom: {
5 sellerId: 'seller_mq082jqid92',
6 },
7});

You can link back to your site or app directly from your email notifications, so that users can easily rejoin the conversation. Add your link under Inbox URL on the Notifications page of your TalkJS dashboard.

You can either add a plain link, for example https://example.com, or use template macros to let TalkJS build the inbox URL to go directly to the correct page or conversation.

The inbox URL applies globally to all users, unless overridden per user role.

If you're using the Inbox prebuilt chat UI, you can make the inbox URL immediately preselect the right conversation. For example, if you have a user's inbox on https://example.com/inbox and their conversation ID is 123456, you can add the conversation ID in a query parameter: https://example.com/inbox?conversation=123456. With a template macro, you could then add the following inbox URL:

1https://example.com/inbox?conversation={{conversation.id}}

and TalkJS generates a URL to preselect the correct conversation.

You can link straight to a page about a product or order, by adding a custom field to the conversation to identify the product or order. For example, you could pass {"productId": "12345"} when creating the conversation, and then configure the inbox URL as follows:

1https://yoursite.com/orders/{{conversation.custom.productId}}

With a chatbox or pop-up embedded on the destination page, users can directly continue their conversation right there.

Reply by email

Email replies let users stay engaged with conversations even when they’re not in your app. When a user replies via email, their reply automatically shows up in the chat conversation. No additional setup is needed for replying by email, as TalkJS automatically routes replies to the correct conversation.

Users who only have Read access to a conversation can receive email notifications, but replies they send to a notification email won't show up in the conversation.

All email notifications include an unsubscribe link which, when clicked, unsubscribes the user. This ensures reliable delivery and complies with Google's requirements for bulk email senders.

The unsubscribe link takes the user to a page where they can resubscribe, in case they clicked the link by mistake.

When a user unsubscribes, they won't receive any further email notifications about unread messages.

By default, the unsubscribe link appears at the bottom of each email notification, with the text 'Unsubscribe from all chat emails'. You can change the link text on the Notifications page of your TalkJS dashboard.

If you're using a custom email theme, then you can use the <UnsubscribeLink> component to customize the link text, CSS styling, and placement. The component's children are rendered as the link text. For example:

1<UnsubscribeLink class="unsubscribe">
2 Unsubscribe from Example Company chats
3</UnsubscribeLink>

If your theme doesn't contain an <UnsubscribeLink>, you can add it from Email themes on the Themes page of your TalkJS dashboard. Adding the <UnsubscribeLink> component to your live email theme takes effect immediately.

Turn off email notifications

To turn off email notifications for a user, you can remove the user's email address by setting their email field to null. You can also mute notifications for a particular conversation with the REST API. When notifications are muted, your user won't receive any notifications for that conversation, including email notifications.

See also