Notification & Approval System Overview

The Unified Notification and Approval System provides proactive multi-channel notifications for all AI agent approval workflows. Instead of requiring administrators to manually check the admin console for pending approvals, the system pushes notifications via Email and Microsoft Teams with one-click approve/deny actions.

Purpose

When AI agents encounter situations requiring human oversight, they create approval requests. Without notifications, these items sit in passive queues until an administrator happens to check. The notification system solves this by:

• Pushing notifications to administrators via Email and Teams as soon as an approval is needed
• Enabling one-click actions so approvers can respond without logging into Control Bridge
• Consolidating all approval types into a single, configurable notification framework
• Logging every notification for audit and compliance

Supported Approval Types

The notification system covers five approval types across the platform:

Approval Type	Description	Triggered By
Escalations	Agent needs human input for a decision	Escalation Router (request_human_input tool)
Safety Reviews	High-risk content flagged by the Safety Gateway	Safety Gateway rule violations
Email Approvals	Agent wants to send, reply to, or forward an email	Email processing agents
Agent Creation	A new agent was requested and needs approval	Agent Self-Service
QuickBooks Write	A financial write operation needs approval	QuickBooks integration

Notification Channels

Each approval type can be configured to send notifications through one or both channels:

Email Notifications

Email notifications are sent from your organization's shared escalation mailbox (the same mailbox used by the Escalation Router). Each email includes:

• A branded header with your organization context
• Approval-type-specific details (agent name, reason, risk level, etc.)
• Approve and Deny buttons that link to the Approval Action Portal
• An urgency indicator for high-priority items
• A link to the admin console for detailed review

Microsoft Teams Notifications

Teams notifications are sent as Adaptive Cards via the AICOS bot to each recipient's personal chat. Each card includes:

• A header with the approval type and urgency level
• Key facts about the approval request
• Inline Approve and Deny buttons that process directly within Teams
• After action, the card updates in place with the result

info

Teams notifications require the AICOS bot to be installed for your tenant and the recipient to have an active conversation with the bot. If either prerequisite is not met, the Teams channel is silently skipped and the email channel delivers the notification.

Default Channel Configuration

Each approval type has a sensible default configuration:

Approval Type	Email	Teams
Escalations	On	On
Safety Reviews	On	On
Email Approvals	On	Off
Agent Creation	On	Off
QuickBooks Write	On	Off

Notification channel defaults are fixed at the system level. To customize recipients for a specific approval type, contact your platform administrator or configure recipients directly in the relevant workflow settings.

How It Works

When an AI agent triggers an approval workflow, the notification system follows this sequence:

Agent Triggers Approval
         |
         v
+-------------------------+
|  Notification Service   |
|  notify()               |
+-------------------------+
         |
         v
  1. Resolve Recipients
     (Configured > Platform Admins fallback)
         |
         v
  2. Resolve Channels
     (Email and/or Teams per config)
         |
         v
  3. Generate Action Tokens
     (One per recipient per action)
         |
         v
  4. Dispatch Notifications
     (Email + Teams in parallel)
         |
         v
  5. Log to NotificationLog

Recipient Resolution

Recipients are determined using a 3-tier resolution strategy:

1. Explicit recipients - Some approval flows (like escalations) already know the approver. These recipients are used directly.
2. Configured recipients - If you configure specific recipients for an approval type in Notification Preferences, those users receive the notification.
3. Platform Admins fallback - If no recipients are configured, all users with the Platform Admin role receive the notification.

Action Tokens

Each notification generates unique, time-limited action tokens for every recipient and action combination. For example, a single email approval sent to 2 recipients generates 4 tokens (2 recipients x 2 actions: approve and deny).

Action tokens provide:

• Single-use protection - Once a token is consumed, it cannot be reused
• Sibling invalidation - When any recipient takes action, all other tokens for the same approval are invalidated, preventing conflicting actions
• Configurable expiry - Tokens expire after a set period (default: 72 hours, configurable from 1 to 720 hours)
• Audit trail - Every token usage records the IP address and timestamp

Fire-and-Forget Design

Notification delivery never blocks the approval workflow. If a notification channel fails (for example, the Teams bot is not installed or the email service is temporarily unavailable), the failure is logged but the approval item remains in its queue for manual review in the admin console.

Prerequisites

Before notifications can be sent, ensure:

1. Escalation Router configured - Email notifications are sent from the shared mailbox configured in the Escalation Router. Navigate to Manage > Escalation > Escalation Router to verify setup.
2. Microsoft 365 connection - Required for sending email notifications via Microsoft Graph API. Configure in Build > Connections > Microsoft 365.
3. AICOS bot installed (for Teams notifications) - The Teams bot must be installed for your tenant. Configure in Build > Connections > Team Messaging.

Security

The notification system includes multiple security layers:

Feature	Description
UUID-based tokens	128-bit entropy tokens that cannot be guessed
Single-use tokens	Consumed tokens cannot be replayed
Sibling invalidation	Prevents conflicting approve/deny from multiple recipients
Configurable expiry	Tokens become invalid after the configured period
Rate limiting	30 requests per minute per IP, 5 attempts per token
Two-step confirmation	Email links open a confirmation page before processing
IP logging	Every action records the actor's IP address
Tenant isolation	Tokens are scoped to a specific tenant

Related Topics

• Approval Action Portal - How one-click actions work from email and Teams
• Escalation Router Overview - Understanding the escalation system
• Safety Gateway Overview - How safety reviews are triggered
• Agent Self-Service Overview - How agent creation approvals work