Calling from Widget Code

Call a connector by its permalink using the SDK. The SDK sends the request to the backend connector instead of calling the destination API directly.

Load the SDK

The SDK is not auto-injected — you must include the <script> tag in your widget HTML before any code that uses it. Place it at the top of your file. The browser runs <script> tags in order, so window.WidgetServiceSDK is ready in any script block that follows. See the Widget SDK overview for the current script tag.

Pin the SDK version in production

The latest path always loads the most recent SDK version, which can introduce breaking changes. For production widgets, use a specific version number instead of latest in the URL.

Call a connector

Use sdk.connectors.execute() with the connector's permalink. The method parameter must match the HTTP method configured on the connector (GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS).

The (async () => { ... })(); wrapper is required because widget <script> tags are not ES modules — top-level await is only available in <script type="module">.

GET with query parameters

(async () => {
  const sdk = new window.WidgetServiceSDK();
  try {
    const data = await sdk.connectors.execute({
      permalink: "weather-api",
      method: "GET",
      queryParams: {
        q: "Warsaw"
      }
    });
    console.log(data);
  } catch (error) {
    console.error("Connector request failed:", error);
  }
})();

POST with JSON body

(async () => {
  const sdk = new window.WidgetServiceSDK();
  try {
    const result = await sdk.connectors.execute({
      permalink: "plantbook",
      method: "POST",
      payload: { name: "Monstera", size: "M" }
    });
    console.log(result);
  } catch (error) {
    console.error("Connector request failed:", error);
  }
})();

See more usage patterns in Examples.

Never pass user identity from browser code

Data sent from the browser — including queryParams and payload — can be modified by the user. Never pass user IDs, emails, or other identity data as SDK parameters. Instead, use server-side template variables like {{ user.id }} in the connector configuration. See Passing User Context for the secure pattern.

Working with the response

Widget code runs inside Shadow DOM. If you update the DOM after a connector call, query elements through the widget's shadow root, not document. See Rendering & DOM.

Next Steps

• Examples — More usage patterns and advanced options
• Passing User Context — Securely inject user identity into requests
• Testing & Debugging — Verify your connector works and diagnose issues
• Template Variables — Variables and functions available in templates