Custom alerts

NOTE: This is the documentation for websocket channel custom_alerts. Websocket access for personal use is only available through the Advanced plan. Unlike the other websocket channels, custom_alerts is a per-user stream. You only receive notifications that match the alert configurations on the Unusual Whales account that owns the API token used to connect. Configure alerts on https://unusualwhales.com/notifications; every notification fired against your account is also delivered on this channel. You can find fully-functional examples that stream data from many channels here:

Connect to the websocket URI: wss://api.unusualwhales.com/socket?token=<YOUR_API_TOKEN> then join the channel: custom_alerts. Payload format:

[
  "custom_alerts",
  {
    "name": "Aggressive ask-side flow on AAPL",
    "noti_type": "flow_alerts",
    "user_noti_config_id": "f80a7f23-2cf6-4bc2-b7cd-2cb13e7a9a80",
    "user_id": "0d5b0a13-b9d8-4f3b-8a4f-7c6c9a9a1b40",
    "symbol": "AAPL",
    "symbol_type": "stock",
    "tape_time": "2026-04-27T14:32:11Z",
    "meta": {}
  }
]

meta is a free-form object whose shape depends on noti_type.

Field reference

Field	Type	Description
`name`	string	The alert configuration’s display name.
`noti_type`	string	The kind of alert that fired (e.g. `"flow_alerts"`, `"price_alert"`, `"news"`). Determines the shape of `meta`.
`user_noti_config_id`	uuid string	Identifier of the alert configuration that produced this notification. Use this to group alerts by the rule that fired them.
`user_id`	uuid string	Account that received the alert (always the account associated with the API token).
`symbol`	string \| null	Symbol the alert is about, if applicable.
`symbol_type`	`"stock"` \| `"option_chain"` \| null	Tells you how to interpret `symbol`.
`tape_time`	ISO 8601 string	Time the alert fired, UTC.
`meta`	object	Free-form payload whose shape depends on `noti_type`.

Overview

Channels

Field reference