Custom emojis

Note: If you've edited your UserMessage theme component before 9 September 2024, you'll have to update the component for custom emoji reactions to display correctly. See the upgrade guide for how to do this.

You can add custom emojis to your chat. Custom emojis are user-defined images, such as GIFs, PNGs, or SVGs, that users can add in messages or as reactions, in addition to the built-in emoji set.

Add custom emojis

You can add custom emoji images to your chat UI with the customEmojis option.

Make sure to wrap custom emoji names in colons, for example :party:, to avoid any clashes with normal text.

For each emoji, you must specify a url. This must be a fully qualified URL of an image file, such as an SVG, GIF, or PNG. The image must be square, so have its width equal its height. TalkJS scales your image down to the size of an emoji.

Once added, users can use custom emojis in their messages, or as reactions to messages:

Make sure you always specify a consistent, backward-compatible set of custom emojis. If an existing message contains a custom emoji that's not specified in customEmojis, then TalkJS can't display the emoji and displays the emoji's name instead, including colons.

Remove custom emojis

If you'd like to remove a previously added custom emoji, you can do so safely by using the hidden option.

Users can't add hidden emojis to new messages, or use them in new emoji reactions, but hidden emojis still display properly in existing messages and reactions. This lets you safely remove custom emoji from the chat UI.

Example

The following example adds three custom emoji, with the names :lol:, :roomba-cat: and :alert::


1await Talk.ready;
2
3const session = new Talk.Session({
4  appId: '<APP_ID>',
5  userId: 'emoji_user_alice',
6});
7session.currentUser.createIfNotExists({
8  name: 'Alice',
9});
10
11const conversation = session.conversation('emoji_conversation');
12conversation.createIfNotExists();
13
14const chatbox = session.createChatbox({
15  customEmojis: {
16    ':lol:': { url: 'https://example.com/images/emoji-lol.svg' },
17    ':roomba-cat:': { url: 'https://example.com/images/roomba-cat.gif' },
18    ':alert:': { url: 'https://example.com/images/alert.gif', hidden: true },
19  },
20});
21chatbox.select(conversation);