Custom HTML

Instructions on how to create and use the Custom HTML Widget

Adding a Custom HTML Widget

1. Open the Widget Menu

   In the Edit Mode tab of the Dashboards Building Interface, click the “add a widget” button.

   
2. Select the Custom HTML Widget

   Choose the Custom HTML option from the widget list.

   
3. Rename the Widget

   In the sidebar in the top left corner, double-click on Untitled widget and provide a name for the selected widget.

   
4. Add HTML Content

   Enter your HTML content (including <script> and <styles> tag). The HTML you add will automatically appear in the HTML widget. Select the icon in the top-right corner of the custom HTML widget to view it in full screen.

   Note:The HTML widget supports both static and dynamic HTML

   If your HTML widget makes HTTP requests, see the next section, Making HTTP Requests in the Custom HTML Widget, to learn how it works.

   When exporting an HTML widget that contains dynamic content (such as animations, delayed rendering, or asynchronously loaded elements), add the following code to your script once all content has fully loaded and finished rendering:

   parent.postMessage('html-widget:ready', '*');

   This signals that the widget is ready to be captured, helping ensure the exported screenshot includes the fully rendered content.

   

---

Making HTTP Requests in the Custom HTML Widget

The Custom HTML Widget lets you make HTTP requests directly from your dashboard, either to Blink’s APIs or to third-party vendor APIs. For example, you can add a button that fetches data from a vendor and displays the response inside the widget.

Note: To make HTTP requests, you must follow the configuration and syntax rules described below. Requests that don’t follow this exact format are ignored.

What’s Always Required and What Varies

The exact configuration and syntax of your request varies depending on the HTTP request you want to send: the vendor, the api, the endpoint, and the method all determine which fields you need. Some parts, however, are the same for every request.

Always required, for every request:

• Preview mode: requests only run when the dashboard is in Preview mode.
• A request message sent with window.parent.postMessage(), with:
  • type: 'html-widget:execute'
  • a unique requestId
  • a payload containing url and method
• A message listener that checks for type: 'html-widget:execute-result' and the matching requestId, and handles both success and failure.

Varies by request (optional):

• connection: when the request needs to authenticate through one of your workspace connections, for example, to call a vendor’s API or Blink’s API. The connection must also be selected in the widget’s ‘Allowed Connections’ field. Requests to APIs that don’t need authentication can leave it out.
• Query parameters: when the endpoint accepts query parameters, such as filters, sorting, or paging, add them to the end of the url, for example ?sort=updated&per_page=10. There’s no separate field for query parameters.
• headers: when the endpoint expects extra headers, such as a specific Accept or Content-Type value.
• body: when the method sends data, typically POST, PUT, or PATCH. Always pass it as a JSON string.

To know which optional fields a request needs and what values they take, check the API documentation for the vendor and endpoint you are calling.

How It Works

1. Your widget sends a request message to Blink using window.parent.postMessage(), with the type html-widget:execute.
2. Blink executes the HTTP request. If the request includes a connection, Blink uses that connection to authenticate.
3. Blink sends the result back to your widget as a message with the type html-widget:execute-result.
4. Your widget listens for that message, matches it to the original request using the requestId, and displays the result.

Important to Note:

• HTTP requests only run in Preview mode. They don’t run in Edit Mode, so switch to Preview to test your widget’s requests.
• Any user with the dashboard:view or dashboard:edit permission can trigger the widget’s HTTP requests. Requests that include a connection run through that connection.

Configuration and Syntax Rules

If your request uses a connection, complete the following steps. Requests that don’t use a connection, such as calls to public APIs that don’t require authentication, can skip these steps and leave connection out of the payload.

1. Create a Connection

   Create a connection for the vendor you want to call (for example, GitHub) in your workspace. The connection provides the authentication for every request made through it.

2. Select the Connection in the Widget

   In the widget’s sidebar, below HTML Content, open the Allowed Connections dropdown and select the connection you want the widget to use. You can search for a connection, and select more than one if your widget calls several vendors.

   Important: Whenever a request includes a connection, that connection must be selected in the Allowed Connections field. A widget can only use connections that are selected here, so requests that reference an unselected connection fail.

   
3. Reference the Connection in Your HTML

   In your script, set the connection key value of the request payload to the connection’s name, for example, connection: 'my_blink_connection'.

   To find the name to use, hover over the connection in the Allowed Connections field. The tooltip shows the connection name. Always use the name from the tooltip, not the display name shown in the dropdown. For example, My Blink Connection is referenced as my_blink_connection. Copy it exactly as it appears in the tooltip.

   Note: Selecting a connection in the Allowed Connections field authorizes the widget to use it. Only selected connections can be used in your HTML, so if a connection isn’t selected, any request that references its name fails.

   Important: If a connection is renamed or deleted, the widget’s requests stop working. If it’s renamed, update the connection value in your HTML to the new name from the tooltip. If it’s deleted, select another connection in the Allowed Connections field and update the connection value to its name.

   

Sending a Request

To send a request, call window.parent.postMessage() with a request message:

window.parent.postMessage({
  type: 'html-widget:execute',
  requestId: pendingRequestId,
  payload: {
    connection: 'my_github_connection',
    url: 'https://api.github.com/user',
    method: 'GET',
  },
}, '*');

Request Message Fields

Field	Required	Description
type	Yes	Must be exactly 'html-widget:execute'. This value is case-sensitive. Messages with any other type aren’t treated as HTTP requests.
requestId	Yes	A unique ID for this request. Blink returns the same ID in the result, so you can match each result to the request that triggered it. Generate a new ID for every request, for example with crypto.randomUUID().
payload	Yes	An object that describes the HTTP request. See the payload fields below.

The second argument of postMessage(), the target origin, must be '*'.

Payload Fields

Field	Required	Description
connection	Only if the request uses a connection	The connection name, exactly as shown in the tooltip when you hover over the connection in the Allowed Connections field. The connection must be selected in the widget, and it must belong to the vendor whose API you’re calling.
url	Yes	The full, exact API URL of the endpoint you’re calling, including https:// (for example, https://api.github.com/user). Include any query parameters in the URL itself (for example, https://api.github.com/user/repos?sort=updated&per_page=10). If the request uses a connection, it must be the API URL of that connection’s vendor.
method	Yes	The HTTP method, in uppercase: GET, POST, PUT, PATCH, or DELETE.
headers	No	Additional request headers, as an object of key-value pairs. If the request uses a connection, don’t add authentication headers; the connection supplies authentication.
body	No	The request body, for methods such as POST, PUT, and PATCH. It must be a JSON string, not an object: wrap the JSON in single quotes and use double quotes inside it, for example '{"title": "New issue"}'.

Note: Query parameters are passed in the url, not as a separate payload field. If a value contains spaces or special characters, encode it with encodeURIComponent(), for example '?q=' + encodeURIComponent('status = "open"').

Examples by Request Type

The required fields are the same in every request. What changes is the method and the optional fields the endpoint needs.

GET

A GET request with only the required fields:

window.parent.postMessage({
  type: 'html-widget:execute',
  requestId: crypto.randomUUID(),
  payload: {
    connection: 'my_github_connection',
    url: 'https://api.github.com/user',
    method: 'GET',
  },
}, '*');

GET with query parameters

A GET request that adds query parameters to the URL to sort and limit the results:

window.parent.postMessage({
  type: 'html-widget:execute',
  requestId: crypto.randomUUID(),
  payload: {
    connection: 'my_github_connection',
    url: 'https://api.github.com/user/repos?sort=updated&per_page=10',
    method: 'GET',
  },
}, '*');

POST with headers and body

A POST request that sends data in the body and sets a header the endpoint expects:

window.parent.postMessage({
  type: 'html-widget:execute',
  requestId: crypto.randomUUID(),
  payload: {
    connection: 'my_github_connection',
    url: 'https://api.github.com/repos/OWNER/REPO/issues',
    method: 'POST',
    headers: {
      Accept: 'application/vnd.github+json',
    },
    body: '{"title": "Issue created from a Blink dashboard", "body": "Details about the issue."}',
  },
}, '*');

Note: In your widget, store the requestId in a variable before sending the request (as in the full example), so your listener can match the result to it.

Making Requests to Blink’s APIs

You can also use the widget to call Blink’s REST API, for example, to read records from a table or to run a workflow. Requests to Blink’s APIs follow the same rules as any other request, with these specifics:

• Connection: you need a Blink connection, selected in the widget’s Allowed Connections field. As with any connection, reference it by the name in its tooltip. For example, My Blink Connection is referenced as my_blink_connection.
• URL: use your Blink environment’s API address followed by the endpoint path, in the format https://<your-blink-domain>/api/v1/<endpoint-path>. The default domain is app.blinkops.com. It must match the API address configured in your Blink connection.
• IDs: endpoints usually include IDs, such as your workspace ID, a table name, or a workflow ID. See the API reference for each endpoint’s path, parameters, and body.

The following example shows a widget that reads records from a Blink table, with My Blink Connection selected in the widget’s Allowed Connections field and referenced in the HTML as my_blink_connection:

List table records (GET)

Lists records from a table, using the q query parameter in the URL to filter them with RQL. The RQL query is encoded with encodeURIComponent() because it can contain spaces and special characters. See List Records from Table.

window.parent.postMessage({
  type: 'html-widget:execute',
  requestId: crypto.randomUUID(),
  payload: {
    connection: 'my_blink_connection',
    url: 'https://app.blinkops.com/api/v1/workspace/<WORKSPACE_ID>/table/<TABLE_NAME>?q=' + encodeURIComponent('<RQL_QUERY>'),
    method: 'GET',
  },
}, '*');

Run a workflow (POST)

Runs a workflow with input values and waits for its output. See Execute a Playbook.

window.parent.postMessage({
  type: 'html-widget:execute',
  requestId: crypto.randomUUID(),
  payload: {
    connection: 'my_blink_connection',
    url: 'https://app.blinkops.com/api/v1/workspace/<WORKSPACE_ID>/playbooks/<WORKFLOW_ID>/execute?run_sync=true',
    method: 'POST',
    body: '{"input_values": {"<INPUT_NAME>": "<INPUT_VALUE>"}}',
  },
}, '*');

Tip: To try a Blink API request, use the full example and replace its payload with one of the payloads above.

Receiving the Response

To receive the result, add a message event listener to the window:

window.addEventListener('message', (event) => {
  const msg = event.data;
  if (msg?.type !== 'html-widget:execute-result' || msg.requestId !== pendingRequestId) return;

  pendingRequestId = null;
  button.disabled = false;

  if (msg.success) {
    status.className = 'success';
    status.textContent = 'Succeeded at ' + new Date().toLocaleTimeString();
    responseBox.textContent = JSON.stringify(msg.data, null, 2);
  } else {
    status.className = 'error';
    status.textContent = 'Failed at ' + new Date().toLocaleTimeString();
    responseBox.textContent = msg.error;
  }
});

The widget can receive messages from other sources too, so the listener’s first line is required: it ignores any message whose type isn’t 'html-widget:execute-result', or whose requestId doesn’t match the request you’re waiting for.

Result Message Fields

Field	Description
type	Always 'html-widget:execute-result'.
requestId	The requestId from the request this result belongs to.
success	true if the request succeeded. false if it failed, including when the API returns an error status code (4xx or 5xx).
data	The response returned by the API, always as JSON. Only present when success is true.
error	A message describing what went wrong. Only present when success is false.

Syntax Rules

Follow these rules in every widget that makes HTTP requests:

• Send requests with window.parent.postMessage(). This is how the widget passes the request to Blink to run, through your connection if the request includes one.
• Use the exact message types. Send requests with type: 'html-widget:execute' and listen for type: 'html-widget:execute-result'.
• Generate a new requestId for every request. Reusing an ID makes it impossible to tell which result belongs to which request.
• Register the message listener before sending a request, so the widget is ready when the result arrives.
• Always check both type and requestId at the start of your listener, and ignore any message that doesn’t match.
• Handle both outcomes. Check msg.success, and display msg.data on success or msg.error on failure.
• Pass body as a JSON string. Wrap it in single quotes, with double quotes inside, for example '{"key": "value"}'.
• Never put credentials in your HTML. If the API requires authentication, use a connection instead.

Tip: To prevent duplicate requests, disable the button that triggers the request while it’s pending, and re-enable it when the result arrives, as shown in the example below.

Full Example

The following widget displays an Execute Request button. When clicked, it calls the GitHub API through the my_github_connection connection, shows the request status, and displays the response or error.

Full HTML Example

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Execute Request</title>
  <style>
    body { margin: 0; padding: 24px; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; color: #1F2328; }
    button { padding: 10px 20px; font-size: 14px; font-weight: 600; color: #fff; background: #4F46E5; border: none; border-radius: 6px; cursor: pointer; }
    button:hover { background: #4338CA; }
    button:disabled { background: #A5A3F0; cursor: default; }
    #status { margin-top: 12px; font-size: 13px; color: #57606A; }
    #status.success { color: #1A7F37; }
    #status.error { color: #CF222E; }
    #response { margin-top: 12px; padding: 12px; max-height: 400px; overflow: auto; font-size: 12px; background: #F6F8FA; border: 1px solid #D0D7DE; border-radius: 6px; white-space: pre-wrap; word-break: break-word; }
    #response:empty { display: none; }
  </style>
</head>
<body>
  <button id="executeBtn" type="button">Execute Request</button>
  <div id="status"></div>
  <pre id="response"></pre>

  <script>
    const button = document.getElementById('executeBtn');
    const status = document.getElementById('status');
    const responseBox = document.getElementById('response');
    let pendingRequestId = null;

    // 1. Listen for results from Blink
    window.addEventListener('message', (event) => {
      const msg = event.data;
      if (msg?.type !== 'html-widget:execute-result' || msg.requestId !== pendingRequestId) return;

      pendingRequestId = null;
      button.disabled = false;

      if (msg.success) {
        status.className = 'success';
        status.textContent = 'Succeeded at ' + new Date().toLocaleTimeString();
        responseBox.textContent = JSON.stringify(msg.data, null, 2);
      } else {
        status.className = 'error';
        status.textContent = 'Failed at ' + new Date().toLocaleTimeString();
        responseBox.textContent = msg.error;
      }
    });

    // 2. Send a request when the button is clicked
    button.addEventListener('click', () => {
      pendingRequestId = crypto.randomUUID();
      button.disabled = true;
      status.className = '';
      status.textContent = 'Sending...';
      responseBox.textContent = '';

      window.parent.postMessage({
        type: 'html-widget:execute',
        requestId: pendingRequestId,
        payload: {
          connection: 'my_github_connection',
          url: 'https://api.github.com/user',
          method: 'GET',
        },
      }, '*');
    });
  </script>
</body>
</html>

---

How the Example Works

Part of the example	Required?	What it does
let pendingRequestId = null;	Yes	Stores the ID of the request that’s waiting for a result.
window.addEventListener('message', ...)	Yes	Receives the result from Blink. It’s registered when the page loads, before any request is sent.
if (msg?.type !== ... || msg.requestId !== pendingRequestId) return;	Yes	Ignores any message that isn’t the result of the pending request.
if (msg.success) { ... } else { ... }	Yes	Displays msg.data when the request succeeds, or msg.error when it fails.
pendingRequestId = crypto.randomUUID();	Yes	Creates a unique ID for each new request.
window.parent.postMessage({ type: 'html-widget:execute', ... }, '*')	Yes	Sends the request to Blink.
button.disabled = true / false	Recommended	Prevents duplicate requests while one is pending.
status and responseBox elements	Optional	Show the request’s progress and its result. Replace these with any UI that suits your widget.
<style> block	Optional	Styles the widget.

To adapt the example, change the payload values: set connection to your connection’s name (or remove it if the request doesn’t need a connection), url to the endpoint you want to call, and method to the HTTP method the endpoint expects.

---

Troubleshooting

Problem	What to check
Nothing happens after the request is sent	Check that the dashboard is in Preview mode; requests don’t run in Edit Mode. Then check that type is exactly 'html-widget:execute', and that the listener checks for 'html-widget:execute-result'.
The result arrives but isn’t displayed	Check that the requestId you compare against is the same ID you sent, and that you generate it before calling postMessage().
success is false	Read msg.error. If the request uses a connection, check that the connection is selected in the widget’s Allowed Connections field, that the connection value matches the name in the connection’s tooltip exactly, and that the connection has the permissions the endpoint requires.
Requests stopped working after a connection changed	If the connection was renamed, update the connection value to the new name from its tooltip. If it was deleted, select another connection in the Allowed Connections field and update the connection value.
The vendor returns an authentication error	Check that the url is the exact API URL of the connection’s vendor, and that the connection’s credentials are still valid.

Tip: If you use an AI assistant to generate your widget’s HTML, include the rules on this page in your prompt, so the generated code uses the correct message format.

---

Editing a HTML Widget

Any changes made to the HTML, will be automatically applied to the HTML widget in real time.

---

Deleting a HTML Widget

1. Select the HTML Widget

   In the left-hand sidebar, click the icon in the top-right corner and then select the delete button.

2. Delete the HTML Widget

   The HTML widget will be removed from your Dashboard Building Interface.

   

---

Duplicate Widget

1. Select the HTML Widget

   In the left-hand sidebar, click the icon in the top-right corner and then select the duplicate button.

   
2. Duplicate the HTML Widget

   The HTML widget will be duplicated