Notify agent

Shows a brief toast on the agent's softphone — e.g. "VIP customer calling" or "First-time caller". Cheaper than a screen pop and easy to compose with cont…

type: agentNotify status: stable sinceVersion: 0.1.0 seeAlso: [screenPop] keywords: ["agentNotify", "notify", "agent", "agent experience"]

What it does

Shows a brief toast on the answering agent's softphone — a one-line cue like "VIP customer calling", "First-time caller", or "Account flagged" that surfaces in the corner of the agent's screen and auto-dismisses on its own. It's the cheapest of the three agent-facing nodes: agentNotify ships only a string, severity, and an optional sound, where screenPop ships a full HTML card or opens a real URL.

The toast is published over the per-user realtime channel, so only the agent who actually picked up the bridge sees it — not every agent in the org. Like the pop nodes, this only works inside an onAgentAnswered chain because the worker uses state.triggerAgent.userId to route the message. Toasts are fire-and-forget: there's no acknowledgement, no return value, no case routing — the flow advances down the next edge as soon as the publish succeeds.

When to use it

• Flag VIP or high-priority callers when the agent picks up
• Pair with contactLookup to whisper "First-time caller" on the not-found branch and "Returning customer (last seen 14 days ago)" on the found branch
• Surface a queue-derived label ("From sales line", "Spanish queue") so the agent opens the call in the right register
• Pop a soft warning ("Account on hold — verify before discussing balance") that doesn't deserve a full HTML card
• Wire to a custom sound preset for unmistakable cues on busy desks

If you need a rich card or a clickable URL, use screenPop (pick Custom HTML or URL as the pop type).

Configuration

Shows a brief toast on the agent's softphone — e.g. "VIP customer calling" or "First-time caller". Cheaper than a screen pop and easy to compose with contactLookup. Only works inside an "On agent answered" chain.

Outgoing events: __next

Examples

VIP toast on agent answer

Inside an onAgentAnswered chain, fire a success-severity toast that includes the contact's display name.

{
  "id": "notify-vip",
  "type": "agentNotify",
  "config": {
    "message": "VIP customer: {{contact.displayName}}",
    "severity": "success",
    "durationMs": 6000,
    "sound": "chime"
  },
  "on": { "__next": "agent-whisper" }
}

Warning with a longer dwell

When the contact tag includes "flagged", drop a warn toast and keep it on screen for ten seconds so the agent has time to read it.

{
  "id": "notify-flagged",
  "type": "agentNotify",
  "config": {
    "message": "Account flagged — verify ID before balance details",
    "severity": "warn",
    "durationMs": 10000
  },
  "on": { "__next": "end" }
}

Gotchas

• Only fires inside an onAgentAnswered chain. Outside that scope the worker has no state.triggerAgent.userId and silently skips the node with a warning in the log. The flow still advances.
• Empty message is a no-op. The worker checks for a non-empty rendered string and drops the publish if the template resolves to empty. Useful to know when chaining off contact fields that may be null.
• Severity is clamped. Only info, success, and warn are honored — anything else (typo, custom severity) falls back to info. There is no error severity; this is meant for cues, not alerting.
• Templates render server-side at fire time. The toast is a snapshot of vars and contact when the node executes. Mutating vars afterwards has no effect on the toast already on screen.
• No queue, no replay. Toasts are forwarded over Redis to the agent's live websocket. If their softphone is offline at the moment of publish, the toast is lost — there is no retry on reconnect.
• sound accepts a preset name or a public audio URL. Unknown preset names fall back to silent. Audio URLs must be reachable by the softphone (CORS-clean) or the toast appears without sound.