Chat channels

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.

Microsoft Teams is experimental and intended for business accounts.

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.

string

required

Must be "chat-channels"

string

required

Must be "list"

object

required

Show properties

string

required

Genie UUID.

boolean

Whether the request succeeded.

array

Show item properties

string

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

string

"slack" or "teams".

string | null

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

boolean

true when the workspace installed the genie’s own Slack app rather than the shared Help Genie app.

string | null

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

string

ISO 8601 timestamp when the workspace was connected.

const workspaces = await ApiService.invoke("chat-channels", "list", {
  data: { agentId: "agent-uuid" },
});

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" }
  }'

{
  "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 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.

string

required

Must be "chat-channels"

string

required

Must be "install-link"

object

required

Show properties

string

required

Genie UUID.

string

required

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

boolean

Whether the request succeeded.

object

Show properties

string | null

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

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

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" }
  }'

{
  "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.

string

required

Must be "chat-channels"

string

required

Must be "set-paused"

object

required

Show properties

string

required

Genie UUID.

string

required

Workspace connection ID from list.

boolean

required

true to pause, false to resume.

boolean

Whether the request succeeded.

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.

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

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 }
  }'

{
  "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.

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.

string

required

Must be "chat-channels"

string

required

Must be "disconnect"

object

required

Show properties

string

required

Genie UUID.

string

required

Workspace connection ID from list.

boolean

Whether the request succeeded.

object

Show properties

boolean

Always true.

await ApiService.invoke("chat-channels", "disconnect", {
  data: { agentId: "agent-uuid", installId: "install-uuid" },
});

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" }
  }'

{
  "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:

Call own-app-create and open create_url to create the app in Slack from the manifest.
Call own-app-save with the App ID, Client ID, Client Secret and Signing Secret from the app’s settings in Slack.
Share https://helpgenie.ai/connect/slack/install/{id}. A test install from that link sets status to ready.
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.

string

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

string

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

string | null

The App ID saved from Slack.

string | null

The Client ID saved from Slack.

boolean

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

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.

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.

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.

string

required

Must be "chat-channels"

string

required

Must be "own-app-get"

object

required

Show properties

string

required

Genie UUID.

boolean

Whether the request succeeded.

object

Show properties

boolean

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

boolean

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

object | null

The own app object, or null when the genie has none.

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

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" }
  }'

{
  "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.

string

required

Must be "chat-channels"

string

required

Must be "own-app-create"

object

required

Show properties

string

required

Genie UUID.

boolean

Whether the request succeeded.

object

The own app object, with status: "pending" for a new app.

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

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" }
  }'

{
  "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).

string

required

Must be "chat-channels"

string

required

Must be "own-app-save"

object

required

Show properties

string

required

Genie UUID.

string

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

string

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

string

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

string

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

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.

boolean

Whether the request succeeded.

object

The updated own app object.

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",
  },
});

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"
    }
  }'

{
  "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.

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.

string

required

Must be "chat-channels"

string

required

Must be "own-app-remove"

object

required

Show properties

string

required

Genie UUID.

boolean

Whether the request succeeded.

object

Show properties

boolean

Always true.

await ApiService.invoke("chat-channels", "own-app-remove", {
  data: { agentId: "agent-uuid" },
});

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" }
  }'

{
  "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.

string

required

Must be "chat-channels"

string

required

Must be "own-app-admin-list"

boolean

Whether the request succeeded.

object

Show properties

array

Show item properties

string

Own app ID.

string

Genie UUID.

string | null

Genie name.

string | null

Email of the genie’s owner.

string | null

The App ID saved from Slack.

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"

boolean

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

boolean

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

number

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

number

The current manifest version.

string[]

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

string

ISO 8601 timestamp when the app was started.

string | null

ISO 8601 timestamp of the last activity received from Slack.

string | null

ISO 8601 timestamp of the last error.

string | null

The last error message.

array

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

const { apps } = await ApiService.invoke("chat-channels", "own-app-admin-list");

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" }'

{
  "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. 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.

string

required

Must be "chat-channels"

string

required

Must be "slack-oauth"

object

required

Show properties

string

required

The authorization code Slack returns to the callback page.

string

required

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

boolean

Whether the request succeeded.

object

Show properties

string

Name of the genie now answering in the workspace.

string

Name of the connected Slack workspace.

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.

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.

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

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" }
  }'

{
  "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.

string

required

Must be "chat-channels"

string

required

Must be "teams-oauth"

object

required

Show properties

string

required

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

string

required

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

boolean

Whether the request succeeded.

object

Show properties

string

Name of the genie now connected to the organization.

string | null

Name of the connected Teams organization.

boolean

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

string

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

string

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

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

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" }
  }'

{
  "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 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.

string

required

Must be "chat-channels"

string

required

Must be "own-app-install-url"

object

required

Show properties

string

required

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

boolean

Whether the request succeeded.

object

Show properties

string

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

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

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" }
  }'

{
  "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

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

List connected workspaces

Get install link

Pause or resume a workspace

Disconnect a workspace

Own Slack app

The own app object

Get own Slack app

Start an own Slack app

Save own Slack app

Remove own Slack app

List all own Slack apps (admin)

Complete a Slack install

Complete a Teams install

Resolve an own app install link

Error codes

​List connected workspaces

​Get install link

​Pause or resume a workspace

​Disconnect a workspace

​Own Slack app

​The own app object

​Get own Slack app

​Start an own Slack app

​Save own Slack app

​Remove own Slack app

​List all own Slack apps (admin)

​Complete a Slack install

​Complete a Teams install

​Resolve an own app install link

​Error codes

List connected workspaces

Get install link

Pause or resume a workspace

Disconnect a workspace

Own Slack app

The own app object

Get own Slack app

Start an own Slack app

Save own Slack app

Remove own Slack app

List all own Slack apps (admin)

Complete a Slack install

Complete a Teams install

Resolve an own app install link

Error codes