AI Analyst — Notification routing

​

Why route notifications

• A Slack channel where the on-call sees high-severity findings
• An email distribution list for after-hours escalation
• A Teams card for the IR team’s daily standup feed
• A ServiceNow ticket auto-created on Critical alerts
• Anything else Shuffle’s catalog can reach

​

Where it lives in the UI

​

One-time prerequisite: deployment Shuffle connector

1. Connectors → Shuffle (or via SQL: SELECT * FROM connectors WHERE connector_name='Shuffle')
2. Set:
   • connector_url — your Shuffle region (e.g. https://shuffler.io, https://california.shuffler.io)
   • connector_api_key — admin Bearer token from your Shuffle account (Shuffle profile → API key, or POST /api/v1/users/generateapikey)
   • connector_extra_data — your parent Org-Id (optional but helps in some flows)
   • connector_enabled = 1, connector_verified = 1

​

Step-by-step setup for one customer

​

Step 1 — Add a Shuffle integration

1. Open the customer’s AI Notifications tab
2. Click Shuffle integrations
3. Click Add Shuffle integration
4. Fill out:
   • Display name — human label, e.g. Acme Production Shuffle
   • Shuffle org — dropdown populated from your deployment’s Shuffle connector. Picks the org for this customer (top-level or sub-org). Sub-orgs show a · sub-org hint
   • Enabled — leave checked
5. Click Add integration

If the org dropdown is empty or fails to load, the Shuffle connector isn’t configured correctly. See troubleshooting.

​

Step 2 — Authenticate the apps you want to use

• Inside Shuffle’s UI directly (shuffler.io → Apps → connect Slack/ Outlook/etc.)
• From CoPilot’s “Manage apps” drawer — clicks through to Shuffle’s OAuth dance

1. Shuffle integrations sub-tab → click the catalog icon on the integration row
2. The drawer opens with Shuffle’s app picker scoped to this customer’s org
3. Search for the app you want (Slack, Outlook, Teams, Gmail, ServiceNow, etc.)
4. Click the app — Shuffle opens an OAuth window in a new tab
5. Authenticate in Shuffle, return to CoPilot
6. The new app is now available for routes that target this org

Apps authenticated inside Shuffle directly will also appear here — the drawer is a convenience, not a requirement.

​

Step 3 — Create a notification route

1. Open Routes sub-tab → Add route
2. Fill out:
   • Name — human label, e.g. SOC Slack #alerts
   • Minimum severity — only investigations at this tier or higher fire this route. Pick from Critical (only), High and above, Medium and above, Low and above, Informational and above (everything)
   • Channel — locked to Shuffle
   • Shuffle integration — pick the integration you created in Step 1
   • Shuffle app — pick from the dropdown of apps authenticated in this org (Step 2)
   • Destination hint — free-form text that’s prepended to the outgoing message as a Send to <hint>: … instruction so Shuffle’s app agent knows where to deliver inside that app:
     • For Slack: #soc-alerts or #general
     • For Outlook / Gmail: soc@example.com
     • For Teams: a channel name or webhook target
     • For ServiceNow: ticket queue or assignee
   • Custom message template — leave empty for the default body. If you set one, include {{summary}} somewhere or the AI’s finding will be dropped from the message
   • Enabled — leave checked
3. Click Create route

​

Step 4 — Test by triggering an investigation

1. Pick any alert in Incident Management → Alerts for this customer
2. Click the AI Analyst tab on the alert
3. Click Investigate with AI Analyst if no report exists
4. Wait ~30–90 seconds for Talon to finish
5. Check the route’s destination — Slack channel, mailbox, etc.

curl -X POST "${COPILOT_URL}/api/notifications/dispatch" \
  -H "Authorization: Bearer ${COPILOT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_code": "00001",
    "alert_id": 147,
    "trigger": "investigation_complete",
    "severity_assessment": "Critical",
    "summary": "Test notification — ignore",
    "alert_name": "Manual smoke test"
  }'

​

Step 5 — Verify in the dispatch log

• When — timestamp
• Alert — alert ID
• Trigger — the event type (investigation_complete)
• Status — sent (success), failed (provider error), or skipped (idempotency hit — same alert already dispatched for the same route+trigger)
• Latency — provider call duration
• Error / Preview — error message on failures, or the first 500 chars of the rendered body

​

End-to-end example: Slack #soc-alerts for High+ findings

1. Shuffle prerequisite: Slack workspace authenticated in Acme’s Shuffle org as the Slack app (done either in Shuffle’s UI or via Step 2 above)
2. Add Shuffle integration:
   • Display name: Acme Shuffle
   • Shuffle org: Acme Corp (3a8c…) (picked from dropdown)
3. Add notification route:
   • Name: SOC Slack #soc-alerts
   • Minimum severity: High and above
   • Shuffle integration: Acme Shuffle
   • Shuffle app: Slack
   • Destination hint: #soc-alerts
   • Custom template: empty
4. Trigger test investigation on a High-severity alert
5. Dispatch log shows sent row with ~300 ms latency, shuffle_execution_id=exec-…
6. Slack #soc-alerts receives a message with the alert summary and severity

​

Common patterns

​

How filtering actually works

1. Route is enabled
2. Route’s trigger matches the dispatch’s event type (currently always investigation_complete)
3. Investigation’s severity is at-or-above the route’s min_severity (Informational < Low < Medium < High < Critical)

​

Custom message templates

:rotating_light: *{{severity}}* finding on alert #{{alert_id}}

{{summary}}

<{{report_url}}|Open in CoPilot>

Watch out: if your template doesn’t reference {{summary}}, the actual investigation finding gets dropped. The route fires but recipients see only what’s in the template literal. Always include {{summary}} somewhere unless you genuinely want a content-free teaser.

​

Troubleshooting

​

Safety & guardrails

• Per-customer scope — routes attached to customer A’s integrations only fire on customer A’s alerts. CoPilot’s dispatcher refuses to cross tenant boundaries even if a route is hand-edited to point at another customer’s integration.
• Best-effort delivery — a notification dispatch failure never fails the underlying investigation. Talon’s report is written before the dispatch attempt; failures are logged but don’t propagate.
• No automatic retries — a failed dispatch waits for the next Talon run on the same alert (or a manual re-trigger) to overwrite the log row. Phase 4 may add automatic retry semantics for transient failures.
• Admin-tier auth — only users with admin or analyst scope can read or modify routes. Operator-tier users see investigation reports but not the routing config.
• Org auth tokens visible to admins — the Manage apps drawer fetches a per-org auth token from Shuffle so the embedded picker can show authenticated apps. This token is exposed to the admin’s browser session for the duration of the drawer being open. Don’t share screenshots of the drawer with non-admins.

​

Related

• AI Analyst (Talon) — the investigation engine that produces the reports being routed
• AI Analyst — Analyst review workflow — review and grade the reports after they’re produced