---
name: gtwy-embed-integration
description: Guide for integrating GTWY's embedded panel (agents, configuration, model settings, workflows) into a user's own app or website. Use this skill whenever the user mentions "GTWY", "gtwy embed", third-party agent embedding for GTWY specifically, embedding an AI agent panel via GTWY, generating a GTWY embed token/JWT, or asks to add a script tag / window.GtwyEmbed calls to their frontend. Also trigger if the user asks about GTWY events (agent drafted/published), GTWY folder access limits, or the GTWY getAgents API — even if they don't say the word "embed" explicitly.
---

# GTWY Embed Integration

GTWY lets another app embed its full interface (agents, configuration tools, model settings, workflows) inline, instead of redirecting users to a separate GTWY-hosted platform. Integrating it has three parts: (1) generate a signed embed token on the backend, (2) drop a script tag into the frontend, (3) control/listen to the embed with JS.

Always do backend token generation server-side — never expose the signing key (`GTWY_EMBED_TOKEN`) to the browser.

## 1. Generate the embed token (backend)

The embed token is a JWT signed with **HS256**, using the Access Key from the GTWY panel's Integration Setup (env var convention: `GTWY_EMBED_TOKEN`). Use the key as-is — no re-encoding.

Payload:

```json
{
  "org_id": "YOUR_ORG_ID",
  "folder_id": "YOUR_FOLDER_ID",
  "user_id": "YOUR_USER_ID"
}
```

| Field | Description |
| --- | --- |
| `org_id` | The org's unique ID — ask the user for this if not given |
| `folder_id` | Folder ID this embed should be scoped to — ask the user for this |
| `user_id` | A unique identifier for the end user (email, UUID, internal ID). If the calling app doesn't have an obvious one, ask what they'd like to use as the user id |

Generate this token fresh in the backend for each session/user (or reuse an existing valid one) — don't hardcode it in the frontend build.

## 2. Add the embed script (frontend)

There are two documented script variants — pick based on what the user's GTWY environment expects (dev vs. main), and don't silently merge attributes from both:

**Dev / parent-container variant** (renders in a specific container, or a slider if no `parentId` is given):

```html
<script
  id="gtwy-main-script"
  embedToken="YOUR_EMBED_TOKEN"
  src="https://gtwy.ai/gtwy.js"
  parentId="YOUR_PARENT_ID"
></script>
```

**Main variant** (opens by default if `defaultOpen` is set):

```html
<script
  id="gtwy-main-script"
  src="https://app.gtwy.ai/gtwy.js"
  embedToken="YOUR_EMBED_TOKEN"
  defaultOpen="true"
></script>
```

Rules that always apply:

- `id` must always be `gtwy-main-script`.
- `embedToken` is the JWT generated in step 1 (fetched from the backend at render time, not committed to source).
- If the user doesn't specify a container, GTWY opens in a slider by default.

## 3. Control the embed (frontend JS)

Two overlapping APIs are documented — `window.GtwyEmbed.*` and top-level `window.openGtwy`/`window.closeGtwy`. Prefer `window.GtwyEmbed.*` for new integrations since it's the more complete, current API; the top-level functions still work and may appear in older integrations.

```jsx
// Open / close
window.GtwyEmbed.open();
window.GtwyEmbed.close();
// equivalent older-style calls:
window.openGtwy();
window.closeGtwy();

// Open a specific agent
window.GtwyEmbed.open({ agent_id: "your_agent_id" });
window.openGtwy({ agent_id: "your_gtwy_agentid" });

// Create/navigate to an agent by name or purpose
window.openGtwy({ agent_name: "your gtwy agent name" });
window.openGtwy({ agent_purpose: "your agent purpose" });

// Open an agent and attach metadata
window.openGtwy({
  agent_id: "your_agent_id",
  meta: { key: "value" }
});

// Create/configure an agent + pass UI settings in one call
window.GtwyEmbed.sendDataToGtwy({
  agent_name: "New Agent",       // create a bridge with this name
  agent_id: "your_agent_id",     // or redirect to a specific existing agent
  agent_purpose: "your_agent_purpose", // create an agent with this purpose
  hideHomeButton: true,
  showGuide: false,
  showConfigType: false,
  meta: { key: "value" }
});
```

Use `sendDataToGtwy` when you want to both configure the agent and toggle UI chrome in a single call; use `openGtwy`/`GtwyEmbed.open` when you just need to open/navigate.

## 4. UI configuration options

These control what's visible inside the embedded interface. Toggle based on how much configuration control the host app wants to expose to its end users:

| Option | Description |
| --- | --- |
| Show Agent Type on Create Agent | Shows available agent types (Chatbot, API, Trigger, Batch) when creating a new agent |
| Show History | Displays conversation history logs inside the embed |
| Show Config Type | Shows the configuration type (API, Chatbot, Batch API, etc.) while modifying/creating an agent |
| Hide Advanced Parameters | Hides model tuning params (creativity, tool choice, etc.) |
| Hide Create Agent Manually Button | Removes manual agent creation from the embed |
| Hide Advanced Configurations | Hides fallback model, guardrails, model-switching logic, etc. |
| Hide Pre Tool | Hides the pre-tool configuration section |
| Default API Keys | Sets default API keys at the embed level |
| `meta` | Metadata saved on the agent |
| Show Variables, Show Agent Tone, Hide Prompt Helper, Migrate Prompt | Documented as available options; exact behavior wasn't specified in source material — confirm with GTWY docs/support if precise behavior matters for the integration |

**Display settings** (also documented without detailed descriptions — treat as available toggles, confirm exact behavior if it matters): Hide Profiles, Enable Logs, Hide All Access, Hide Chat Buttons, Hide Insights, Theme Mode, Add Schedule Deploy.

**Folder access control**: limit which folders an embed can reach via GTWY panel → Folders → Actions → Set Folder.

**Supported model providers** inside the embed: OpenAI, OpenRouter, Groq, Anthropic, Cohere, Gemini, xAI.

## 5. Fetch agents for a user

```bash
curl --location https://db.gtwy.ai/api/embed/getAgents \
  -H 'Authorization: your_embed_token'
```

Returns the agents associated with the user id embedded in the token used to authenticate.

## 6. Listen for GTWY events

```html
<script>
window.addEventListener('message', (event) => {
  if (event.data.type === 'gtwy') {
    console.log('Received gtwy event:', event.data);
  }
});
</script>
```

**Agent created (drafted)** — fires immediately after an agent is created, while still in draft mode:

```json
{
  "type": "gtwy",
  "status": "drafted",
  "data": { "agent_id": "agentId" },
  "message": "Agent created Successfully"
}
```

**Agent published** — fires when an agent is published:

```json
{
  "type": "gtwy",
  "status": "published",
  "data": {
    "name": "Chatbot_1",
    "agent_description": "",
    "agent_id": "agent_id",
    "agent_version_id": "versionId"
  },
  "message": "Agent Published Successfully"
}
```

(Source material didn't specify additional trigger conditions beyond "when published" — if the host app needs finer-grained timing, confirm with GTWY docs.)

## Common integration shape

When a user asks to "add GTWY to my app," walk through in this order:

1. Confirm what `org_id`/`folder_id` they have, and what `user_id` scheme makes sense for their app.
2. Write the backend endpoint that signs the HS256 JWT and returns it to the frontend.
3. Add the script tag with the token fetched from that backend endpoint.
4. Wire up open/close triggers (buttons, menu items) using `window.GtwyEmbed`.
5. Add the `message` event listener if the host app needs to react to agent creation/publishing (e.g., saving `agent_id` to its own database).
6. Only after the basic flow works, layer in UI configuration options and folder limits.

## Things to flag to the user rather than guess

- Exact behavior of the options marked "not described in source" above (Show Variables, Show Agent Tone, Hide Prompt Helper, Migrate Prompt, and the Display Settings list) — don't invent behavior for these.
- Whether they want `window.GtwyEmbed.*` (recommended) or the legacy top-level `window.openGtwy`/`closeGtwy` functions, if their existing codebase already uses one style.