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.

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.

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.

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 Notifications → Email 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.

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.

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

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

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.

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

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.

• SMS notifications
• Mobile push notifications
• Themes