Chat Messages
Applications (e.g. chatbots) can interact with Space users through the application chat channel.
In the application chat channel, a Space user can:
In all these cases, Space will send a different type of payload to the application.
Adding a chat channel for an application is an explicit action. Multi-org applications can add a chat channel for themselves by making the setUiExtensions
API call. For example, this is how you can do it on the server side using Kotlin Space SDK:
space.applications.setUiExtensions(
contextIdentifier = GlobalPermissionContextIdentifier,
extensions = listOf(ChatBotUiExtensionIn())
)
In case of a single-org application, you can enable a chat channel from the application settings:
In Extensions | Applications, open the required application.
In the Overview tab, select Chat bot.
If you want to open the corresponding chat channel, click Go to chat bot.
When a user starts typing in the application chat channel, Space sends payload of the ListCommandsPayload
type to the application.
An example of the payload:
{
{...}
A typical chatbot works in the following way:
If a user types the slash
/
character, Space shows the full list of available commands.If a user types some other character, Space handles the characters as a search pattern and shows the list of commands that match the pattern.
Space provides this functionality out of the box. The only task of the application is to respond with a JSON list of available commands on receiving a ListCommandsPayload
. For each command, you should specify its name
and description
. For example:
{
"commands": [
{
"name": "help",
"description": "Show this help"
},
{
"name": "do",
"description": "Do something"
}
]
}
To help you prepare the list of available commands, Space SDK provides the CommandDetail
class. For example, this is how you can use it to prepare the list of commands and send it back to Space:
// our custom command that can also 'run' something
{...}
When a user types a message in the application chat and presses Enter, Space sends a payload of the MessagePayload
type to the application.
An example of the payload:
{
{...}
If your application is a chatbot or a slash command, typically, it implies that a user must send some command to the application chat. This can be just a command name, for example, help
, or a command with arguments, for example, book room-621
. The MessagePayload
class provides two helper functions for processing commands sent in the messages:
MessagePayload.command(): String?
returns the command specified by the userMessagePayload.commandArguments(): String?
returns the command arguments specified by the user
// For example, a user sends 'do 1234' to chat
val cmd = payload.command() // do
val cmdargs = payload.commandArguments() // 1234
To help you work with different types of message attachments, Space SDK provides several classes, for example, FileAttachment
, ImageAttachment
, VideoAttachment
, and others. Learn how to upload and attach files
For example, this is how you can handle messages with Kotlin Space SDK:
// our custom command that can also 'run' something
{...}
Message constructor DSL lets you create chat messages containing interactive UI controls (currently, only buttons are supported). The controls have the action: MessageAction
property. The MessageAction
interface has one implementation: PostMessageAction(actionId: String, payload: String)
. When a user clicks a button in the chat, Space sends a payload of the MessageActionPayload
type to the application. The payload contains button's actionId
and action's payload
. After performing this action, the application must respond with the 200 OK
HTTP status.
An example of the payload:
{
{...}
In case of Space SDK, use the MessageActionPayload
class to process message actions. The class provides two properties:
actionId: String
returns theactionId
of the clicked button.actionValue: String
returns the actionpayload
.
// For example, a user clicks a button with
// 'actionId="do"' and 'payload="that!"'
val id = payload.actionId // do
val value = payload.actionValue // that!
Here's how you can process message actions with Kotlin Space SDK:
fun main() {
{...}
Thanks for your feedback!