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

# Chat channels

> Let customers chat with a genie inside their own Slack workspace or Microsoft Teams organization

Chat channels let a genie answer customers inside their own Slack workspace or Microsoft Teams organization. The genie owner shares an install link; each customer workspace that installs it gets that genie added. A workspace can hold several genies, including genies from different owners, through one shared Help Genie app. Each genie answers under its own name.

Once connected, the genie answers direct messages, mentions and follow-ups in a thread. Each genie can be paused, resumed or disconnected in each workspace on its own, without affecting the other genies there.

On a paid plan, a genie can also have its **own Slack app**: a Slack app the owner creates in their own Slack account, with the genie's name, so customers install a branded bot instead of the shared Help Genie app. See [Own Slack app](#own-slack-app).

> [!NOTE]
>
> Microsoft Teams is experimental and intended for business accounts.

> [!NOTE]
>
> All actions except `slack-oauth`, `teams-oauth` and `own-app-install-url` require access to the genie (owner, team member with access, or admin). Callers without access receive `UNAUTHORIZED`. Creating, changing or removing an own Slack app is limited to the genie's owner and admins.

***

## List connected workspaces

Returns the Slack workspaces and Teams organizations a genie is connected to, newest first.

**resource** `string` *required*

Must be `"chat-channels"`

**action** `string` *required*

Must be `"list"`

**data** `object` *required*

**properties**

**agentId** `string` *required*

Genie UUID.

**success** `boolean`

Whether the request succeeded.

**data** `array`

**item properties**

**id** `string`

This genie's connection to the workspace. Pass it as `installId` to `set-paused` and `disconnect`.

**platform** `string`

`"slack"` or `"teams"`.

**workspace\_name** `string | null`

Name of the customer's Slack workspace or Teams organization.

**own\_app** `boolean`

`true` when the workspace installed the genie's [own Slack app](#own-slack-app) rather than the shared Help Genie app.

**paused\_at** `string | null`

ISO 8601 timestamp when the genie was paused in this workspace, or `null` when it is answering.

**created\_at** `string`

ISO 8601 timestamp when the workspace was connected.

```typescript Example request theme={null}
const workspaces = await ApiService.invoke("chat-channels", "list", {
  data: { agentId: "agent-uuid" },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1/chat-channels \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "list",
    "data": { "agentId": "agent-uuid" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": [
    {
      "id": "install-uuid",
      "platform": "slack",
      "workspace_name": "Acme Support",
      "own_app": false,
      "paused_at": null,
      "created_at": "2026-10-28T09:00:00.000Z"
    },
    {
      "id": "install-uuid-2",
      "platform": "teams",
      "workspace_name": "Acme Corp",
      "own_app": false,
      "paused_at": null,
      "created_at": "2026-10-27T15:20:00.000Z"
    }
  ]
}
```

***

## Get install link

Returns the shareable link that adds this genie to a customer's Slack workspace or Teams organization. For Slack, the link installs the shared Help Genie app; for Teams, it opens a Microsoft sign-in, after which the genie is connected to the person's organization. If the app is already there, the genie is added alongside the existing ones. Share it with customers; each workspace that installs it appears in `list`.

The link of a genie's [own Slack app](#own-slack-app) is separate: `https://helpgenie.ai/connect/slack/install/{appId}`, using the `id` from `own-app-get`.

The link does not expire. Control access per workspace with `set-paused` and `disconnect`.

**resource** `string` *required*

Must be `"chat-channels"`

**action** `string` *required*

Must be `"install-link"`

**data** `object` *required*

**properties**

**agentId** `string` *required*

Genie UUID.

**platform** `string` *required*

`"slack"` or `"teams"`. Any other value returns `VALIDATION_ERROR`.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**url** `string | null`

Slack install URL or Microsoft sign-in URL for this genie. For Teams, `null` while Teams is not yet available.

```typescript Example request theme={null}
const { url } = await ApiService.invoke("chat-channels", "install-link", {
  data: { agentId: "agent-uuid", platform: "slack" },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1/chat-channels \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "install-link",
    "data": { "agentId": "agent-uuid", "platform": "slack" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "url": "https://slack.com/oauth/v2/authorize?client_id=...&state=..."
  }
}
```

***

## Pause or resume a workspace

Pauses or resumes the genie in one connected workspace. A paused genie stays added to the workspace but does not answer. Other genies in the same workspace are unaffected.

**resource** `string` *required*

Must be `"chat-channels"`

**action** `string` *required*

Must be `"set-paused"`

**data** `object` *required*

**properties**

**agentId** `string` *required*

Genie UUID.

**installId** `string` *required*

Workspace connection ID from `list`.

**paused** `boolean` *required*

`true` to pause, `false` to resume.

**success** `boolean`

Whether the request succeeded.

**data** `object`

The updated workspace connection, with the same fields as a `list` item. Returns `NOT_FOUND` when the connection does not belong to this genie.

```typescript Example request theme={null}
const workspace = await ApiService.invoke("chat-channels", "set-paused", {
  data: { agentId: "agent-uuid", installId: "install-uuid", paused: true },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1/chat-channels \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "set-paused",
    "data": { "agentId": "agent-uuid", "installId": "install-uuid", "paused": true }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "id": "install-uuid",
    "platform": "slack",
    "workspace_name": "Acme Support",
    "own_app": false,
    "paused_at": "2026-10-29T08:30:00.000Z",
    "created_at": "2026-10-28T09:00:00.000Z"
  }
}
```

***

## Disconnect a workspace

Removes the genie from a customer's Slack workspace or Teams organization. Other genies in that workspace keep answering. In Slack, when no other genie is left there, the app is also uninstalled from the workspace, so the bot does not stay behind without answering. In Teams, only the customer can remove the app itself.

> [!WARNING]
>
> This action is destructive. The customer has to use the genie's install link again to add it back.

Succeeds silently when the connection does not exist or does not belong to this genie.

**resource** `string` *required*

Must be `"chat-channels"`

**action** `string` *required*

Must be `"disconnect"`

**data** `object` *required*

**properties**

**agentId** `string` *required*

Genie UUID.

**installId** `string` *required*

Workspace connection ID from `list`.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**success** `boolean`

Always `true`.

```typescript Example request theme={null}
await ApiService.invoke("chat-channels", "disconnect", {
  data: { agentId: "agent-uuid", installId: "install-uuid" },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1/chat-channels \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "disconnect",
    "data": { "agentId": "agent-uuid", "installId": "install-uuid" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": { "success": true }
}
```

***

## Own Slack app

A genie's own Slack app lets customers install a bot with the genie's name instead of the shared Help Genie app. The owner creates the app in their own Slack account from a ready-made manifest, then pastes its credentials back into Help Genie. The first finished install proves the credentials work and moves the app from `pending` to `ready`.

Own apps need a paid plan on the genie owner's account (or, for a teammate's genie, the team owner's account). Admins are exempt.

Setup flow:

1. Call `own-app-create` and open `create_url` to create the app in Slack from the manifest.
2. Call `own-app-save` with the App ID, Client ID, Client Secret and Signing Secret from the app's settings in Slack.
3. Share `https://helpgenie.ai/connect/slack/install/{id}`. A test install from that link sets `status` to `ready`.
4. When `needs_update` is `true`, apply the new `manifest` in Slack and call `own-app-save` with `manifestUpdated: true`.

### The own app object

Returned by `own-app-get`, `own-app-create` and `own-app-save`. Secrets are never returned.

**id** `string`

Own app ID. Used in the install link `/connect/slack/install/{id}`.

**status** `string`

`"pending"` until a test install succeeds with the saved credentials, then `"ready"`.

**slack\_app\_id** `string | null`

The App ID saved from Slack.

**client\_id** `string | null`

The Client ID saved from Slack.

**has\_credentials** `boolean`

Whether both the Client Secret and the Signing Secret are saved.

**needs\_update** `boolean`

`true` when a `ready` app was set up from an older manifest or is missing permissions the genie now needs. Apply the current `manifest` in Slack, then call `own-app-save` with `manifestUpdated: true`.

**manifest** `object`

The Slack app manifest for this genie: its name, bot user, permissions, and the event and interactivity URLs that connect it to Help Genie.

**create\_url** `string`

Link that opens Slack's "create app" page with the manifest filled in.

***

## Get own Slack app

Returns the genie's own Slack app, if it has one, and whether the caller may set one up.

**resource** `string` *required*

Must be `"chat-channels"`

**action** `string` *required*

Must be `"own-app-get"`

**data** `object` *required*

**properties**

**agentId** `string` *required*

Genie UUID.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**can\_manage** `boolean`

Whether the caller is the genie's owner or an admin, and so may create, change or remove its app.

**is\_plan\_eligible** `boolean`

Whether the plan allows an own app. Always `true` for admins.

**app** `object | null`

The [own app object](#the-own-app-object), or `null` when the genie has none.

```typescript Example request theme={null}
const { can_manage, is_plan_eligible, app } = await ApiService.invoke("chat-channels", "own-app-get", {
  data: { agentId: "agent-uuid" },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1/chat-channels \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "own-app-get",
    "data": { "agentId": "agent-uuid" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "can_manage": true,
    "is_plan_eligible": true,
    "app": {
      "id": "chat-app-uuid",
      "status": "ready",
      "slack_app_id": "A0123ABCD",
      "client_id": "1234567890.1234567890",
      "has_credentials": true,
      "needs_update": false,
      "manifest": { "display_information": { "name": "Acme Support Genie" } },
      "create_url": "https://api.slack.com/apps?new_app=1&manifest_json=..."
    }
  }
}
```

***

## Start an own Slack app

Starts setting up the genie's own Slack app and returns its manifest and `create_url`. Returns the existing app when the genie already has one.

Genie owner or admin only (`UNAUTHORIZED` otherwise). Returns `FORBIDDEN` without a paid plan.

**resource** `string` *required*

Must be `"chat-channels"`

**action** `string` *required*

Must be `"own-app-create"`

**data** `object` *required*

**properties**

**agentId** `string` *required*

Genie UUID.

**success** `boolean`

Whether the request succeeded.

**data** `object`

The [own app object](#the-own-app-object), with `status: "pending"` for a new app.

```typescript Example request theme={null}
const app = await ApiService.invoke("chat-channels", "own-app-create", {
  data: { agentId: "agent-uuid" },
});
window.open(app.create_url);
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1/chat-channels \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "own-app-create",
    "data": { "agentId": "agent-uuid" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "id": "chat-app-uuid",
    "status": "pending",
    "slack_app_id": null,
    "client_id": null,
    "has_credentials": false,
    "needs_update": false,
    "manifest": { "display_information": { "name": "Acme Support Genie" } },
    "create_url": "https://api.slack.com/apps?new_app=1&manifest_json=..."
  }
}
```

***

## Save own Slack app

Saves the credentials pasted from the app's settings in Slack, or records that the owner applied the latest manifest.

A secret left blank keeps the stored one. Changing the App ID or Client ID means a different Slack app: both secrets are required again, and the app returns to `pending` until a new test install succeeds.

Genie owner or admin only (`UNAUTHORIZED` otherwise). Returns `FORBIDDEN` without a paid plan and `NOT_FOUND` when the genie has no own app yet (call `own-app-create` first).

**resource** `string` *required*

Must be `"chat-channels"`

**action** `string` *required*

Must be `"own-app-save"`

**data** `object` *required*

**properties**

**agentId** `string` *required*

Genie UUID.

**slackAppId** `string`

The App ID from Slack. Required unless `manifestUpdated` is `true`.

**clientId** `string`

The Client ID from Slack. Required unless `manifestUpdated` is `true`.

**clientSecret** `string`

The Client Secret from Slack. Required for a new or different app; leave blank to keep the stored secret.

**signingSecret** `string`

The Signing Secret from Slack. Required for a new or different app; leave blank to keep the stored secret.

**manifestUpdated** `boolean`

`true` to record that the owner applied the current `manifest` in Slack. Clears `needs_update` once the app has the permissions it needs. The credential fields are ignored.

**success** `boolean`

Whether the request succeeded.

**data** `object`

The updated [own app object](#the-own-app-object).

```typescript Example request theme={null}
const app = await ApiService.invoke("chat-channels", "own-app-save", {
  data: {
    agentId: "agent-uuid",
    slackAppId: "A0123ABCD",
    clientId: "1234567890.1234567890",
    clientSecret: "your-client-secret",
    signingSecret: "your-signing-secret",
  },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1/chat-channels \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "own-app-save",
    "data": {
      "agentId": "agent-uuid",
      "slackAppId": "A0123ABCD",
      "clientId": "1234567890.1234567890",
      "clientSecret": "your-client-secret",
      "signingSecret": "your-signing-secret"
    }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "id": "chat-app-uuid",
    "status": "pending",
    "slack_app_id": "A0123ABCD",
    "client_id": "1234567890.1234567890",
    "has_credentials": true,
    "needs_update": false,
    "manifest": { "display_information": { "name": "Acme Support Genie" } },
    "create_url": "https://api.slack.com/apps?new_app=1&manifest_json=..."
  }
}
```

***

## Remove own Slack app

Uninstalls the genie's own Slack app from every customer workspace, then deletes its credentials and those workspace connections. A workspace that refuses the uninstall does not block the removal. Workspaces using the shared Help Genie app are not affected.

> [!WARNING]
>
> This action is destructive. Customers who installed the own app lose the genie; the owner has to set the app up again to restore it.

Genie owner or admin only (`UNAUTHORIZED` otherwise). Succeeds silently when the genie has no own app.

**resource** `string` *required*

Must be `"chat-channels"`

**action** `string` *required*

Must be `"own-app-remove"`

**data** `object` *required*

**properties**

**agentId** `string` *required*

Genie UUID.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**success** `boolean`

Always `true`.

```typescript Example request theme={null}
await ApiService.invoke("chat-channels", "own-app-remove", {
  data: { agentId: "agent-uuid" },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1/chat-channels \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "own-app-remove",
    "data": { "agentId": "agent-uuid" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": { "success": true }
}
```

***

## List all own Slack apps (admin)

Returns every genie's own Slack app with its health, worst first, then newest first. Admin only; other callers receive `FORBIDDEN`. Secrets are never returned.

**resource** `string` *required*

Must be `"chat-channels"`

**action** `string` *required*

Must be `"own-app-admin-list"`

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**apps** `array`

**item properties**

**id** `string`

Own app ID.

**agent\_id** `string`

Genie UUID.

**genie\_name** `string | null`

Genie name.

**owner\_email** `string | null`

Email of the genie's owner.

**slack\_app\_id** `string | null`

The App ID saved from Slack.

**health** `string`

One of, worst first:

* `"failing"` — an error in the last 7 days with no successful activity since
* `"needs_update"` — set up from an older manifest or missing permissions
* `"not_installed"` — ready, but no workspace has installed it
* `"setup_unfinished"` — still `pending`
* `"plan_lapsed"` — the owner no longer has a paid plan
* `"quiet"` — no activity for over 30 days
* `"healthy"`

**has\_credentials** `boolean`

Whether the Client ID, Client Secret and Signing Secret are all saved.

**has\_plan** `boolean`

Whether the owner (or their team owner) has a paid plan. Always `true` for admin-owned genies.

**manifest\_version** `number`

Manifest version the app was last set up or updated from.

**current\_manifest\_version** `number`

The current manifest version.

**missing\_scopes** `string[]`

Slack permissions a `ready` app is missing. Empty for `pending` apps.

**created\_at** `string`

ISO 8601 timestamp when the app was started.

**last\_event\_at** `string | null`

ISO 8601 timestamp of the last activity received from Slack.

**last\_error\_at** `string | null`

ISO 8601 timestamp of the last error.

**last\_error** `string | null`

The last error message.

**workspaces** `array`

Workspaces that installed the app: `{ id, name, created_at, is_paused }`, where `is_paused` is whether the genie is paused there.

```typescript Example request theme={null}
const { apps } = await ApiService.invoke("chat-channels", "own-app-admin-list");
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1/chat-channels \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "own-app-admin-list" }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "apps": [
      {
        "id": "chat-app-uuid",
        "agent_id": "agent-uuid",
        "genie_name": "Acme Support Genie",
        "owner_email": "owner@acme.com",
        "slack_app_id": "A0123ABCD",
        "health": "healthy",
        "has_credentials": true,
        "has_plan": true,
        "manifest_version": 1,
        "current_manifest_version": 1,
        "missing_scopes": [],
        "created_at": "2026-10-20T10:00:00.000Z",
        "last_event_at": "2026-11-01T14:12:00.000Z",
        "last_error_at": null,
        "last_error": null,
        "workspaces": [
          { "id": "install-uuid", "name": "Acme Support", "created_at": "2026-10-21T09:00:00.000Z", "is_paused": false }
        ]
      }
    ]
  }
}
```

***

## Complete a Slack install

Finishes a Slack install after the customer approves the app in Slack. Called by the `/connect/slack/callback` page with the values Slack returns. Adds the genie named in the install link to the customer's workspace, alongside any genies already there.

The same action finishes installs of a genie's [own Slack app](#own-slack-app). The first successful install marks the own app `ready`. If the credentials answer for a different Slack app than the saved App ID, the install is undone and `VALIDATION_ERROR` is returned.

This action is public: it accepts a public request (no API key) as well as a signed-in session. Reinstalling a genie that is already in the workspace refreshes the connection.

After the install, the installer gets a direct message from the app. If this is the only genie in the workspace, it greets them; if there are several, they are asked which genie they want to talk to.

**resource** `string` *required*

Must be `"chat-channels"`

**action** `string` *required*

Must be `"slack-oauth"`

**data** `object` *required*

**properties**

**code** `string` *required*

The authorization code Slack returns to the callback page.

**state** `string` *required*

The signed state carried by the install link, returned unchanged by Slack.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**genieName** `string`

Name of the genie now answering in the workspace.

**workspaceName** `string`

Name of the connected Slack workspace.

**appUrl** `string`

`slack://` link that opens the installer's direct message with the app in the Slack desktop or mobile app. Falls back to opening the workspace when the direct message could not be created.

**webUrl** `string`

Link to the same direct message in Slack on the web. Falls back to the app's page in the workspace when the direct message could not be created.

```typescript Example request theme={null}
const { genieName, workspaceName, appUrl, webUrl } = await ApiService.invoke("chat-channels", "slack-oauth", {
  data: { code: "slack-oauth-code", state: "signed-state" },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1/chat-channels \
  -H "Content-Type: application/json" \
  -H "x-public-request: true" \
  -d '{
    "action": "slack-oauth",
    "data": { "code": "slack-oauth-code", "state": "signed-state" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "genieName": "Acme Support Genie",
    "workspaceName": "Acme Support",
    "appUrl": "slack://channel?team=T0123ABCD&id=D0456EFGH",
    "webUrl": "https://app.slack.com/client/T0123ABCD/D0456EFGH"
  }
}
```

***

## Complete a Teams install

Finishes connecting a genie to a Microsoft Teams organization after the customer signs in with Microsoft. Called by the `/connect/teams/callback` page with the values Microsoft returns. Adds the genie named in the install link to the organization the person signed in with, alongside any genies already there, then installs the app for that person so the genie is waiting in Teams.

This action is public: it accepts a public request (no API key) as well as a signed-in session.

If Microsoft refuses to install the app for the person (for example, because their organization restricts app installs), the genie stays connected and `installed` is `false`; `addUrl` then lets them add the app themselves. When the install succeeds, the genie greets them in a personal chat.

**resource** `string` *required*

Must be `"chat-channels"`

**action** `string` *required*

Must be `"teams-oauth"`

**data** `object` *required*

**properties**

**code** `string` *required*

The sign-in code Microsoft returns to the callback page.

**state** `string` *required*

The signed state carried by the install link, returned unchanged by Microsoft.

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**genieName** `string`

Name of the genie now connected to the organization.

**workspaceName** `string | null`

Name of the connected Teams organization.

**installed** `boolean`

Whether the app was installed for the person who signed in. `false` when Microsoft refused the install.

**chatUrl** `string`

Link that opens the person's chat with the genie in Teams.

**addUrl** `string`

Link that opens the app in Teams so the person can add it themselves.

```typescript Example request theme={null}
const { genieName, workspaceName, installed, chatUrl, addUrl } = await ApiService.invoke("chat-channels", "teams-oauth", {
  data: { code: "microsoft-sign-in-code", state: "signed-state" },
});
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1/chat-channels \
  -H "Content-Type: application/json" \
  -H "x-public-request: true" \
  -d '{
    "action": "teams-oauth",
    "data": { "code": "microsoft-sign-in-code", "state": "signed-state" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "genieName": "Acme Support Genie",
    "workspaceName": "Acme Corp",
    "installed": true,
    "chatUrl": "https://teams.microsoft.com/l/chat/0/0?tenantId=...&users=28:...",
    "addUrl": "https://teams.microsoft.com/l/app/...?tenantId=..."
  }
}
```

***

## Resolve an own app install link

Resolves the install link of a genie's [own Slack app](#own-slack-app) to the app's Slack authorize page. Called by the `/connect/slack/install/{chatAppId}` page on each visit, so the link keeps working when the owner replaces the app's credentials.

This action is public: it accepts a public request (no API key) as well as a signed-in session. Returns `NOT_FOUND` for an unknown app, or until its Client ID is saved.

**resource** `string` *required*

Must be `"chat-channels"`

**action** `string` *required*

Must be `"own-app-install-url"`

**data** `object` *required*

**properties**

**chatAppId** `string` *required*

Own app ID (the `id` from `own-app-get`).

**success** `boolean`

Whether the request succeeded.

**data** `object`

**properties**

**url** `string`

Slack authorize URL for the own app. Completing it calls `slack-oauth`.

```typescript Example request theme={null}
const { url } = await ApiService.invoke("chat-channels", "own-app-install-url", {
  data: { chatAppId: "chat-app-uuid" },
});
window.location.href = url;
```

```bash cURL theme={null}
curl -X POST https://api.helpgenie.ai/v1/chat-channels \
  -H "Content-Type: application/json" \
  -H "x-public-request: true" \
  -d '{
    "action": "own-app-install-url",
    "data": { "chatAppId": "chat-app-uuid" }
  }'
```

```json Response theme={null}
{
  "success": true,
  "data": {
    "url": "https://slack.com/oauth/v2/authorize?client_id=...&state=..."
  }
}
```

***

## Error codes

| Code | Meaning |
| - | - |
| `VALIDATION_ERROR` | A required field is missing, `paused` is not a boolean, `platform` is not `"slack"` or `"teams"`, own app credentials are incomplete, the Slack app is already connected to another genie (`own-app-save`), or the Slack app does not match the saved App ID (`slack-oauth`) |
| `UNAUTHORIZED` | You do not have access to this genie, you are not the genie's owner or an admin (`own-app-create`, `own-app-save`, `own-app-remove`), or (for `slack-oauth` and `teams-oauth`) the install link is not valid |
| `FORBIDDEN` | An own Slack app needs a paid plan (`own-app-create`, `own-app-save`), or the caller is not an admin (`own-app-admin-list`) |
| `NOT_FOUND` | The workspace connection does not belong to this genie (`set-paused`), the genie has no own app yet (`own-app-save`), the install link is not valid (`own-app-install-url`), or the genie or its own app is inactive, missing or not set up (`slack-oauth`, `teams-oauth`) |
| `INVALID_ACTION` | Unknown action |
| `INTERNAL_ERROR` | Unexpected server error |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.