--- schema_version: "1" id: 06f51dbe1775b0087f27c8b18d6a22eaa0b35ea5d26ff85e9b9b97520bf1484d title: Surface Components collection: developer version: current locale: en-us portal_url: https://docs.salesforce.com/developer/current/en-us/salesforce-slack-sdk/apex-slack-sdk/guides/components/surface.md canonical_url: https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/surface.html source_site: developer.salesforce.com content_type: documentation content_hash: afa95e39b893c8497b8166b993ba263a132a2b30c55658431ca2f6f571187208 products: - Apex SDK for Slack (Beta) --- # Surface Components The root component of a view containing layout components. You can add components to these surfaces: the Home tab, messages, and modals. ## Home The Home tab is a persistent, dynamic interface for apps. Present each of your users with a unique Home tab just for them, always found in the same place. The Home tab is a space you can fully customize in your app, complete with intricate layouts and deep interactivity. A single API endpoint handles building and updating the Home tab. See [Home is where the tabs are](https://api.slack.com/surfaces/tabs). Publish views to the app's home tab in Slack using Slack.BotClient. See [Access a Slack Client](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/build/actions_register.md#access-a-slack-client). **warning:** Apex SDK for Slack is subject to Slack's block limit, which is 100 blocks in a the Home tab. If you are displaying Salesforce record data that exceeds 100 blocks, we recommend that you provide a button or link that directs a user back to Salesforce for a complete view. ![Home tab example](https://developer.salesforce.com/media/home.png) **Examples** This example creates a header and section for the Home tab. ```yaml components: - definition: home components: - definition: header properties: text: "Our App" - definition: section properties: text: type: "mrkdwn" text: "Our app helps you take off. :rocket:" - definition: divider - definition: section properties: text: "For more information, check out the example." components: - definition: button properties: name: "my_button" label: "Click Me" url: "https://www.example.com" ``` This example creates some text, a header, and several buttons for the Home tab. ```yaml description: "This is a simple app home" schema: properties: bodyText: type: string required: true headerText: type: string defaultValue: "Welcome Home" components: - definition: home components: - definition: header properties: text: "{!view.properties.headerText}" - definition: section properties: text: type: "mrkdwn" text: "{!view.properties.bodyText}" - definition: divider - definition: actions components: - definition: button properties: label: "Click Me" name: "homeButton" value: "someData" events: onclick: definition: "apex__action__HandleClick" - definition: button properties: label: "View Opportunity" name: "opptyButton" events: onclick: definition: "apex__action__ViewRecord" properties: objectApiName: "Opportunity" recordId: "006R0000003FpnmIII" ``` **Keys** | Key | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------- | | `definition` | String | Yes | The value must be `home`. | | `components` | Array | Yes | An array of [layout components](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/layout.md). | ## Message Messages are one of the basic ingredients of Slack apps. Compose them, send them, retrieve them, update them, delete them. Send messages to a channel using `Slack.BotClient` and `Slack.UserClient`. See [Access a Slack Client](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/build/actions_register.md#access-a-slack-client). **warning:** Apex SDK for Slack is subject to Slack's block limit, which is 50 blocks in a message. If you are displaying Salesforce record data that exceeds 50 blocks, we recommend that you provide a button or link that directs a user back to Salesforce for a complete view. ![Message example](https://developer.salesforce.com/media/message.png) **Examples** This example creates a message with a header and a section containing some text. ```yaml components: - definition: message properties: text: "All your tasks are completed." components: - definition: header properties: text: "Daily Tasks" - definition: section properties: text: type: "mrkdwn" text: "You've completed all your tasks today. :tada:" ``` This example creates a message with a header and a button that opens a URL. ```yaml description: "This is the app welcome message." schema: properties: homeLink: type: string required: true components: - definition: message properties: text: "This is the app welcome message." components: - definition: header properties: text: "Welcome!" - definition: actions components: - definition: button properties: name: "visit_home_button" label: "Visit the Home Page" url: "{!view.properties.homeLink}" ``` **Keys** | Key | Type | Required | Description | | ----------------- | --------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `definition` | String | Yes | The value must be `message`. | | `properties` | Object | No | The component's properties. | | `properties.text` | String, [Expression](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/build/expressions.md) | No | When you use components in a message payload, `text` becomes a fallback message displayed in notifications. Use components to define everything else about the visible message. | | `components` | Array | No | An array of [layout components](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/layout.md) to render as the message. | ## Modal Modals are focused spaces to request and collect data from users, or to temporarily display dynamic and interactive information. Modals are the Slack app equivalent of alert boxes, pop-ups, or dialog boxes. They capture and maintain focus within Slack until the user submits or dismisses the modal. Compose a modal using visual and interactive components. If you're not familiar with a modal's lifecycle in a Slack app, see [Modals: focused spaces for user interaction](https://api.slack.com/surfaces/modals). Modals can handle these interaction payloads. - `block_actions`—Received when a user interacts with a component - `view_submission`—Received when a user submits a view in a modal. - `view_closed`—Received when a user dismisses a modal. To receive these payloads, the modal view must have been created with the `notify_on_close` argument set to `true`. Payloads include a `trigger_id` that you must use to respond back with a modal. Slack has a 3-second expiration on the `trigger_id`. But what if you're making an API call to fetch some data? A request could exceed this 3-second timeout. To satisfy the 3-second ack rule and work with modals, use the `Slack.ActionHandler` Apex class. [`Slack.ActionHandler`](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/apex_ref/apex_ref_dispatchers.md#actionhandler-class) has a number of methods to help you structure your handler. You can respond to Slack with a staging modal, which is a simple **Loading...** view. At this point, app code can take time to build up the actual modal view to show. **warning:** Apex SDK for Slack is subject to Slack's block limit, which is 100 blocks in a modal. If you are displaying Salesforce record data that exceeds 100 blocks, we recommend that you provide a button or link that directs a user back to Salesforce for a complete view. ![Modal example](https://developer.salesforce.com/media/modal.png) **Example** ```yaml components: - definition: modal properties: title: "Update Opportunity" submitLabel: "Update" closeLabel: "Cancel" events: onsubmit: definition: "apex__action__EditRecord" properties: recordId: "{!view.properties.recordId}" objectApiName: "Opportunity" oncancel: definition: "apex__action__CancelSave" properties: recordId: "{!view.properties.recordId}" objectApiName: "Opportunity" components: - definition: section properties: text: "Text Value" ``` **Keys** | Key | Type | Required | Description | | ---------------------------- | -------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------- | | `definition` | String | Yes | The value must be `modal`. | | `properties` | Object | Yes | The component's properties | | `properties.title` | String, [Plain Text](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/composition.md#plain-text), [Expression](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/build/expressions.md#expressions) | Yes | Title text for the modal | | `properties.submitLabel` | String, [Plain Text](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/composition.md#plain-text), [Expression](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/build/expressions.md#expressions) | No | A label for the submit button | | `properties.closeLabel` | String, [Plain Text](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/composition.md#plain-text), [Expression](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/build/expressions.md#expressions) | No | A label for the close button | | `components` | Array | No | An array of [layout components](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/layout.md) to render inside the modal. | | `events` | Object | No | The events on the modal that trigger [Actions](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/layout.md#actions) to execute. | | `events.onsubmit` | Object | No | An object that defines the action to take when the `onsubmit` event fires and the properties to pass to the action. | | `events.onsubmit.definition` | String | No | The [action](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/layout.md#actions) that executes when a user clicks the submit button. | | `events.onsubmit.properties` | Object | No | The properties to pass to the action. | | `events.oncancel` | Object | No | An object that defines the action to take when the `oncancel` event fires and the properties to pass to the action. | | `events.oncancel.definition` | String | No | The [action](https://developer.salesforce.com/docs/platform/salesforce-slack-sdk/guide/layout.md#actions) that executes when a user clicks the cancel button. | | `events.oncancel.properties` | Object | No | The properties to pass to the action. | ## See Also - [Creating useful dialogs](https://api.slack.com/best-practices/creating-useful-dialogs) - [Interacting with users through dialogs](https://api.slack.com/dialogs)