Connect a Slack or Teams Chat Agent

You can put a GTM Engine agent directly in Slack or Microsoft Teams, so your team can ask it questions, look up records, run research, and take actions without leaving chat. This guide walks through creating your own Slack app, granting the scopes GTM Engine needs, and connecting it to an agent from the agent's Slack/Teams Chat tab.

Most of this guide covers Slack, since that's the most common setup. Microsoft Teams is covered briefly at the end.

How It Works

When you connect a chat app to an agent:

• The agent responds to @mentions in channels it's been added to, and to direct messages.
• Each incoming message is matched to the sender's GTM Engine user (by email), so the agent runs with that person's access and organization scope.
• The agent streams its answer back inline, and posts a card for every tool it runs (record lookups, reports, research, and so on) so it's clear what the agent is doing.

You supply the app's Bot Token and Signing Secret; GTM Engine gives you an Events webhook URL to paste back into your Slack app. That completes the two-way connection.

Prerequisites

• You're an admin of the Slack workspace (or can ask one to install the app).
• You have an agent in GTM Engine you want to expose in chat.
• You can access the agent's Slack/Teams Chat tab (open the agent, then select the tab).

Step 1 — Create a Slack App

1. Go to api.slack.com/apps and click Create New App.
2. Choose From scratch, give it a name (this is what your team will see, e.g. Genie), and pick the workspace to develop it in.

Step 2 — Add the Bot Token Scopes

Under OAuth & Permissions → Scopes → Bot Token Scopes, add every scope below. These cover mentions, channels, DMs, group DMs, and reading user identity (needed to map a Slack user to their GTM Engine account).

Step 3 — Enable the App Agent (AI Assistant) Experience

Under App Home (or Agents & AI Apps, depending on your Slack app's settings), enable the Agents & AI Apps feature so the app can act as an AI assistant. This is what pairs with the assistant:write scope above.

Step 4 — Install the App and Copy Credentials

1. Back on OAuth & Permissions, click Install to Workspace and approve the requested scopes.
2. Copy the Bot User OAuth Token (starts with xoxb-).
3. Go to Basic Information → App Credentials and copy the Signing Secret.

Step 5 — Connect It in GTM Engine

1. In GTM Engine, open your agent and go to the Slack/Teams Chat tab.
2. Select Slack as the platform.
3. Paste the Bot Token and Signing Secret, then click Save Config.
4. Click Test Connection to confirm GTM Engine can reach your workspace.

After saving, GTM Engine shows an Events Webhook URL on the same tab. Copy it — you'll need it in the next step.

Step 6 — Point Slack Events at GTM Engine

1. In your Slack app settings, go to Event Subscriptions and toggle Enable Events on.
2. Paste the Events Webhook URL from GTM Engine into the Request URL field. Slack will verify it.
3. Under Subscribe to bot events, add:
   • app_mention — triggers the agent when someone @mentions it in a channel.
   • message.im — triggers the agent on direct messages.
   • message.groups / message.mpim — optional, for private channels and group DMs.
4. Save your changes. Slack may prompt you to reinstall the app to apply the new events.

Step 7 — Try It Out

• In a channel: invite the app to a channel, then @mention it with a question.
• In a DM: open a direct message with the app and ask it something.

The agent will stream its answer and post a card for each tool it runs so you can see its work.

Managing the Integration

From the Slack/Teams Chat tab you can:

• Pause / resume the integration with the active toggle (without deleting your credentials).
• Update credentials by entering a new token or signing secret.
• Remove the integration entirely.

Microsoft Teams

The flow for Teams is similar, but you create an Azure Bot instead of a Slack app:

1. In the Azure Portal, create an Azure Bot (Multi-Tenant unless you need to restrict to one tenant). Note the App ID.
2. Under Configuration, set the Messaging endpoint to the endpoint URL shown on the Slack/Teams Chat tab (select Microsoft Teams first).
3. In the app registration, under Certificates & secrets, create a new client secret — this is your App Password.
4. Add the Microsoft Graph delegated permissions: ChatMessage.Read, ChatMessage.Send, Chat.ReadWrite, User.Read.
5. In GTM Engine, paste the App ID and App Password into the Teams form, save, and test.
6. In the Teams Developer Portal, add your bot to a Teams app manifest and publish it to your organization.

Common Questions

• The agent doesn't respond to @mentions. Confirm app_mention is subscribed under Event Subscriptions, the app is a member of the channel, and the integration is active on the Chat tab.
• The agent replies "I can only chat with users who have a GTM Engine account." The sender's Slack email doesn't match a GTM Engine user. Make sure users:read.email is granted and the person has a GTM Engine account with the same email.
• Slack couldn't verify my Request URL. Save your credentials in GTM Engine first (so the webhook URL exists), and make sure you copied the full URL from the Chat tab.

Next Steps

• Build a multi-tool agent — give your chat agent the tools it needs to answer real questions.
• Getting started — connect the rest of GTM Engine.