Users & Roles

What it is

Users & Roles is BotBat's team management hub. It gives workspace administrators a single location to invite colleagues, assign predefined or custom roles, and fine-tune exactly what each person can see and do across every module in the platform. Whether your team has three people or three hundred, this module ensures that the right people have the right level of access at all times.

Every action inside BotBat is governed by a CASL-based permission system. Permissions are granular abilities such as campaigns:create, inbox:write, or billing:manage. These abilities are grouped into roles, and roles are assigned to users. Because the system is additive (permissions are merged when multiple roles apply), you can layer access precisely. Every permission change, user invitation, and role modification is recorded in a tamper-resistant audit trail, giving you a complete history of who did what and when.

The module is divided into three primary tabs: the User List (all active and deactivated members), the Roles Manager (predefined and custom role definitions), and the Audit Log (chronological record of all administrative actions). Together, these tabs form a complete identity and access management solution without needing external tooling.

When to use

Scenario	What to do
Onboarding a new team member	Invite them by email, pick a role, and they receive exactly the access they need from day one.
Restricting sensitive operations	Assign the Viewer role to stakeholders who only need read access, or create a custom role that allows campaign management but blocks billing.
Investigating unexpected changes	Open the Audit Log and filter by user, date range, or action type to trace who performed a specific action.
Scaling across departments	Set up department-specific custom roles such as "Marketing Manager" with campaign and analytics permissions but no inbox access.
Offboarding or suspending a user	Deactivate a team member immediately to revoke all access without deleting their activity history.
Temporary elevated access	Create a time-bound custom role, assign it, and remove it once the task is complete. The audit trail captures every change.

Steps

Inviting a team member

Navigate to the Account menu in the sidebar and select "Users & Roles." Click the "Invite User" button to open the invitation modal. Enter the new member's email address, select a role from the dropdown (Admin, Manager, Agent, or Viewer), and click Send. The invitee receives an email with a secure link to join the workspace. Until they accept, their status shows as "Pending" in the user list.

You can invite multiple users at once by entering comma-separated email addresses. All invitees receive the same role assignment. If you need different roles per person, send separate invitations.

Assigning or changing a role

From the user list, click the role badge next to any member to open the role reassignment dropdown. Select a predefined role (Admin, Manager, Agent, Viewer) or any custom role you have created. The change takes effect immediately and the user's session is updated without requiring them to log out. The previous role assignment is recorded in the audit trail for accountability.

Creating a custom role

Go to the "Roles" tab and click "Create Role." Name the role descriptively (e.g., "Campaign Operator" or "Support Lead"). The permission editor displays every available permission grouped by module. Toggle individual permissions on or off to build a precise access profile. Use the "Copy Role" button on an existing role to start from a known baseline, which reduces the risk of missing a permission toggle.

The following table lists the most commonly configured permissions:

Permission	Description
campaigns:create	Create and edit marketing campaigns
campaigns:send	Approve and send campaigns to contacts
contacts:read	View contact profiles and segments
contacts:write	Edit contact details and manage segments
inbox:read	View inbox conversations
inbox:write	Reply to and manage inbox conversations
billing:manage	Access billing, change plans, manage payment methods
users:write	Invite, deactivate, and remove workspace members
roles:manage	Create, edit, and delete custom roles
audit:read	View the audit trail

Deactivating and removing a user

Select a user from the list and click "Deactivate." A confirmation dialog appears warning that all active sessions for this user will be terminated immediately. The user can no longer log in, but their historical actions remain in the audit trail for compliance and traceability purposes.

For permanent removal, select an already deactivated user and click "Remove." This deletes the user account from the workspace entirely. This action is irreversible, so proceed with caution. Removed users can be re-invited later, but they will start with a fresh profile.

Reviewing the audit trail

Open the "Audit Log" tab to access the full history of administrative actions in your workspace. Every entry includes the timestamp, the acting user, the action performed, and the affected resource. You can filter by user, date range, or action type (role changes, permission edits, user invitations, deactivations). Export the log as CSV for external compliance reporting.

The audit trail is append-only and cannot be modified or deleted by any user, including workspace Admins. This ensures a reliable record for security investigations and regulatory compliance.

Common pitfalls

Pitfall	Why it matters
Granting Admin to everyone	Admin has unrestricted access including billing, user management, and API keys. Limit this role to one or two people per workspace.
Forgetting to deactivate departing employees	A user with active credentials can still access conversations and customer data. Always deactivate on their last day.
Overlapping custom roles with conflicting permissions	When a user holds multiple custom roles, permissions are merged (union). This can inadvertently grant more access than intended.
Ignoring the audit trail during incidents	When something unexpected happens (a campaign sent prematurely, contacts deleted), the audit trail is the fastest path to root cause.
Not testing custom roles before assigning	Create a test user account to verify that a new custom role works as expected before rolling it out to the whole team.

tip

Use the "Copy Role" button when creating a new custom role that is similar to an existing one. This saves time and reduces the risk of missing a permission toggle.

• Users & Roles Overview
• Invite Team Members
• Role Management
• Audit Log
• Deactivate Users
• Custom Role Editor