Bots

1. 1

   Open the form

   Bots → Create bot (owners and admins). You need at least one connection first — bots answer through it.

2. 2

   Name the bot

   The @handle people mention in Slack or Teams. Lowercase letters, numbers, hyphens, and underscores, starting with a letter or number — e.g. finance_bot.

3. 3

   Pick the connection and agent

   Choosing a connection loads its agents from Snowflake; pick the one this bot runs. The binding is one bot to one agent — fixed afterwards (to re-point a bot, create a new one).

4. 4

   Choose platform, transport, and channel access

   Pick Slack or Microsoft Teams as the platform. For Slack, socket mode is the default and right for most setups — details below. Teams is webhook-only: there is no socket option, and your Gondola instance must be reachable over public HTTPS. Channel access is optional and Slack-only (see below) — Teams bots always respond in every channel or chat they're installed in.

5. 5

   Create bot

   You land on the bot's page, which walks you through the platform setup next — the Slack app setup card or the Microsoft Teams setup card, depending on the platform you picked.

The Slack app setup card on the bot's page lists every step — about five minutes in your Slack workspace settings.

1. 1

   Create the Slack app

   Open api.slack.com/apps → Create New App → From a manifest, pick your workspace, and paste the manifest Gondola generated for the bot. It preconfigures the bot scopes and events, and either enables socket mode or fills in the webhook Request URL, depending on the transport.

   Updating an existing app? Scopes added to the manifest after you first created the app (for example, users:read) must be added manually under OAuth & Permissions, then the app reinstalled to your workspace for the new scopes to take effect.

2. 2

   Socket mode only: generate an app-level token

   In the Slack app: Basic Information → App-Level Tokens → Generate Token and Scopes, add the connections:write scope, and copy the xapp- token.

3. 3

   Install and copy credentials

   Install the app to your workspace and copy the Bot User OAuth Token (xoxb-). Webhook bots also need the Signing Secret from Basic Information.

4. 4

   Paste the credentials into Gondola

   Save them in the setup card. Gondola verifies the bot token against Slack before saving, then shows the workspace it connected to and starts the bot. Tokens are stored AES-256-GCM encrypted and never shown again. If the credentials save but the runtime can't start, the card shows a warning with the reason.

Teams connects through a per-bot Azure app registration and bot resource — the same per-customer isolation model Gondola uses for Slack. There is no socket mode for Teams; the Bot Framework pushes activities to Gondola over HTTPS, so your instance must be reachable from the public internet. The Microsoft Teams setup card on the bot's page walks through the same steps below.

1. 1

   Prerequisites

   • An Azure AD (Microsoft Entra ID) tenant you can create app registrations in.
   • Teams admin rights in that tenant — needed to approve or sideload the app package.
   • Your Gondola instance reachable over public HTTPS. The production origin is the webhook base URL.
2. 2

   Create the Gondola bot with platform Teams

   In the bot create form, pick Microsoft Teams as the platform. Teams is webhook-only, so the transport is fixed to webhook and channel access is not editable — the bot responds in every channel or chat it's installed in. Note the bot ID from its URL (/bots/<botId>); you'll use it in the webhook path next.

3. 3

   Register the Azure app and bot

   The Teams CLI creates the app registration, the Azure Bot resource, and wires the messaging endpoint in one step. Run it from any machine with Node 18+:

   shellCopy

   npx @microsoft/teams.cli app create \
     --endpoint https://<your-gondola-host>/api/teams/events/<botId>
   
   npx @microsoft/teams.cli app doctor <appId>

   app create prints the App (client) ID, the tenant ID, and prompts you to generate a client secret. Save all three — you'll enter them in Gondola in step 6.

   Prefer the portal? Create an app registration (Microsoft Entra ID → App registrations → New registration) with a client secret under Certificates & secrets, then an Azure Bot resource (Create a resource → Azure Bot) of type Existing App Registration pointing at it.

4. 4

   Set the messaging endpoint

   The Bot Framework sends messages to a single messaging endpoint per bot. Gondola's is:

   endpointCopy

   https://<your-gondola-host>/api/teams/events/<botId>

   The CLI sets this for you. In the portal, open the Azure Bot resource → Configuration → set Messaging endpoint to the URL above and save. It must be HTTPS and publicly reachable — Bot Framework does not call private networks.

5. 5

   Pick MultiTenant or SingleTenant

   The app registration's supported account type decides who the bot accepts messages from:

   • MultiTenant (AzureADMultipleOrgs) — accepts messages from any tenant. Simplest for a shared bot across customers. No tenant ID required in Gondola.
   • SingleTenant (AzureADMyOrg) — accepts messages from one specific tenant. The per-customer isolation model. You mustsupply that tenant's Entra tenant ID in Gondola.

   Match the choice you made in Azure when you enter credentials below.

6. 6

   Paste the credentials into Gondola

   In the Teams setup card on the bot's page, enter the App ID (the Entra client ID), the app password (the secret Value, not the Secret ID), the app type, and — for SingleTenant — the tenant ID. Gondola validates the credentials against Microsoft on save; if the bot's runtime status flips to healthy, you're done. Credentials are stored AES-256-GCM encrypted and never shown again.

7. 7

   Install the app into Teams

   After registration the bot exists in Azure but isn't installed anywhere. Two paths:

   • Sideload (dev/test) — in the Teams client, Apps → Manage your apps → Upload an app, and upload the app package (a .zip manifest from teams.cli app package or the Developer Portal). Requires Upload custom appsto be enabled in the tenant's Teams admin policy.
   • Org-wide approval(production) — submit the app through the Teams admin center. The Teams admin approves it once and it appears in the org's app catalog for everyone. Use this when sideload is blocked by policy.
8. 8

   @mention to test

   Once installed, @mention the bot in a channel or chat to start a conversation. v1 responds to @mentions only by default. To read all messages without an @mention, add RSC permissions (ChannelMessage.Read.Group, ChatMessage.Read.Chat) to the app manifest — they're accepted at install time, no portal consent step.

This choice applies to Slack bots. Teams is webhook-only — there is no socket option, covered in the section above.

Use socket mode unless you have a reason not to. For webhook bots, timing matters: Slack verifies the Request URL immediately, and only a running bot can answer the challenge — so activate the bot in Gondola first, then save the Request URL in your Slack app's settings. The generated manifest already carries the URL, which means Slack may ask to verify it while you create the app; retry once the bot is active.

You can switch transport later from the bot page (Bot info → Edit). Save the credentials the new transport needs from the Slack setup card afterwards.

A bot is always in one of four states:

• Setup needed — created, but no platform credentials saved yet.
• Active — credentials saved; the bot should be listening.
• Disabled — deactivated by someone in the workspace.
• Error — something failed; the recorded message shows on the badge and in the runtime card.

The Runtime card on the bot page shows whether the bot process is currently running, its transport, and the last error. Owners and admins get Activate / Deactivate buttons here — deactivating stops the platform connection, activating starts it again.

A bot can also show an amber Last error line while staying Active: transient problems (a stream failure, a Snowflake credential error) are recorded without taking the bot down.

Channel access is a Slack-only feature. Teams bots always respond in every channel or chat they're installed in — there's no allowlist, because the Bot Framework doesn't expose a comparable channel-ID restriction.

For a Slack bot, with no channels listed the bot responds in every channel it's invited to. Direct messages always work, regardless of the list.

To restrict a Slack bot, add Slack channel IDs in the create form or later via Bot info → Edit. An ID looks like C012AB3CD45 — find it in Slack by clicking the channel name at the top of the conversation and opening the About tab; the Channel ID is at the bottom. Channel names such as #general are not accepted because Slack events identify conversations by ID, not display name.

The bot page's Activity button opens a summary plus the conversation list:

• Summary — total conversations, transport, whether the runtime is running, and the last recorded error.
• Conversations — one row per chat thread the bot has answered in: channel, thread timestamp, last activity, and the Snowflake thread it maps to.

Conversations appear after someone mentions the bot or replies in one of its threads.

When someone mentions the bot, its answer streams into a chat thread off that message — a Slack thread or a Teams reply chain. Gondola records which Snowflake conversation each thread belongs to, so a reply in the same thread continues the same conversation — follow-ups keep the context of what came before. A new mention outside the thread starts a fresh conversation.

The Danger zone card on the bot page (owners and admins) deletes the bot after a confirmation. Deleting removes its platform credentials and conversation history, and cannot be undone.