Skip to main content

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 the responsible owner via Email or Teams as soon as an approval is needed
  • Enabling one-click actions so the owner can respond without logging into Control Bridge
  • Consolidating all approval types into a single, unified notification framework
  • Tracking every notification on a durable queue for audit and compliance

Supported Approval Types​

The notification system covers five approval types across the platform:

Approval TypeDescriptionTriggered By
EscalationsAgent needs human input for a decisionEscalation Router (request_human_input tool)
Safety ReviewsHigh-risk content flagged by the Safety GatewaySafety Gateway rule violations
Email ApprovalsAgent wants to send, reply to, or forward an emailEmail processing agents
Agent CreationA new agent was requested and needs approvalAgent Self-Service
QuickBooks WriteA financial write operation needs approvalQuickBooks integration

Notification Channels​

Each notification is delivered on a single resolved channel, chosen automatically by the system (see Channel Resolution below). It is not a per-approval-type on/off setting.

Email Notifications​

Email notifications are sent from a mailbox in your own tenant, chosen automatically. Outermind uses the first available option in this order:

  1. Your dedicated escalation mailbox, if you have configured one through the Escalation Router
  2. Your AI Chief of Staff's mailbox
  3. Any other active monitored mailbox, most recently updated first
  4. An Outermind system address, used only when your tenant has no monitored mailbox at all

Options 1 through 3 are mailboxes you own, so recipients can reply to the notification. Option 4 is not, so escalation email sent that way carries a note that replies to the address are not monitored and asks the recipient to use the buttons instead.

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 the owner'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 delivery requires the AICOS bot to be installed for your tenant and the owner to have an active conversation with the bot. If either prerequisite is not met, delivery falls back to email.

Channel Resolution​

The delivery channel for each notification is resolved automatically, in this order:

  1. Channel hint - If the originating workflow pins a specific channel, that channel is used.
  2. Trigger type - Otherwise, the type of work that produced the approval maps to a channel (for example, email-triggered work resolves to Email and chat-triggered work resolves to Chat or Teams).
  3. Owner default - Otherwise, the owner's Default Approval Channel preference is used, if set.
  4. Email fallback - If none of the above apply, the notification is delivered by Email.

There is no per-approval-type channel on/off configuration and no admin recipients list; both were retired when the system converged on the single-owner model.

How It Works​

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

Agent Triggers Approval
         |
         v
+-------------------------+
|  enqueueNotification()  |
+-------------------------+
         |
         v
  1. Resolve Owner
     (explicit owner, else the agent's supervising human)
         |
         v
  2. Insert NotificationQueue row
     (NotificationId is the action link id; Status = pending)
         |
         v
  3. Dispatcher resolves the channel
     (hint > trigger type > owner default > email)
         |
         v
  4. Deliver on the single resolved channel
     (Email or Teams)
         |
         v
  5. Update NotificationQueue row state
     (notified / actioned / expired / failed)

Owner Resolution​

Every notification is addressed to a single responsible owner, resolved in this order:

  1. Explicit owner - Some approval flows already know the responsible human. Escalations use the configured escalation recipient; safety reviews use the primary approver. That user is used directly.
  2. The agent's supervising human - Otherwise, the owner is the human who supervises the agent that raised the approval: the Personal Assistant's owner for PA agents, or the agent's Business Owner for CAIOO and standard agents.

If no owner can be resolved, no notification is sent and the approval still waits in its queue for manual review in Control Bridge.

Action Tokens​

Each notification is backed by a single NotificationQueue row. That row's NotificationId doubles as the bearer action token embedded in the Approve and Deny links - there is no separate token table and no per-recipient token fan-out.

The action token provides:

  • Single-use protection - Once the row is marked actioned, the link cannot be reused. Concurrent clicks are guarded atomically, so only the first click wins.
  • Time-limited validity - Each row carries an expiry (default: 72 hours); after it passes, the link no longer works and the approval must be handled in Control Bridge.
  • Audit trail - The row records who acted, when, the action taken, and the actor's IP address.

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. Microsoft 365 connection - Required for sending email notifications via Microsoft Graph API. Configure in Capabilities > Connections > Microsoft 365.
  2. At least one monitored mailbox - Email notifications are sent from a mailbox in your tenant, picked automatically (see Email Notifications above). Most tenants already have one after setting up their AI Chief of Staff or their first monitored mailbox.
  3. AICOS bot installed (for Teams notifications) - The Teams bot must be installed for your tenant. Configure in Capabilities > Connections > Team Messaging.

Configuring the Escalation Router is not a prerequisite for email notifications. A dedicated escalation mailbox changes which address notifications are sent from; it is not required for them to send. See Delivery Modes.

Security​

The notification system includes multiple security layers:

FeatureDescription
UUID-based tokensThe NotificationId is a 128-bit-entropy value that cannot be guessed
Single-use tokensA row marked actioned cannot be replayed; concurrent clicks are atomically guarded
Time-limited expiryTokens become invalid after the row's expiry (default 72 hours)
Rate limiting30 requests per minute per IP, 5 attempts per token
Two-step confirmationEmail links open a confirmation page before processing
IP loggingEvery action records the actor's IP address
Tenant isolationTokens are scoped to a specific tenant