Message content
Every message has "content" which specifies the information in the message. This could be some formatted text, a file attachment, or a shared location.
See the conceptual documentation for message content to learn more about how TalkJS represents message content.
The content of a message is structured as a list of content blocks.
Currently, each message can only have one content block, but this will change in the future. This will not be considered a breaking change, so your code should assume there can be multiple content blocks.
These blocks are rendered in order, top-to-bottom.
Currently the available Content Block types are:
- type: "text" (TextBlock)
- type: "file" (FileBlock)
- type: "location" (LocationBlock)
A block of formatted text in a message's content.
Each TextBlock is a tree of TextNode children describing the structure of some formatted text. Each child is either a plain text string, or a node representing some text with additional formatting.
For example, if the user typed:
> *This first bit* is bold, and *_the second bit_* is bold and italics
Then this would become a Text Block with the structure:
1{2 type: "text",3 children: [4 {5 type: "text",6 children: [7 { type: "bold", children: ["This first bit"] },8 " is bold, and ",9 {10 children: [11 { type: "italic", children: ["the second bit"] }12 ],13 type: "bold",14 },15 " is bold and italics",16 ],17 },18 ],19}
Rather than relying the automatic message parsing, you can also specify the TextBlock directly using ConversationRef.send with SendMessageParams.
Any node that can exist inside a TextBlock.
The simplest TextNode is a plain text string. Using "hello" as an example message, the TextBlock would be:
1{2 type: 'text';3 children: ['hello'];4}
Other than plain text, there are many different kinds of node which render some text in a specific way or with certain formatting.
1type TextNode =2 | string3 | MarkupNode4 | BulletListNode5 | BulletPointNode6 | CodeSpanNode7 | LinkNode8 | AutoLinkNode9 | ActionLinkNode10 | ActionButtonNode11 | CustomEmojiNode12 | MentionNode;
If the text node is not a plain string, it will have a type field indicating what kind of node it is, and either a property text: string or a property children: TextNode[]. This will be true for all nodes added in the future as well.
Full documentation of each TextNode variant
A node in a TextBlock that renders its children with a specific style.
The kind of formatting to apply when rendering the children
- type: "bold" is used when users type *text* and is rendered with HTML <strong>
- type: "italic" is used when users type _text_ and is rendered with HTML <em>
- type: "strikethrough" is used when users type ~text~ and is rendered with HTML <s>
A node in a TextBlock that adds indentation for a bullet-point list around its children (HTML <ul>).
Used when users send a bullet-point list by starting lines of their message with - or *.
A node in a TextBlock that renders its children with a bullet-point (HTML <li>).
Used when users start a line of their message with - or *.
A node in a TextBlock that renders its children as a clickable link (HTML <a>).
By default, users do not have permission to send messages containing LinkNode as it can be used to maliciously hide the true destination of a link.
The URL to open when the node is clicked.
A node in a TextBlock that renders text as a link (HTML <a>).
Used when user-typed text is turned into a link automatically.
Unlike LinkNode, users do have permission to send AutoLinkNodes by default, because the text and url properties must match. Specifically:
- If text is an email, url must contain a mailto: link to the same email address
- If text is a phone number, url must contain a tel: link to the same phone number
- If text is a website, the domain name including subdomains must be the same in both text and url. If text includes a protocol (such as https), path (/page), query string (?page=true), or url fragment (#title), they must be the same in url. If text does not specify a protocol, url must use either https or http.
This means that the following AutoLink is valid:
1{2 type: "autoLink",3 text: "talkjs.com"4 url: "https://talkjs.com/docs/Reference/JavaScript_Data_API/Message_Content/#AutoLinkNode"5}
That link will appear as talkjs.com and link you to the specific section of the documentation that explains how AutoLinkNodes work.
These rules ensure that the user knows what link they are clicking, and prevents AutoLinkNode being used for phishing. If you try to send a message containing an AutoLink that breaks these rules, the request will be rejected.
The text to display in the link.
The URL to open when a user clicks this node.
A node in a TextBlock that renders its children as a clickable action link which triggers a custom action.
By default, users do not have permission to send messages containing ActionLinkNode as it can be used maliciously to trick others into invoking custom actions. For example, a user could send an "accept offer" action link, but disguise it as a link to a website.
The name of the custom action to invoke when the link is clicked.
The parameters to pass to the custom action when the link is clicked.
A node in a TextBlock that renders its children as a clickable action button which triggers a custom action.
By default, users do not have permission to send messages containing action buttons as they can be used maliciously to trick others into invoking custom actions. For example, a user could send an "accept offer" action button, but disguise it as "view offer".
The name of the custom action to invoke when the button is clicked.
The parameters to pass to the custom action when the button is clicked.
A node in a TextBlock that renders text in an inline code span (HTML <code>).
Used when a user types ```text```.
A node in a TextBlock that is used for custom emoji.
The name of the custom emoji to show.
A node in a TextBlock that is used when a user is mentioned.
Used when a user types @name and selects the user they want to mention.
The ID of the user who is mentioned.
The name of the user who is mentioned.
A file attachment received in a message's content.
All FileBlock variants contain url, size, and fileToken. Some file blocks have additional metadata, in which case they will have the subtype property set.
Currently the available FileBlock subtypes are:
- No subtype set (GenericFileBlock)
- subtype: "video" (VideoBlock)
- subtype: "image" (ImageBlock)
- subtype: "audio" (AudioBlock)
- subtype: "voice" (VoiceBlock)
Full documentation of each FileBlock variant
The most basic FileBlock variant, used whenever there is no additional metadata for a file.
Do not try to check for subtype === undefined directly, as this will break when we add new FileBlock variants in the future.
Instead, treat GenericFileBlock as the default. For example:
1if (block.subtype === "video") {2 handleVideoBlock(block);3} else if (block.subtype === "image") {4 handleImageBlock(block);5} else if (block.subtype === "audio") {6 handleAudioBlock(block);7} else if (block.subtype === "voice") {8 handleVoiceBlock(block);9} else {10 handleGenericFileBlock(block);11}
An encoded identifier for this file. Use in SendFileBlock to send this file in another message.
The name of the file, including file extension
The size of the file in bytes
The URL where you can fetch the file
Never set for generic file blocks.
A FileBlock variant for a video attachment, with additional video-specific metadata.
You can identify this variant by checking for subtype: "video".
Includes metadata about the height and width of the video in pixels, and the duration of the video in seconds, where available.
Videos that you upload with the TalkJS UI will include the dimensions and duration as long as the sender's browser can preview the file. Videos that you upload with the REST API or Session.uploadVideo will include this metadata if you specified it when uploading. Videos attached in a reply to an email notification will not include any metadata.
An encoded identifier for this file. Use in SendFileBlock to send this video in another message.
The name of the video file, including file extension.
The size of the file in bytes.
The URL where you can fetch the file.
The duration of the video in seconds, if known.
The height of the video in pixels, if known.
The width of the video in pixels, if known.
A FileBlock variant for an image attachment, with additional image-specific metadata.
You can identify this variant by checking for subtype: "image".
Includes metadata about the height and width of the image in pixels, where available.
Images that you upload with the TalkJS UI will include the image dimensions as long as the sender's browser can preview the file. Images that you upload with the REST API or Session.uploadImage will include the dimensions if you specified them when uploading. Image attached in a reply to an email notification will not include the dimensions.
An encoded identifier for this file. Use in SendFileBlock to send this image in another message.
The name of the image file, including file extension.
The size of the file in bytes.
The URL where you can fetch the file.
The height of the image in pixels, if known.
The width of the image in pixels, if known.
A FileBlock variant for an audio attachment, with additional audio-specific metadata.
You can identify this variant by checking for subtype: "audio".
The same file could be uploaded as either an audio block, or as a VoiceBlock. The same data will be available either way, but they will be rendered differently in the UI.
Includes metadata about the duration of the audio file in seconds, where available.
Audio files that you upload with the TalkJS UI will include the duration as long as the sender's browser can preview the file. Audio files that you upload with the REST API or Session.uploadAudio will include the duration if you specified it when uploading. Audio files attached in a reply to an email notification will not include the duration.
An encoded identifier for this file. Use in SendFileBlock to send this file in another message.
The name of the audio file, including file extension
The size of the file in bytes
The URL where you can fetch the file
The duration of the audio in seconds, if known
A FileBlock variant for a voice recording attachment, with additional voice-recording-specific metadata.
You can identify this variant by checking for subtype: "voice".
The same file could be uploaded as either a voice block, or as an AudioBlock. The same data will be available either way, but they will be rendered differently in the UI.
Includes metadata about the duration of the recording in seconds, where available.
Voice recordings done in the TalkJS UI will always include the duration. Voice recording that you upload with the REST API or Session.uploadVoice will include this metadata if you specified it when uploading.
Voice recordings will never be taken from a reply to an email notification. Any attached audio file will become an AudioBlock instead of a voice block.
An encoded identifier for this file. Use in SendFileBlock to send this voice recording in another message.
The name of the file, including file extension
The size of the file in bytes
The URL where you can fetch the file
The duration of the voice recording in seconds, if known
A block showing a location in the world, typically because a user shared their location in the chat.
In the TalkJS UI, location blocks are rendered as a link to Google Maps, with the map pin showing at the specified coordinate. A thumbnail shows the surrounding area on the map.
The north-south coordinate of the location.
Usually listed first in a pair of coordinates.
Must be a number between -90 and 90
The east-west coordinate of the location.
Usually listed second in a pair of coordinates.
Must be a number between -180 and 180
The version of ContentBlock that is used when sending or editing messages.
This is the same as ContentBlock except it uses SendFileBlock instead of FileBlock
SendContentBlock is a subset of ContentBlock. This means that you can re-send the content from an existing message without any issues:
1const existingMessage: MessageSnapshot = ...;23const convRef = session.conversation('example_conversation_id');4convRef.send({ content: existingMessage.content });
The version of FileBlock that is used when sending or editing messages.
When a user receives the message you send with SendFileBlock, this block will have turned into one of the FileBlock variants.
For information on how to obtain a file token, see FileToken.
The SendFileBlock interface is a subset of the FileBlock interface. If you have an existing FileBlock received in a message, you can re-use that block to re-send the same attachment:
1const existingFileBlock = ...;2const imageToShare = existingFileBlock.content[0] as ImageBlock34const convRef = session.conversation('example_conversation_id');5convRef.send({ content: [imageToShare] });
The encoded identifier for the file, obtained by uploading a file with Session.sendFile, or taken from another message.
A token representing a file uploaded to TalkJS.
You cannot create a FileToken yourself. Get a file token by uploading your file to TalkJS with Session.uploadFile, or one of the subtype-specific variants like Session.uploadImage. Alternatively, take a file token from an existing FileBlock to re-send an attachment you received, without having to download and re-upload the file. You can also upload files using the REST API. This system ensures that all files must be uploaded to TalkJS before being sent to users, limiting the risk of malware.
Passed in SendFileBlock when you send a message containing a file attachment.
We may change the FileToken format in the future. Do not store old file tokens for future use, as these may stop working.
Using a file input1// From `<input type="file">`2const file: File = fileInputElement.files[0];3const myFileToken = await session.uploadFile(file, { filename: file.name });45const block = {6 type: 'file',7 fileToken: myFileToken,8};9session.conversation('example_conversation_id').send({ content: [block] });
Re-sending a file from a previous message
1session.conversation('example_conversation_id').send({2 content: previousMessageSnapshot.content3});