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, this is the case for chatbots or slash commands (Space sends user input), webhooks (Space sends payload with event details), and some other types of applications.

Payload contents

A 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.

ClassDescriptionRelevant for
InitPayload

Not yet available

Initializes the application that was installed from Space Marketplace.

Applications distributed through Space Marketplace.
ListCommandsPayloadRequests a list of available commands. Space sends this type of payload when a user types slash / in a chat. The application must respond with a JSON list of commands.Chatbots, slash commands.
ListMenuExtensionsPayload

Not yet available

Requests a list of available menu commands. Space sends this type of payload when a user opens a particular menu. The application must respond with a JSON list of menu items.

Applications that extend a particular Space menu with custom items.
MenuActionPayload

Not yet available

Contains info about the menu item selected by a user.

Applications that extend a particular Space menu with custom items.
MessagePayloadContains message sent by a user to the application from a particular chat.Chatbots, slash commands.
MessageActionPayloadContains info about the action executed by a user in a particular chat. Typically, this is a result of user interaction with a UI element in a chat message, for example, clicking a button.Chatbots, slash commands.
WebhookRequestPayloadContains 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 read the payload data, Space SDK provides the readPayload helper function:

readPayload(body: String): ApplicationPayload

The function reads the request body and returns an instance of ApplicationPayload. Typically, your task is to process the payload depending on its type. For example, this is how you can do this in a Ktor application:

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/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/help/space/verify-requests-from-space.html]]] // null if you choose other verification way val token = payload.verificationToken
Last modified: 06 August 2021