Skip to main content

​
Remote Block

The remote_block fetches BlockKit JSON from a URL and renders it inline. This enables dynamic, server-driven content within a BlockKit layout — dashboards, live status panels, personalized widgets, or any content that needs to come from an API.

​
JSON Structure

{
  "type": "remote_block",
  "url": "https://api.example.com/blockkit/dashboard",
  "method": "GET",
  "data": {
    "user_id": "{user_id}",
    "org": "{org_name}"
  },
  "headers": {
    "X-API-Key": "{api_key}"
  },
  "refresh_interval": 30,
  "loader": {
    "enabled": true,
    "text": "Loading dashboard...",
    "spinner_size": "medium",
    "overlay": false
  },
  "error_behavior": "show_fallback",
  "fallback": [
    { "type": "alert", "severity": "warning", "text": "Dashboard is temporarily unavailable." }
  ]
}

​
Properties

PropertyTypeRequiredDefaultDescription
type"remote_block"Yes—Block type identifier
urlstringYes—URL to fetch BlockKit content from. Supports {variable} substitution.
method"GET" | "POST"No"GET"HTTP method. GET appends data as query params; POST sends as JSON body.
dataRecord<string, string>No{}Key-value pairs. Sent as query params (GET) or JSON body (POST). Values support {variable} syntax.
headersRecord<string, string>No{}Custom HTTP headers. Values support {variable} syntax.
refresh_intervalnumberNo—Auto-refresh interval in seconds. Minimum 5 seconds. Omit or set to 0 for fetch-once.
cache_keystringNo—Deduplication key. Two remote blocks with the same cache_key share a single request.
loaderobjectNoSee belowLoading state configuration.
error_behavior"show_error" | "show_fallback" | "hide"No"show_error"What to render when the fetch fails.
fallbackBlockElement[]No[]Blocks to render when error_behavior is "show_fallback".

​
Loader Properties

PropertyTypeDefaultDescription
enabledbooleantrueShow a loading spinner. Set false to load silently.
textstring"Loading..."Text displayed next to the spinner.
spinner_size"small" | "medium" | "large""medium"Spinner size.
overlaybooleanfalseWhen true and auto-refreshing, shows a translucent overlay spinner over existing content instead of replacing it. Prevents content flash on refresh.

​
Server Response Format

The endpoint must return JSON. Three formats are accepted:

​
Array of blocks

[
  { "type": "heading", "level": 2, "text": "Dashboard" },
  { "type": "text", "text": "Last updated: 2 minutes ago" }
]

​
Wrapped with scoped replacements

{
  "blocks": [
    { "type": "text", "text": "Welcome, {remote_user}!" }
  ],
  "replacements": {
    "remote_user": "Jason"
  }
}
Scoped replacements are merged with the parent context and only apply within the remote block’s rendered content.

​
Single block

{ "type": "alert", "severity": "info", "text": "System operational" }

​
Variable Substitution

The url, data values, and headers values all support {variable} substitution from the parent replacements context: 
{
  "type": "remote_block",
  "url": "https://api.example.com/users/{user_id}/widgets",
  "data": {
    "locale": "{user_locale}",
    "theme": "{app_theme}"
  }
}

​
Error Handling

error_behaviorBehavior
"show_error"Displays an error alert with the failure message and URL
"show_fallback"Renders the fallback blocks array
"hide"Renders nothing

​
Auto-Refresh

Set refresh_interval to automatically re-fetch content on a timer: 
{
  "type": "remote_block",
  "url": "https://api.example.com/live-stats",
  "refresh_interval": 10,
  "loader": {
    "overlay": true,
    "text": "Refreshing..."
  }
}
With overlay: true, the existing content stays visible with a translucent spinner overlay during refresh — no content flash. Minimum interval is 5 seconds to prevent accidental high-frequency polling.

​
Builder

In the WYSIWYG builder:
  • Library: Drag “Remote Block” from the Layout category
  • Properties panel: Configure URL, method, data parameters (key-value editor), headers (key-value editor), refresh interval, loader settings, error behavior, cache key
  • Canvas: Shows a placeholder card (no fetch in edit mode) displaying the configured URL and method
  • Fallback editor: Toggle between “Preview Card” and “Fallback” views. The Fallback view is a full drag-and-drop editor for the fallback content blocks.
  • Preview mode: Performs the live fetch and renders the remote content

​
Example: Live Dashboard Widget

{
  "type": "remote_block",
  "url": "https://api.example.com/blockkit/dashboard",
  "method": "GET",
  "data": {
    "org_id": "{org_id}"
  },
  "refresh_interval": 30,
  "loader": {
    "enabled": true,
    "text": "Loading dashboard...",
    "spinner_size": "medium",
    "overlay": true
  },
  "error_behavior": "show_fallback",
  "fallback": [
    {
      "type": "section",
      "elements": [
        { "type": "alert", "severity": "warning", "text": "Dashboard temporarily unavailable. Please try again later." }
      ]
    }
  ]
}