Skip to main content

Messages

Messages are the core building blocks of ChatKitty applications. Users send messages using the client SDK, while bots and system administrators can send messages using the Platform API. Text messages have a Unicode text body, while file messages have a file attached to them. User messages are messages sent by end-users of your application through the client SDK. System messages are messages sent via the Platform API on behalf of the application.

Schema​

type
required
string

The type of this message

id
required
integer <int64>

64-bit integer identifier associated with this resource

body
required
string

The text body of this message

channel_id
required
integer <int64>

The ID of the channel this message belongs to

created_time
required
string <date-time>

The time this message was created

group_tag
string

Optional string to associate this message with other messages. Can be used to group messages into a gallery

last_edited_time
string <date-time>

The time this message was last edited

Array of objects (MessageLinkProperties)

Link previews in this message

Array of objects (MessageMentionProperties)

Mentions in this message

nested_level
required
integer <int32>

The nested thread level of this message

required
object

Custom data associated with this message

Array of objects (MessageReactionsSummaryProperties)

Reactions to this message

replies_count
integer <int64>

The number of replies to this message

required
object (ChatUserProperties)
Array of objects (Link)

Hypermedia control links for this resource

Example
{}

Message types​

There are four types of messages:

User Text Message​

Users can send text messages containing a Unicode text body. These messages can contain emojis and other Unicode characters.

User File Message​

Users can send files messages with a file attachment.

System Text Message​

You can send text messages containing a Unicode text body on behalf of your application.

System File Message​

You can send file messages with a file attachment on behalf of your application.

Sending to a message​

You can send messages in a channel, a channel thread, as a reply to another message.

Sending a user text message​

Using a client SDK as a channel member, send a user text message.

Parameters​

Channel message parameters​
NameTypeDescriptionRequired
channelChannelChannel this message belongs to✔
bodystringThe Unicode text body of this message✔
propertiesobjectCustom data associated with this message-
const result = await chatkitty.sendMessage({
  channel: channel,
  body: 'Hello, world!'
});

if (result.succeeded) {
  const message = result.message; // Handle message
}

if (result.failed) {
  const error = result.error; // Handle error
}
Message reply parameters​
NameTypeDescriptionRequired
messageMessageparent message being replied to✔
bodystringThe Unicode text body of this message✔
propertiesobjectCustom data associated with this message-
const result = await chatkitty.sendMessage({
  message: message,
  body: 'This is a reply!'
});

if (result.succeeded) {
  const message = result.message; // Handle message
}

if (result.failed) {
  const error = result.error; // Handle error
}

Sending a user file message​

Using a client SDK, send a user file message.

Parameters​

Channel message parameters​
NameTypeDescriptionRequired
channelChannelChannel this message belongs to✔
fileFileFile to upload as an attachment or ChatKitty external file properties✔
propertiesobjectCustom data associated with this message-
progressListenerUploadProgressListenerListener to be notified as the file upload progresses.-
const result = await chatkitty.sendMessage({
  channel: channel,
  file: file,
  progressListener: {
    onStarted: () => {
      // Handle file upload started
    },

    onProgress: (progress) => {
      // Handle file upload process
    },

    onCompleted: (result) => {
      // Handle file upload completed
    }
  }
});

if (result.succeeded) {
  const message = result.message; // Handle message
}

if (result.failed) {
  const error = result.error; // Handle error
}
Message reply parameters​
NameTypeDescriptionRequired
messageMessageparent message being replied to✔
fileFileFile to upload as an attachment or ChatKitty external file properties✔
propertiesobjectCustom data associated with this message-
progressListenerUploadProgressListenerListener to be notified as the file upload progresses.-
const result = await chatkitty.sendMessage({
  message: message,
  file: file,
  progressListener: {
    onStarted: () => {
      // Handle file upload started
    },

    onProgress: (progress) => {
      // Handle file upload process
    },

    onCompleted: (result) => {
      // Handle file upload completed
    }
  }
});

if (result.succeeded) {
  const message = result.message; // Handle message
}

if (result.failed) {
  const error = result.error; // Handle error
}

Listing messages​

You can list previous messages and observe new messages.

Listing channel messages​

A user can list previous messages in a channel he or she is a member.

const result = await chatkitty.listMessages({
  channel: channel
});

if (result.succeeded) {
  const messages = result.paginator.items; // Handle messages
}

if (result.failed) {
  const error = result.error; // Handle error
}

Listing message replies​

List replies to a message.

const result = await chatkitty.listMessages({
  message: message
});

if (result.succeeded) {
  const messages = result.paginator.items; // Handle messages
}

if (result.failed) {
  const error = result.error; // Handle error
}

Observing channel messages​

A user can observe new messages in a channel he or she is a member of.

chatkitty.startChatSession({
  channel: channel,
  onMessageReceived: (message) => {
    // Handle received message
  }
});

Mentions​

Mentions are a direct way to notify users of things that need their attention in a message. Mentions can trigger notifications and are embedded inside a message.

Schema​

type
required
string

The type of this message mention

end_position
required
integer <int32>

The ending position of this mention reference inside its message

start_position
required
integer <int32>

The starting position of this mention reference inside its message

tag
required
string

The literal text referencing the mentioned entity inside the message

required
object (MessageMentionChannelProperties)

Channel properties embedded in channel mentions

Example
{
  • "type": "CHANNEL",
  • "end_position": 0,
  • "start_position": 0,
  • "tag": "string",
  • "channel": {
    }
}

Mention types​

There are two types of message mentions:

Channel mention​

This notifies all members of a public or private channel.

Additional Properties​
NameTypeDescriptionRequired
channelChannelThe channel that was mentioned✔

User mention​

This notifies a user.

Additional Properties​
NameTypeDescriptionRequired
userUserThe user that was mentioned✔

Mentioning users and channels​

Users can mention channels and users inside their messages using ChatKitty's mention syntax.

Mentioning a user​

You can mention a user using the ChatKitty user mention syntax inside a text message: <@username> where username is the username of the user being mentioned.

const result = await chatkitty.sendMessage({
  channel: channel,
  body: 'Hello, <@jane@chatkitty.com>!'
});

if (result.succeeded) {
  const message = result.message; // Handle message
}

if (result.failed) {
  const error = result.error; // Handle error
}

Mentioning a channel​

You can mention a channel using the ChatKitty channel mention syntax inside a text message: <#channelName> where channelName is the name of the channel being mentioned.

const result = await chatkitty.sendMessage({
  channel: channel,
  body: 'Hello, <#my-public-channel>!'
});

if (result.succeeded) {
  const message = result.message; // Handle message
}

if (result.failed) {
  const error = result.error; // Handle error
}

Message Links contain parsed link preview data like an image and description and are embedded inside a message.

Schema​

end_position
required
integer <int32>

The ending index of this link within the message

object (MessageLinkPreviewProperties)

Embedded link preview data

source
required
string

The href of the URL this message link represents

start_position
required
integer <int32>

The starting index of this link within the message

{
  • "end_position": 0,
  • "preview": {
    },
  • "source": "string",
  • "start_position": 0
}

Message links are automatically created for URLs embedded inside text messages:

const result = await chatkitty.sendMessage({
  channel: channel,
  body: "Here's a link! https://chatkitty.com"
});

if (result.succeeded) {
  const links = result.message.links; // Handle message links
}

if (result.failed) {
  const error = result.error; // Handle error
}