Sending an agent a pop-up with the send_notification function

Supervisors sometimes need to reach a live Agent without picking up the phone or walking across the floor. The send_notification function handles this: it pushes a pop-up alert directly onto an active agent's screen through an HTTP call to the Non-agent API. The message appears in the agent interface's alert box, with optional styling and a confetti animation if you want to mark a milestone.

The function can target a single user, everyone in a user group, or every agent currently logged into a specific Campaign. If the target agent is not logged in at the scheduled delivery time, VICIdial holds the notification for up to one minute after the scheduled time, then discards it.

How a notification reaches the agent screen

sequenceDiagram
  participant App as Supervisor App
  participant API as non_agent_api.php
  participant DB as notification queue
  participant AGC as Agent Screen
  App->>API: send_notification recipient=6666 recipient_type=USER
  API->>DB: queue notification for delivery
  DB-->>API: notification queued
  API-->>App: SUCCESS notification queued
  AGC->>DB: poll for pending notifications
  DB-->>AGC: notification payload
  AGC->>AGC: display alert box and confetti

Required and optional parameters

Two parameters are required. recipient_type must be USER, USER_GROUP, or CAMPAIGN. recipient must match the type — a user ID for USER, a valid user group name for USER_GROUP, or a campaign ID for CAMPAIGN. If you pass a recipient value but omit the type, VICIdial tries to resolve the type by looking up the recipient as a user ID first, then a user group, then a campaign.

The notification_text parameter carries the message body. Spaces in the text must be replaced with plus signs in the URL: notification_text=Ten+minutes+to+closing. If you omit the text, the alert box still appears but it will be empty.

Text styling uses four optional parameters. text_size accepts a numeric point size (default 12). text_font accepts a font name (default Arial). text_weight accepts bold, italic, or underline — or a combined string like bold,underline (default is bold). text_color takes a color name or hex value (default black).

Confetti settings and scheduling

Set show_confetti=Y to trigger an animation on the agent screen. Three more optional parameters tune the animation: duration (1–10 seconds), MaxParticleCount (up to 9,999 particles), and ParticleSpeed (up to 100). If you do not set these, VICIdial reads defaults from the system settings container named CONFETTI_SETTINGS. If that container does not exist either, the system falls back to 2 seconds, 2,350 particles, and a speed of 60.

The optional notification_date parameter accepts a date and time in yyyy-mm-dd HH:ii:ss format. This lets a supervisor schedule a message to fire at a specific time — useful for shift-change announcements or timed contest updates. If the date is omitted, delivery happens immediately.

# Send a styled notification to a full user group with confetti
http://server/agc/api.php?user=6666&pass=1234&function=send_notification&source=test&recipient=AGENTS&recipient_type=USER_GROUP&show_confetti=N&notification_text=Ten+minutes+to+closing&text_size=36&text_color=9900FF&text_weight=bold,italic,underline

The Agent session receiving the notification does not need to take any action — the alert renders automatically. If you are targeting a campaign, only agents who are logged into that campaign at the time the notification fires will see it. Agents who log in after the one-minute delivery window closes will not receive it.

For more on how the Non-Agent API and Agent API differ, see the Non-Agent API vs Agent API comparison. For the complete function list and where send_notification fits in the broader picture, visit the VICIdial API and AGI overview. Every VICIfast plan ships with a fully configured VICIdial server in under 40 seconds, API access included.