Calling from Widget Code

Call a connector by its permalink using the SDK. Import connectors from @gainsight-hub/sdk (how the import works). The SDK sends the request to the backend connector instead of calling the destination API directly. See the connectors reference for the full API.

Call a connector

Use 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).

In a widget, keep the import line at the top of the module script and put the call inside init(sdk). A sitewide script registered with "type": "module" can use the snippets unchanged (see SDK).

A connector's permalink identifies a destination the community admin has already configured — including the target API and its credentials. Your widget code only references the permalink; it never chooses the destination or manages authentication for it.

GET with query parameters

import { connectors } from "@gainsight-hub/sdk";

try {
  const data = await 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

import { connectors } from "@gainsight-hub/sdk";

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

Pass the request body via payload, not body

The request body goes in the payload option as a plain JSON object. body is not a recognized option — and execute() silently ignores any option it does not recognize, so a call using body sends an empty request body.

See more usage patterns in SDK 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.

Common mistakes

These patterns compile but fail at runtime or in production.

Wrong	Why it fails
fetch("https://api.example.com/...")	A raw fetch() to an external domain is blocked in production. The platform sets no explicit connect-src in its Content-Security-Policy, so connect-src falls back to default-src 'self' — same-origin requests only. Route every external call through connectors.execute(...) instead, which proxies the request server-side.

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

• SDK 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