Catalio logo
Sign in
Banner image for Slack Agent Usage Guide
Integrations • 9 min read

Slack Agent Usage Guide

Learn how to interact with the Catalio Slack Agent to manage requirements, personas, and use cases through natural conversation.

Updated

The Catalio Slack Agent is a conversational AI that understands natural language. You don’t need to memorize specific commands. Simply describe what you want in plain English, and Catalio will help you manage requirements directly from Slack.

Getting Started

Finding Catalio in Slack

  1. Open Slack and click on Apps in the left sidebar
  2. Search for “Catalio” in the Apps directory
  3. Click on the Catalio app to open it

If Catalio isn’t installed in your workspace, see the Slack Integration Administration guide or contact your Slack administrator.

App Home Tab

When you open the Catalio app, you’ll see the Home tab with:

  • Welcome Message: A personalized greeting with your name
  • Your Account: Your email address and role in the organization
  • Connection Status: Whether your Slack workspace is connected to Catalio
  • Getting Started: Quick reference commands to get you started

The Home tab also provides:

  • Switch Organizations button: Link to sign into a different Catalio organization
  • Open Slack Settings button: Navigate to the Slack integration settings in Catalio
  • Connect/Disconnect: Manage your workspace connection

Account Linking

Your Slack profile email must match your Catalio account email for the agent to recognize you.

Important

If your Slack email is different from your Catalio account email, you’ll receive a message asking you to update either your Slack profile or Catalio account to match.

To verify your email:

  1. In Slack, go to your profile and check your email address
  2. In Catalio, go to Settings > Account to see your registered email
  3. Ensure both emails match exactly

How to Communicate with Catalio

You can interact with the Catalio agent in three ways:

Method 1: @Mention in Channels

Mention @Catalio in any channel where the app is installed to start a conversation:

Plaintext 
@Catalio create a requirement for user login with email and password
Plaintext 
@Catalio list my recent requirements
Plaintext 
@Catalio what requirements are in progress?

Use @mentions when you want to:

  • Collaborate with teammates who can see the conversation
  • Keep a record of requirements discussions in a specific channel
  • Get quick answers visible to the whole team

Method 2: Direct Message

Open a direct message with Catalio for private conversations:

Plaintext 
list all high-priority requirements
Plaintext 
create a new requirement for the checkout process

In DMs, you don’t need to @mention Catalio. Just type your message directly.

Use DMs when you want to:

  • Have a private conversation with the agent
  • Avoid cluttering team channels
  • Work on requirements without interruption

Method 3: Thread Replies

After your initial interaction with @Catalio, you can continue the conversation in the thread without mentioning the agent again:

Initial message:

Plaintext 
@Catalio list requirements from this week

Reply in thread (no @mention needed):

Plaintext 
show me more details about the first one

Another reply:

Plaintext 
update its priority to high

The agent maintains context within the thread, so you can have natural back-and-forth conversations.

Common Tasks

Creating Requirements

Simply describe what you need in natural language:

Plaintext 
@Catalio create a requirement for password reset functionality
Plaintext 
@Catalio I need a new requirement: Users can export their data as CSV
Plaintext 
@Catalio create requirement titled "Multi-factor authentication" with high priority

When you create a requirement, Catalio will:

  1. Show a “Processing…” message while working
  2. Create the requirement in your organization
  3. Respond with the new requirement details including its ID

Tip

Be descriptive! The more context you provide, the better Catalio understands your intent. For example: “Create a requirement for user registration with email verification” is better than “new req”.

Listing and Searching Requirements

Ask for requirements in natural language:

Plaintext 
@Catalio list recent requirements
Plaintext 
@Catalio show me requirements from this week
Plaintext 
@Catalio what requirements are assigned to me?
Plaintext 
@Catalio find requirements about authentication

Catalio will display a formatted list showing:

  • Requirement title
  • Status
  • ID (for reference in follow-up requests)

Updating Requirements

Reference requirements by their ID or title to update them:

Plaintext 
@Catalio update REQ-123 priority to urgent
Plaintext 
@Catalio change the status of "User Authentication" to in progress

Getting Help

Ask Catalio for help anytime:

Plaintext 
@Catalio help
Plaintext 
@Catalio what can you do?

If you @mention Catalio without any message, it will automatically respond with help information.

Tips for Effective Use

Be Descriptive

The more context you provide, the better Catalio understands your request:

Less Clear More Clear
“new req” “Create a requirement for user registration with email verification”
“list reqs” “List all high-priority requirements in progress”
“update it” “Update REQ-123 status to approved”

Cancel Conversations

If you want to start over or cancel the current conversation, say:

  • cancel
  • reset
  • start over
  • never mind

Catalio will respond with “Cancelled. How can I help you?”

How the Agent Understands Context

Catalio uses AI to understand your intent through:

  • Natural language processing: Understanding what you mean, not just what you type
  • Conversation history: In threads, the agent remembers previous messages
  • Context awareness: Knowing your organization, role, and recent requirements

This means you can:

  • Use casual language (“show me my stuff” works as well as “list my requirements”)
  • Refer to previous items (“update the first one” after listing requirements)
  • Ask follow-up questions without repeating context

Rate Limits

To ensure fair usage, the agent allows 10 requests per minute per user. If you send messages too quickly, you’ll receive an ephemeral message asking you to slow down, with the number of seconds to wait before trying again.

Account and Organization Context

How User Identity Works

When you message Catalio, it looks up your Catalio account by matching your Slack profile email to your Catalio account email:

  1. Catalio retrieves your Slack profile email
  2. It searches for a Catalio user with that email in the connected organization
  3. If found, your requests are executed with your permissions
  4. If not found, you’ll receive instructions to update your email settings

Multi-Organization Access

If you belong to multiple Catalio organizations:

  1. Your Slack workspace connects to one Catalio organization at a time
  2. Use the Switch Organizations button in the App Home to sign into a different organization
  3. An administrator can connect the workspace to a different organization through Settings > Integrations > Slack

Understanding Data Access

All requirements you view or create through Slack belong to the organization your Slack workspace is connected to:

  • You can only see requirements in your connected organization
  • Your role (Admin, Editor, Contributor, Viewer) determines what actions you can take
  • All actions are logged with your identity for audit purposes

Troubleshooting

Quick Diagnostic Checklist

Before diving into specific issues, try these steps:

  1. Check your Slack email: Ensure it matches your Catalio account email
  2. Open the App Home: Verify the connection status shows “Connected” (green circle)
  3. Send a test message: Try sending help in a DM to the Catalio bot
  4. Check channel membership: Ensure @Catalio is invited to the channel you’re using

“I don’t recognize your Catalio account”

This message appears when Catalio cannot match your Slack identity to a Catalio user.

Full message:

I don’t recognize your Catalio account yet. Please make sure:

  1. Your Slack email matches your Catalio account email
  2. You have access to the connected Catalio organization

Solutions:

  1. Check your Slack email:

    • Click your profile picture in Slack
    • Select “Profile”
    • Click “Edit Profile”
    • Verify your email address

  2. Check your Catalio email:

    • Log into Catalio at catalio.ai
    • Go to Settings > Account
    • Verify your registered email

  3. Update to match:

    • Option A: Update your Slack profile to use your Catalio email
    • Option B: Update your Catalio account email in Settings

  4. Verify organization access:

    • Make sure you’re a member of the Catalio organization connected to your Slack workspace
    • Contact your Catalio administrator if you need to be added

Tip

Email matching is exact. “john@example.com” and “John@example.com” are treated as the same, but “john@example.com” and “john@example.org” are not.

Agent Not Responding

If @Catalio doesn’t respond when you mention it:

Troubleshooting Steps:

  1. Try a direct message:

    • Click on the Catalio app in your sidebar
    • Send help directly to the bot
    • If this works, the issue is channel-specific

  2. Check the App Home:

    • Open the Catalio app
    • Click the “Home” tab
    • Look for the connection status:
      • Green circle = Connected
      • Red circle = Disconnected or Not Connected

  3. Verify channel membership:

    • Type /invite @Catalio in the channel
    • Or click the channel name > Integrations > Add the Catalio app

  4. Confirm the right app:

    • Make sure you’re typing @Catalio (not a similarly named app)
    • Slack should autocomplete the name as you type

  5. Wait and retry:

    • Occasionally, network latency can cause delays
    • Wait 30 seconds and try again

Important

In channels, you must @mention @Catalio. In direct messages with the bot, no @mention is needed.

Rate Limit Messages

If you see this message:

You’re sending messages too quickly. Please slow down and try again in X seconds.

Details:

  • Limit: 10 requests per minute per user
  • This is an ephemeral message (only you can see it)
  • The message tells you exactly how long to wait

Solutions:

  1. Wait the indicated time: Simply pause for the specified seconds
  2. Batch your requests: Combine multiple questions into fewer, more detailed messages
  3. Use threads efficiently: Context is maintained in threads, so follow-up questions don’t need to repeat information

Note

Rate limiting is per-user, not per-channel. Using different channels doesn’t bypass the limit.

Connection Issues

If the App Home shows “Not Connected” or “Disconnected”:

  1. Contact your Catalio administrator
  2. Ask them to reconnect the workspace through Catalio settings
  3. Once reconnected, the App Home will update automatically

Unable to Load Catalio Home

If the App Home displays an error:

Unable to load Catalio Home This may be a temporary issue. Please try again in a moment.

Solutions:

  1. Click the Retry button: The Home view includes a retry option
  2. Wait a moment: Temporary API issues often resolve quickly
  3. Check your connection: Ensure you have internet access
  4. Contact support: If the problem persists, contact support@catalio.ai

Frequently Asked Questions

Can I use Catalio in private channels?

Yes, but the bot must be invited first:

  1. Open the private channel
  2. Type /invite @Catalio
  3. Once added, @mention @Catalio to start interacting

Why can’t my teammate see Catalio’s response?

Catalio sends some messages as “ephemeral” messages, which are only visible to you:

  • Rate limit warnings
  • Account recognition errors
  • Some error messages

Regular responses to @mentions in channels are visible to everyone.

How do I switch organizations in Slack?

If you need to work with a different Catalio organization:

  1. Open the Catalio App Home in Slack
  2. Click Switch Organizations
  3. Sign into Catalio with the appropriate organization
  4. An administrator must connect the Slack workspace to that organization

Note: A Slack workspace connects to one Catalio organization at a time.