Message content

The content field is the most important part of a message. It specifies exactly what text or attachments the message contains, in what order, and how they should be formatted.

The content field replaces the three fields that historically made up the message body: text, attachment, and location. We will continue to support these fields indefinitely. However, we recommend that you use content instead, as it is more flexible and allows for mixed-content messages.

Types of content block

The message content field contains a list of content blocks, which are shown in order, top-to-bottom. There are three different kinds of ContentBlock:

TextBlock is the most common content block, used for formatted text.
FileBlock is used when including a file attachment in a message.
LocationBlock is used to share some coordinates on the world map.

Text

Text blocks are the most flexible and intricate kind of content block. This is because users can combine different kinds of formatting in one message, nested inside of each other.

TextBlock

Structure

Example


1{
2  type: "text",
3  children: TextNode[]
4}


1// For the message `*hi _there_*`
2{
3  type: "text",
4  children: [
5    {
6      type: "bold"
7      children: [
8        "hi ",
9        {
10          type: "italic"
11          children: ["there"]
12        }
13      ],
14    }
15  ]
16}

See the reference documentation for more details about TextBlock and TextNode.

Attachments

All file blocks contain the URL to the file, its name, and the size of the file in bytes. Sometimes, additional metadata is available, like the dimensions of an image.

FileBlock

Structure

Example


1{
2  type: "file",
3  url: string,
4  filename: string,
5  size: number,
6
7  subtype?: "video" | "image" | "audio" | "voice",
8  height?: number,
9  width?: number,
10  duration?: number,
11
12  // Used to send this file in a new message
13  fileToken: string
14}


1{
2  type: "file",
3  url: "https://firebasestorage.googleapis.com/v0/b/glaring-fire-2362/o/user_files%2FHku1c4Pt%2F61588754ca974ae1b5b36b700b9d70bd%2Fcat.png?alt=media&token=64902dc4-a0ac-42f9-9f55-1cc80d053b28",
4  filename: "cat.png",
5  size: 1938103,
6
7  subtype": "image",
8  height": 1339,
9  width": 1008,
10
11  fileToken: "L0oWSRgETFtfWBNRQhBSQgIRHRkHTl8CABsZDFYMwOb6TAcBFQwLS1lDDw0NDhFOBUdeUA5JhvT7AkpDX1RNT0cRUg5bGlENAhECElYPRA8HFhZCDhVFHxUdFQRHDUsVDQ4ECQoUA0kVQgwYCF0fXkhCXwcNCwAADVpYFEZHCg8SFgsHLEYkGRYSCxISIA5VUwJaMRpEEi9DEVVaQV1VXgBcUBVSQBQPFULSt_IQBFhNUQsKVgJbVFwSJ0MDEVwCF0fd4f9UTR8KABwCQxBPCRxOTlNAUkpZDhhZRA9RRhdCUhNVVV8FARUMSEFbBAVSW0FCEANVWVVJUAELDkcYGENURUATUEICBx0HVB4VC1dJAiQYEgZLAik"
12}

See the reference documentation for more details about FileNode and the specifics of when each optional property will be set.

Locations

Locations are the simplest kind of content block. They specify a pair of coordinates on the world map, as latitude and longitude. Most often, this is because a user shared their location. However, it can be used for other purposes, such as giving updates on the location of a customer's order.

LocationBlock

Structure

Example


1{
2  type: "location",
3  latitude: number,
4  longitude: number
5}


1{
2  type: "location",
3  latitude: 45.430556,
4  longitude: -122.371667
5}

See the reference documentation for more details about LocationBlock and how it can be used.

Using message content

Parsing and displaying message content is essential when building your own chat UI from scratch. However, it can also be necessary to read the message content as part of a backend process.

For example, you could read the message content from the payload of a message.sent webhook, looking for instances where a user is mentioned regarding a specific topic they are interested in. Alternatively, you could add custom formatting for messages containing TODO lists, where you display the list outside the TalkJS UI.

Sending message content

When sending a message, you will specify its content. The content you send in a message is almost identical to the content you receive. The only difference is FileBlock.

When sending a message, you use a simpler version that only contains the type and the file token:

SendFileBlock

Structure

Example


1{
2  type: "file",
3  fileToken: string
4}


1{
2  type: "file",
3  fileToken: "L0oWSRgETFtfWBNRQhBSQgIRHRkHTl8CABsZDFYMwOb6TAcBFQwLS1lDDw0NDhFOBUdeUA5JhvT7AkpDX1RNT0cRUg5bGlENAhECElYPRA8HFhZCDhVFHxUdFQRHDUsVDQ4ECQoUA0kVQgwYCF0fXkhCXwcNCwAADVpYFEZHCg8SFgsHLEYkGRYSCxISIA5VUwJaMRpEEi9DEVVaQV1VXgBcUBVSQBQPFULSt_IQBFhNUQsKVgJbVFwSJ0MDEVwCF0fd4f9UTR8KABwCQxBPCRxOTlNAUkpZDhhZRA9RRhdCUhNVVV8FARUMSEFbBAVSW0FCEANVWVVJUAELDkcYGENURUATUEICBx0HVB4VC1dJAiQYEgZLAik"
4}

You can get a file token by uploading your file to TalkJS. Read more about how to upload files to TalkJS using the JavaScript SDK or using the REST API.

Alternatively, you can share a file from an existing message by reusing the fileToken in that message's content.