Message content
View as MarkdownEvery 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)
ContentBlock()
Map<String, dynamic> contentBlock.toJson()
Returns
A block of formatted text in a message's content.
Each TextBlock is a tree of 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:
Rather than relying the automatic message parsing, you can also specify the TextBlock directly using ConversationRef.sendMessage with .
The tree of formatted text nodes.
Map<String, dynamic> textBlock.toJson()
Returns
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 Link as it can be used to maliciously hide the true destination of a link.
The URL to open when the node is clicked.
Map<String, dynamic> link.toJson()
Returns
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 Link, users do have permission to send AutoLink 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:
That link will appear as talkjs.com and link you to the specific section of the documentation that explains how AutoLink works.
These rules ensure that the user knows what link they are clicking, and prevents AutoLink 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.
Map<String, dynamic> autoLink.toJson()
Returns
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 ActionLink 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.
Map<String, dynamic> actionLink.toJson()
Returns
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.
Map<String, dynamic> actionButton.toJson()
Returns
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 (including colons at the start and end) 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.
Map<String, dynamic> mention.toJson()
Returns
FileBlock()
Map<String, dynamic> fileBlock.toJson()
Returns
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 == null directly, as this will break when we add new FileBlock variants in the future.
Instead, treat GenericFileBlock as the default. For example:
The name of the file, including file extension
An encoded identifier for this file. Use in SendFileBlock to send this file in another message.
The size of the file in bytes
Never set for generic file blocks.
The URL where you can fetch the file
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 TalkSession.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.
The duration of the video in seconds, if known.
The name of the video file, including file extension.
An encoded identifier for this file. Use in SendFileBlock to send this video in another message.
The height of the video in pixels, if known.
The size of the file in bytes.
The URL where you can fetch the file.
The width of the video in pixels, if known.
VideoBlock({required fileToken, required url, required size, required filename, width, height, duration})
Map<String, dynamic> videoBlock.toJson()
Returns
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 TalkSession.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.
The name of the image file, including file extension.
An encoded identifier for this file. Use in SendFileBlock to send this image in another message.
The height of the image in pixels, if known.
The size of the file in bytes.
The URL where you can fetch the file.
The width of the image in pixels, if known.
Map<String, dynamic> imageBlock.toJson()
Returns
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 TalkSession.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.
The duration of the audio in seconds, if known
The name of the audio file, including file extension
An encoded identifier for this file. Use in SendFileBlock to send this file in another message.
The size of the file in bytes
The URL where you can fetch the file
Map<String, dynamic> audioBlock.toJson()
Returns
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 TalkSession.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.
The duration of the voice recording in seconds, if known
The name of the file, including file extension
An encoded identifier for this file. Use in SendFileBlock to send this voice recording in another message.
The size of the file in bytes
The URL where you can fetch the file
Map<String, dynamic> voiceBlock.toJson()
Returns
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
Map<String, dynamic> locationBlock.toJson()
Returns
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 .
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:
The encoded identifier for the file, obtained by uploading a file with , or taken from another message.
Map<String, dynamic> sendFileBlock.toJson()