> ## Documentation Index
> Fetch the complete documentation index at: https://agents.candu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get started with Candu Actions in 10 minutes

> Install the Candu Actions snippet, configure your first read and write actions, and trigger an AI-driven API call in your product in under 10 minutes.

<Note>
  **Already using Candu?** Candu Actions runs alongside the classic Candu SDK. If you have `candu.umd.js` installed for content rendering, you can add the Actions snippet below in the same app — both load from `cdn.candu.ai` and don't conflict. See the [classic Candu install guide](https://developers.candu.ai/docs/installing-candu).
</Note>

## What you'll see after install

With the snippet installed, open your app and type into the chat:

> "Create a segment of inactive enterprise users"

Candu Actions will match the request to your `segments_create` action, ask for any missing inputs one at a time, show a confirmation panel with the exact payload before anything fires, execute the POST to your API, and log the run. Nothing executes until the user confirms.

<Card title="See the full flow" icon="sparkles" href="/actions/create-segment">
  Watch the segment wizard end to end: every tool call, payload, and log.
</Card>

***

<Steps>
  <Step title="Add the snippet">
    Paste this into your app just before `</body>`. You only need to change four values: `clientToken`, `userId`, `identifiers`, and your auth header in `fetchFn`. The last two are optional.

    ```html theme={null}
    <script>
    (function initCanduGateway(params) {
      /* ... full gateway snippet ... */
    })({
      snippetVersion: "0.2.0",
      clientToken: "YOUR_CLIENT_TOKEN",   // from Candu Actions dashboard
      userId: "CURRENT_USER_ID",          // logged-in user's ID
      identifiers: {                      // optional — any runtime context the AI may need
        role: "admin",                    // controls role-based action access
        organizationId: "org-456",        // used in action endpoint templates
      },
      fetchFn: function (url, opts) {     // optional — only needed for auth headers/CSRF
        opts = opts || {};
        opts.headers = Object.assign({}, opts.headers, {
          "Authorization": "Bearer YOUR_TOKEN_HERE"
        });
        return fetch(url, opts);
      }
    });
    </script>
    ```

    <Tip>
      Your `clientToken` is in the Candu Actions dashboard under Settings → Installation. Your `userId` should match the identifier you use to identify users elsewhere in your product.
    </Tip>

    <Note>
      Candu Actions executes actions inside your app using your authentication context. Your APIs are never called from an external service.
    </Note>

    <Accordion title="Full snippet (copy this into your app)">
      ```html theme={null}
      <script>
      (function initCanduGateway(params) {
        var SDK_SRC = "https://cdn.candu.ai/agentik/agentik-sdk.js";
        var CONFIG_BASE = "https://api.candu.ai/api/agentik/available-actions";

        function invariant(value, message) {
          if (typeof value !== "string" || value.length === 0)
            throw new Error(message);
          return value;
        }

        params = params || {};
        var userId = invariant(params.userId, "[Candu] userId is required");
        var clientToken = invariant(params.clientToken, "[Candu] clientToken is required");
        var snippetVersion = invariant(params.snippetVersion, "[Candu] snippetVersion is required");
        var fetchFn = typeof params.fetchFn === "function" ? params.fetchFn : null;
        var actionRegistry = {};

        function loadSdk() {
          if (window.canduAgentik && typeof window.canduAgentik.init === "function")
            return Promise.resolve();
          return new Promise(function (resolve, reject) {
            var script = document.createElement("script");
            script.src = SDK_SRC;
            script.async = true;
            script.setAttribute("data-candu-agentik-sdk", "true");
            script.addEventListener("load", resolve);
            script.addEventListener("error", function () {
              reject(new Error("SDK_LOAD_FAILED"));
            });
            document.head.appendChild(script);
          });
        }

        /* ... buildUrl, fetchActions, attachGatewayListener ... */

        Promise.all([loadSdk(), fetchActions()])
          .then(function () {
            attachGatewayListener();
            window.canduAgentik.init({ userId, clientToken, snippetVersion });
            window.canduAgentik.launchChat();
          })
          .catch(console.error);
      })({
        snippetVersion: "0.2.0",
        clientToken: "YOUR_CLIENT_TOKEN",
        userId: "CURRENT_USER_ID",
        fetchFn: function (url, opts) {
          opts = opts || {};
          opts.headers = Object.assign({}, opts.headers, {
            "Authorization": "Bearer YOUR_TOKEN_HERE"
          });
          return fetch(url, opts);
        }
      });
      </script>
      ```
    </Accordion>
  </Step>

  <Step title="Wire your auth (optional)">
    If your app uses session cookies, omit `fetchFn` entirely — the snippet includes `credentials: "include"` by default and no extra setup is needed. For bearer tokens, CSRF signatures, or custom headers, pass a `fetchFn` that returns a `fetch()` with the headers you need. Keep it short — it runs on every action call.

    ```js theme={null}
    fetchFn: function (url, opts) {
      opts = opts || {};
      opts.headers = Object.assign({}, opts.headers, {
        "Authorization": "Bearer " + myApp.getAuthToken()
      });
      return fetch(url, opts);
    }
    ```
  </Step>

  <Step title="Define your actions">
    Your action registry is a JSON file referenced by your `clientToken`. Each action maps to one API endpoint.

    <Frame caption="Each action has a description, role targeting, governance policy, and a Booster that controls how the AI calls it">
      <img src="https://mintcdn.com/candu/sDpAhmar-Rs5KeSS/images/Getting-started,-3-define-your-actions.png?fit=max&auto=format&n=sDpAhmar-Rs5KeSS&q=85&s=9e8ddb2ffc36d616ace77b253b5dffaf" alt="Getting Started, 3 Define Your Actions" width="1680" height="1647" data-path="images/Getting-started,-3-define-your-actions.png" />
    </Frame>

    ```json theme={null}
    {
      "version": "poc-1",
      "actions": [
        {
          "id": "segments_create",
          "name": "Create Segment",
          "description": "Create a new user segment with targeting rules.",
          "method": "POST",
          "endpoint": "/api/segments",
          "execution_policy": "confirm",
          "input_schema": {
            "type": "object",
            "properties": {
              "payload": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "description": { "type": "string" }
                },
                "required": ["name"]
              }
            }
          }
        }
      ]
    }
    ```

    <Tip>
      Set `execution_policy: "confirm"` on write actions where you want the user to review the payload before it fires. Not every write needs confirmation — use your judgement based on the risk of the action.
    </Tip>
  </Step>

  <Step title="See it work">
    Reload your app. The chat is now in the bottom right. Try the example from the top of this page.
  </Step>
</Steps>

## React and Next.js

The snippet works in any framework that can run a script tag. In React or Next.js, run it inside a `useEffect` in your root layout. Pass `clientToken`, `userId`, and your auth via `fetchFn` — same shape as the vanilla setup. Reach out if you want help with your specific framework.

<Tip>
  Both the chat widget and wizard UI run inside a shadow DOM, so your app's styles won't conflict with Candu's and vice versa. Wizards render inline; the chat widget renders as a floating panel.
</Tip>

<Note>
  **Now that the SDK is installed,** your team can start building wizards. Send your CX or product team to the [user-facing wizard documentation](https://docs.candu.ai/en/articles/14993518-what-is-a-wizard) to learn about configuring wizards in the Candu UI.
</Note>