JetBrains Space Help

Receive Payload from Space

With some types of applications, Space acts as a client – it sends POST requests to the application endpoint with JSON payload inside. For example, when a user types in the application chat channel, Space sends payload containing the user input; if the application is subscribed to webhook notifications, Space sends payload with event details, and so on.

Payload contents

The payload consists of the name of a payload class, class-specific payload data, and data that is common for all payload types (like Space URL, user ID, and so on).

For example, this is a sample payload from Space when a user sends help command to a chatbot:

{ // [[[Payload class|#payload-classes]]] "className": "MessagePayload", // Class-specific payload data "message": { "messageId": "CsT000CsT", "channelId": "3FhQeS2URbeY", "messageData": null, "body": { "className": "ChatMessage.Text", "text": "help " }, "attachments": null, "externalId": null, "createdTime": "2021-05-21T17:01:33.767Z" }, // [[[Common payload data|#common-payload-data]]] "accessToken": "", "verificationToken": "abc1234", "userId": "1mEGCd1FvoAh", "serverUrl": "https://mycompany.jetbrains.space", "clientId": "2ulA3W2Vltg6", "orgId": "8fd4d79a-d164-4a71-839a-ff8f8bcd6beb" }

Payload types

To help you process different kinds of payload, Space SDK provides a number of classes. All these classes implement the ApplicationPayload interface.

Class

Description

Relevant for

AppPublicationCheckPayload

JetBrains Marketplace sends this payload during application verification.

Multi-org applications distributed through JetBrains Marketplace.

ApplicationUninstalledPayload

A Space instance sends this payload when the application is uninstalled from this instance.

Multi-org applications distributed via links or through JetBrains Marketplace.

InitPayload

Initializes the application that was installed from JetBrains Marketplace.

Multi-org applications distributed via links or through JetBrains Marketplace.

ListCommandsPayload

Requests a list of available commands. Space sends this payload type when a user types slash / or another character in the application chat channel. The application must respond with a JSON list of commands.

Chatbots, slash commands.

MenuActionPayload

Contains info about the custom menu item selected by a user.

Applications that extend Space context menus with custom items.

MessagePayload

Contains a message sent by a user to the application from a chat channel.

Chatbots, slash commands.

MessageActionPayload

Contains info about the action executed by a user in the application chat channel. Typically, this is a result of user interaction with a UI control in a chat message, for example, clicking a button.

Chatbots, slash commands.

WebhookRequestPayload

Contains info about the event occurred in Space. The application must be subscribed to this event with a corresponding webhook.

Applications that use webhooks to receive notifications about Space events.

Reading the payload

To help you handle the payload, Space SDK provides the Space helper object. This is how you can use it to process the payload depending on its type. For example, in a Ktor application:

@file:OptIn(ExperimentalSpaceSdkApi::class) package com.example import io.ktor.application.* import io.ktor.http.* import io.ktor.request.* import io.ktor.response.* import io.ktor.routing.* import space.jetbrains.api.ExperimentalSpaceSdkApi import space.jetbrains.api.runtime.Space import space.jetbrains.api.runtime.helpers.RequestAdapter import space.jetbrains.api.runtime.helpers.SpaceHttpResponse import space.jetbrains.api.runtime.helpers.processPayload import space.jetbrains.api.runtime.ktorClientForSpace import space.jetbrains.api.runtime.types.InitPayload import space.jetbrains.api.runtime.types.MenuActionPayload import space.jetbrains.api.runtime.types.RefreshTokenPayload import space.jetbrains.api.runtime.SpaceAppInstance import space.jetbrains.api.runtime.helpers.SpaceAppInstanceStorage // we use in-memory storage for storing Space instances // in real life, use a persistent storage, e.g., a database val spaceInstances = HashMap<String, SpaceAppInstance>() object AppInstanceStorage : SpaceAppInstanceStorage { override suspend fun loadAppInstance(clientId: String): SpaceAppInstance? { return spaceInstances[clientId] } override suspend fun saveAppInstance(appInstance: SpaceAppInstance) { spaceInstances[appInstance.clientId] = appInstance } } val ktorClient = ktorClientForSpace() class KtorRequestAdapter(private val call: ApplicationCall) : RequestAdapter { override suspend fun receiveText() = call.receiveText() override fun getHeader(headerName: String) = call.request.headers[headerName] override suspend fun respond(httpStatusCode: Int, body: String) { call.respond(HttpStatusCode.fromValue(httpStatusCode), body) } } fun Routing.routes() { post("api/myapp") { Space.processPayload(KtorRequestAdapter(call), ktorClient, AppInstanceStorage) { payload -> // analyze payload type when (payload) { is InitPayload -> { // initialize the app... SpaceHttpResponse.RespondWithOk } is MenuActionPayload -> { // react to menu item click // val result = ... SpaceHttpResponse.RespondWithResult(result) } is RefreshTokenPayload -> { // save refresh token... SpaceHttpResponse.RespondWithOk } else -> { SpaceHttpResponse.RespondWithOk } } } } }

In a more generic approach, you can use only the readPayload(body: String): ApplicationPayload SDK helper function to handle payload:

fun main() { embeddedServer(Netty, port = 8080) { routing { post("/api/from-space") { val body = call.receiveText() val payload = readPayload(body) // analyze payload type when (payload) { is MessagePayload -> { println("This is MessagePayload") call.respond(HttpStatusCode.OK, "") } else -> call.respond(HttpStatusCode.BadRequest, "Unsupported payload type") } } } }.start(wait = true) }

Common payload data

Regardless of the type, the payload that comes from Space always contains some common information: user ID, server URL, and other. To help you get this data, Space SDK provides a number of extension methods for the ApplicationPayload interface.

val payload = readPayload(body) // ID of a user who initiated the request // Not available for the payload types that // do not imply user interaction val userId = payload.userId // Client ID issued to the app // during the [[[app registration|https://www.jetbrains.com.cn/en-us/help/space/register-app-in-space.html]]] val clientId = payload.clientId // URL of your Space instance val url = payload.serverUrl // ID of your organization in Space val orgId = payload.orgId // Verification token // used to [[[verify Space in the app|https://www.jetbrains.com.cn/en-us/help/space/verify-requests-from-space.html]]] // null if you choose other verification way val token = payload.verificationToken
Last modified: 25 May 2023