> ## Documentation Index
> Fetch the complete documentation index at: https://docs.answeringagent.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notification settings guide

# Team Notification Settings Guide

## Overview

The notification system allows team administrators to control which team members receive notifications for different events (tasks, calls, texts, questions) via email and SMS. This guide explains how to configure notification preferences for your team members.

## Key Concepts

### Notification Hierarchy

The system uses a three-level hierarchy for notification preferences:

1. **Phone-specific preferences** (highest priority) - Settings for a specific phone number
2. **Team-wide preferences** (medium priority) - Settings that apply to all phone numbers in the team
3. **System defaults** (lowest priority) - Default settings for new team members

When a notification event occurs, the system checks for preferences in this order and uses the first match found.

### Default Behavior

When a new member joins your team, they are automatically enrolled in **minimal notifications**:

* ✅ **Task Created** - Email only
* ✅ **Task Assigned** - Email only (only when assigned to them)
* ❌ All other notifications disabled by default

This conservative default prevents notification fatigue while ensuring critical task information reaches team members.

## Available Notification Types

### Events (What triggers notifications)

| Event                | Description                  | When it fires                                                                           |
| -------------------- | ---------------------------- | --------------------------------------------------------------------------------------- |
| **Task Created**     | New task created from a call | Every time AI creates a task from call transcript                                       |
| **Task Assigned**    | Task assigned to a user      | When a task is assigned or reassigned                                                   |
| **Task Updated**     | Task details modified        | When task description, category, or details change (excludes completion and assignment) |
| **Task Completed**   | Task marked complete         | When someone marks a task as done                                                       |
| **Call Completed**   | Call ends and is processed   | After each completed call                                                               |
| **Text Sent**        | Text message sent to client  | When AI sends a text message after a call                                               |
| **Question Created** | Question extracted from call | When AI identifies a question in the transcript                                         |

### Channels (How notifications are delivered)

| Channel   | Requirements                        | Notes                                          |
| --------- | ----------------------------------- | ---------------------------------------------- |
| **Email** | Valid email address on user account | Always available for users                     |
| **SMS**   | Phone number added to user profile  | Must be in E.164 format (starts with +)        |
| **Slack** | Connected customer Slack workspace  | Team-level channels; not a per-user preference |

**Important**: Users can only enable SMS notifications if they have a phone number on their account. Admins can add/edit phone numbers in the Members Settings page.

## Slack Channel Notifications

Slack notifications are configured under **Settings → Notification Preferences → Slack**. Slack is a team-level destination: each channel setup sends new task notifications to one Slack channel. Slack is not part of the per-user Email/SMS preference matrix because delivery goes to shared channels, not individual users.

Supported Slack notification in v1:

* Task Created

Slack setup requires a distributed Slack app for production customer installs. Configure the OAuth redirect URL, then set the customer app credentials in environment variables:

```bash theme={null}
SLACK_CUSTOMER_CLIENT_ID=
SLACK_CUSTOMER_CLIENT_SECRET=
SLACK_CUSTOMER_REDIRECT_URL=
SLACK_CUSTOMER_DISTRIBUTION_ENABLED=true
```

Required bot scopes:

* `chat:write`
* `channels:read`

Optional bot scopes:

* `chat:write.customize` for subject-customer name and icon styling in the
  Answering Agent internal workspace (team 1); customer-owned routes always
  use the installed Answering Agent app identity
* `groups:read` for private channel discovery

Slack optional scopes can be marked optional in the Slack app settings or manifest with `oauth_config.scopes.bot_optional`.

Slack notification health is visible in the Slack settings page. Common failures:

* `not_in_channel` or `channel_not_found`: invite the Answering Agent Slack app to the channel
* `missing_scope`: reconnect Slack with the needed permission
* `invalid_auth`, `not_authed`, `account_inactive`, or `token_revoked`: reconnect Slack
* `is_archived`: choose a different channel
* `rate_limited`: retry after Slack's rate limit window

Slack v1 does not route completed conversations, questions, or SMS replies to customer Slack channels. It also does not watch Slack channels, ingest Slack messages, create tasks from Slack posts, or process Slack button clicks. Buttons in Slack messages are dashboard links only.

## Accessing Notification Settings

### Step 1: Navigate to Settings

1. Click on your **team name** in the sidebar
2. Select **Settings** from the dropdown
3. Click **Notification Preferences** in the settings menu

### Step 2: View Team Members

You'll see a list of all team members with:

* Member name, email, and role
* Current notification preferences (if any configured)
* "Configure" button to edit their settings

## Configuring Member Notifications

### Opening the Configuration Modal

1. Find the team member you want to configure
2. Click the **"Configure"** button next to their name
3. A modal will open showing their notification preferences

### Understanding the Interface

The configuration modal shows:

#### User Information

* Name, email, phone number (for SMS notifications)
* Current notification settings overview

#### Notification Scope Selector

Choose where these settings apply:

* **Team-wide notifications** - Apply to all phone numbers in the team
* **Specific phone number** - Apply only to calls from one phone number

#### Event-Channel Matrix

A grid showing all notification events (rows) and available channels (columns):

* **Email column** - Toggle email notifications for each event
* **SMS column** - Toggle SMS notifications for each event (requires phone number)

### Step-by-Step: Edit Notifications

1. **Select Scope**
   * Choose "Team-wide" for notifications on all phone numbers
   * Or select a specific phone number to configure separately

2. **Enable/Disable Events**
   * Check the boxes for events and channels you want enabled
   * For example, to get email + SMS for new tasks:
     * Find the "Task Created" row
     * Check both "Email" and "SMS" boxes

3. **Save Changes**
   * Click **"Save Preferences"** at the bottom
   * Changes take effect immediately

4. **Clear All Notifications (Optional)**
   * Click **"Reset to Defaults"** to remove all custom settings
   * **Important**: This clears ALL notifications for this scope
   * The member will receive NO notifications until you re-configure them
   * Note: This is different from new member defaults (see below)

> **Understanding "Defaults"**
> There are two different types of defaults in the system:
>
> * **New Member Defaults**: When someone joins your team, they automatically get Task Created + Task Assigned via email
> * **Reset Button**: The "Reset to Defaults" button CLEARS all notifications (sets everything to empty)
>
> If you want to restore a member to the new member defaults, manually enable Task Created and Task Assigned with Email channel.

### Example Configurations

#### Scenario 1: Manager wants all notifications

**Goal**: Get notified about everything via email and SMS

**Configuration**:

* Scope: Team-wide
* Events: Check ALL events
* Channels: Check Email AND SMS for all events

#### Scenario 2: Reduce notification overload

**Goal**: Only get notified when tasks are assigned to them

**Configuration**:

* Scope: Team-wide
* Events: ONLY check "Task Assigned"
* Channels: Email only
* Result: No notifications for task creation, calls, texts, etc.

#### Scenario 3: Different settings per phone number

**Goal**: Get all notifications for Restaurant line, only urgent for Office line

**Configuration for Restaurant line**:

* Scope: Select "Restaurant Line" phone number
* Events: Check all events
* Channels: Email + SMS

**Configuration for Office line**:

* Scope: Select "Office Line" phone number
* Events: Only "Task Created" and "Task Assigned"
* Channels: Email only

**Note**: Phone-specific settings override team-wide settings. If a user has phone-specific preferences set, their team-wide preferences are automatically removed to avoid confusion.

## Managing SMS Notifications

### Adding Phone Numbers for SMS

Before members can receive SMS notifications, they need a phone number on their account:

1. Go to **Settings** → **Members**
2. Find the team member
3. Click on the "SMS Phone" field
4. Enter their phone number (e.g., +15551234567)
5. Press Enter or click the checkmark to save

**Phone Number Format**: Must be in E.164 format starting with country code:

* ✅ Correct: `+15551234567`
* ❌ Incorrect: `555-123-4567` or `5551234567`

### Validating Contact Methods

The system automatically validates that users have required contact information:

* Trying to enable **Email** notifications? Email must be on account
* Trying to enable **SMS** notifications? Phone number must be on account

If validation fails, you'll see an error message explaining which contact method is missing.

## Understanding Member Roles

Different roles have different notification access:

| Role        | Default Access                                   |
| ----------- | ------------------------------------------------ |
| **Owner**   | Can configure notifications for all team members |
| **Admin**   | Can configure notifications for all team members |
| **Manager** | Can configure notifications for assigned members |
| **User**    | Can only edit their own notification preferences |

**Note**: Managers and Admins can only see/edit notifications for members they manage. If they have no specific assignments, they can manage all members.

## Best Practices

### Preventing Notification Fatigue

1. **Start minimal** - New members get only critical notifications (Task Created, Task Assigned)
2. **Add gradually** - Let members opt-in to additional notifications as needed
3. **Use phone-specific settings** - Different phone lines may need different urgency levels
4. **Leverage roles** - Managers might need more notifications than regular users

### Recommended Configurations by Role

#### Owners/Admins

```
Events: Task Created, Task Assigned, Call Received
Channels: Email
Scope: Team-wide
```

Get visibility into tasks and calls without SMS overload.

#### Managers

```
Events: Task Created, Task Assigned, Task Completed
Channels: Email + SMS for Task Assigned only
Scope: Team-wide or specific phone numbers
```

Stay informed about task lifecycle, get immediately notified when tasks assigned.

#### Regular Users

```
Events: Task Assigned
Channels: Email
Scope: Team-wide
```

Only get notified about tasks assigned to them - minimal distraction.

#### Support Team Members

```
Events: Question Created, Task Created
Channels: Email + SMS
Scope: Specific phone number (support line)
```

Immediate notification when customers have questions.

## Viewing Current Settings

To see what notifications a member currently receives:

1. Go to **Settings** → **Notification Preferences**
2. Look under each member's name
3. You'll see a summary like:
   ```
   📞 Restaurant Line (+15551234567):
   Task created → Email, SMS
   Task assigned → Email

   🔔 Team-wide:
   Call completed → Email
   ```

This shows:

* **Icon**: 📞 for phone-specific, 🔔 for team-wide
* **Scope**: Which phone number or "Team-wide"
* **Active notifications**: Event → Channels enabled

If you see "No notifications configured", the member has no custom preferences set. **New members** will use system defaults (Task Created + Task Assigned via email), while members who clicked "Reset to Defaults" will have all notifications disabled.

## Troubleshooting

### Member not receiving notifications

**Check these items:**

1. **Is the event enabled?**
   * Open their notification settings
   * Verify the specific event type is checked

2. **Is the channel enabled?**
   * Check if Email or SMS is enabled for that event
   * For SMS, verify they have a phone number on their account

3. **Scope conflicts?**
   * Phone-specific settings override team-wide settings
   * If they have a phone-specific preference set to "no notifications", team-wide won't apply

4. **Contact information?**
   * Email notifications require valid email address
   * SMS notifications require phone number in E.164 format

### Notifications going to wrong people

**Task Assigned behavior**: Only notifies the person the task is assigned TO, not the whole team. This is intentional to reduce noise.

**Check assignments**: For other events, verify:

* Are they assigned to specific phone numbers?
* Do they have the right scope selected (team-wide vs phone-specific)?

### Can't enable SMS notifications

**Error**: "You cannot enable notifications for channels you don't have contact information for"

**Solution**:

1. Go to Settings → Members
2. Add the user's phone number in the "SMS Phone" column
3. Return to Notification Preferences and try again

### "Reset to Defaults" cleared all notifications

**What happened**: The "Reset to Defaults" button removes all notification preferences, which means NO notifications will be sent.

**To restore new member defaults**:

1. Open the member's notification settings
2. Enable "Task Created" → Email
3. Enable "Task Assigned" → Email
4. Save preferences

## API Reference (for developers)

### Endpoints

```
GET    /api/teams/{team}/notification-preferences
GET    /api/teams/{team}/notification-preferences/users/{user}
PUT    /api/teams/{team}/notification-preferences/users/{user}
PATCH  /api/teams/{team}/notification-preferences/users/{user}/phone
```

### Data Structure

```json theme={null}
{
  "event_channel": {
    "task_created": ["email", "sms"],
    "task_assigned": ["email"],
    "task_updated": [],
    "task_completed": ["email"],
    "call_received": [],
    "text_sent": [],
    "question_created": ["email"]
  }
}
```

## Related Documentation

* [User Roles & Permissions](/user-roles) - Understanding role hierarchy
* [Integrations](/integrations) - How integrations trigger notifications

## Support

If you need help configuring notifications for your team, contact [support@answeringagent.com](mailto:support@answeringagent.com) or check the in-app help documentation.