Skip to main content
Version: 2.0

Connect agents to Slack

Connect a Vectara agent to Slack channels to respond to mentions, maintain threaded conversations, and use Slack-specific tools.

How Slack connectors work​

A Slack connector enables bidirectional communication between Vectara agents and Slack workspaces:

  1. Webhook ingestion: Slack sends events (messages, mentions) to a Vectara webhook endpoint
  2. Agent execution: The agent processes the message with full conversation context
  3. Response posting: Agent output is formatted and posted back to the Slack thread
  4. Tool access: The agent gains access to Slack-specific tools, such as reading channels, posting messages, and looking up users

Threading and sessions​

Slack connectors automatically map Slack threads to agent sessions:

  • New channel message: Creates a new agent session
  • Thread reply: Reuses the existing session for that thread, preserving conversation context
  • Thread context: When joining an existing thread, the agent reads prior messages to understand context

Create a Slack chatbot

Before you begin​

You need:

  • A Vectara account with agent creation permissions
  • A Slack workspace where you can install apps
  • Admin access to create a Slack app and generate tokens

Step 1: Create a Slack app​

  1. Go to https://api.slack.com/apps and select Create New App
  2. Choose From scratch
  3. Enter an app name (for example, "Support Agent") and select your workspace
  4. Select Create App

Step 2: Configure bot permissions​

  1. In the Slack app settings, select OAuth & Permissions from the left sidebar
  2. Scroll to Scopes and add these Bot Token Scopes to enable your agent to respond to Slack messages
  • message.channels - Messages posted to channels
  • message.groups - Messages posted to private channels
  • message.im - Direct messages (if needed)
  • message.mpim - Group direct messages (if needed)
  1. For additional scopes required by Slack tools, see Slack tools and OAuth permissions
  2. Select Install App from the left sidebar
  3. Select Install to (your workspace name)
  4. Review permissions and select Allow

You see the Bot User OAuth Token starting with xoxb-. Copy this token.

Step 3: Get the signing secret and app ID​

  1. Select Basic Information from the left sidebar
  2. Scroll to App Credentials
  3. Copy the Signing Secret (select Show first)
  4. Copy the App ID at the top of the page

Step 4: Create the agent connector​

CREATE SLACK CONNECTOR

Code example with bash syntax.
1

Expected response:

{
  "id": "con_slack_support",
  "agent_key": "support_agent",
  "name": "Support Slack Channel",
  "description":"Receives messages from #support channel",
  "type": "slack",
  "status": "active",
  "enabled": true,
  "configuration": {
    "type": "slack",
    "webhook_path": "/v2/agents/support_agent/connectors/con_slack_support/input"
  },
  "created_at": "2024-01-15T10:30:00Z"
}

The bot token and signing secret are encrypted and not returned in the response. Note the webhook_path for the next step.

Step 5: Configure Slack event subscriptions (optional)​

This step is only required if you want your agent to respond to Slack messages. Otherwise, it will only be capable of posting messages to Slack, and it won't respond to mentions.

  1. Return to your Slack app settings at https://api.slack.com/apps

  2. Select Event Subscriptions from the left sidebar

  3. Toggle Enable Events to On

  4. Enter the Request URL:

    https://api.vectara.io/v2/agents/<agent_key>/connectors/<connector_id>/input

    Replace <agent_key> and <connector_id> with values from step 4.

    Slack verifies the URL. You see a green checkmark when verification succeeds.

  5. Scroll to Subscribe to bot events and add:

    • message.channels - Messages posted to channels
    • message.groups - Messages posted to private channels (if needed)
    • message.im - Direct messages (if needed)
    • message.mpim - Group direct messages (if needed)

  6. Select Save Changes

  7. Slack prompts you to reinstall the app. Select reinstall your app

Step 6: Invite the bot to channels​

In each Slack channel where you want the agent to respond:

  1. Type /invite @YourBotName in the channel
  2. The bot joins and can now see messages

The agent responds when mentioned with @YourBotName in a message.

Step 7: Test the connector​

  1. In a Slack channel where the bot is a member, post a message: 
    @YourBotName What are our office hours?
  2. The agent processes the message and replies in the same thread
  3. Continue the conversation in the thread to test context preservation

The agent maintains conversation context across thread replies.

Slack tools and OAuth permissions​

When a connector is configured, the agent can make use of Slack tools. You will need to grant the Slack app certain permissions depending on which tools you attach to your agent.

slack_post_message​

The agent can use this tool to send proactive notifications, scheduled updates, or confirmation messages.

Requires: chat:write

slack_list_channels​

The agent can use this tool to discover available channels before posting messages.

Requires: channels:read, groups:read

slack_read_channel_history​

The agent can use this tool to read channel history when joining a thread or analyzing recent activity.

Requires: channels:history, groups:history

slack_get_user​

The agent can use this tool to look up user details mentioned in messages.

Requires: users:read, users:read.email

slack_list_users​

The agent can use this tool to discover workspace members.

Requires: users:read

Slack tools and connector metadata​

Slack tools use a fallback chain to resolve which connector's credentials to use:

default_argument_override:
  connector_id:
    $ref: session.metadata.connector_id
    $default: ""

This configuration means:

  1. If session.metadata.connector_id is set, use that connector
  2. If not set (empty string default), fall back to the connector that triggered the current session
  3. If no triggering connector, use the first Slack connector attached to the agent

For webhook-initiated sessions, the Slack connector automatically sets connector_id in session metadata, so tools use that specific connector.

For API-initiated sessions, if you don't set connector_id in session metadata, tools will use the first attached Slack connector. Set it explicitly when you have multiple Slack connectors and need a specific one.

Manage connectors​

List connectors​

LIST CONNECTORS

Code example with bash syntax.
1

Update connector​

UPDATE CONNECTOR

Code example with bash syntax.
1

Set enabled: false to pause event processing without deleting the connector.

Delete connector​

DELETE CONNECTOR

Code example with bash syntax.
1

Deleting a connector removes the configuration and stops event processing. Active sessions are not affected.

Troubleshooting​

Webhook verification fails​

If Slack reports "Your URL didn't respond with the challenge parameter":

  • Verify the webhook path matches the webhook_path from the connector creation response
  • Check that the connector enabled field is true
  • Verify the api_app_id in the connector configuration matches the Slack app ID

Agent does not respond to mentions​

  • Verify the bot is a member of the channel (use /invite @YourBotName)
  • Check the connector status field via the List connectors API
  • Verify the bot token has required scopes: channels:history, chat:write, users:read
  • Confirm the event subscription includes message.channels

Authentication errors in Slack tools​

If the agent receives invalid_auth errors when calling Slack tools:

  • The bot token may have been revoked or expired
  • Update the connector configuration with a fresh bot token
  • Reinstall the Slack app to regenerate the token

Messages appear out of order​

Slack sends events asynchronously. The agent processes each event in the order received, but Slack webhook delivery order is not guaranteed. Thread context is built from message timestamps, not arrival order.

Last updated on by Nikhil Bysani