x-hoppers Smart Notifications
This guide explains how to configure x-hoppers smart notifications feature.
Use cases for passing dynamic variables: x-hoppers dynamic variables use cases.
Created: October 2024
Updated: May 2025
Permalink: https://x-hoppers.atlassian.net/wiki/x/EoCeB
Introduction
The smart notifications feature in x-hoppers enables instant alerts to be broadcasted to store associates when specific events are triggered, such as an assistance requests from till points, QR code-based smart call points or security alerts, etc. This functionality integrates with various devices, including call buttons, cameras, POS systems, through a dedicated Smart Notifications API.
Requests are sorted into multiple queues, with a separate queue for each broadcast. When an event is triggered, store associates receive audio notifications directly on their headsets, as well as text notifications via a mobile or web app. Once an associate accepts a notification by double pressing the Push-to-talk button, the system informs everyone in the broadcast that the request is being handled by a specific associate.
It is also possible to send private notifications to specific store associates. Private notifications are played after the current public ones finish. Meanwhile, public notifications continue broadcasting while the user listens to their private messages.
Requirements
Setup
Make an HTTP request
To initiate a smart notification HTTP request, use the parameters described below. Full details on the parameters can be found in the API documentation or at your PBX https://{subdomain}.wildixin.com/api/v1/doc/#tag/Smart-Notifications/operation/addSmartNotification.
Parameter | Description | Type | Required | Default | Examples / Valid values |
|---|---|---|---|---|---|
| Source of the event (area, department, camera etc.) | string | yes |
| Example: Camera1, Till Point 4, Frozen Food |
| Type of notification desired | string | yes |
| Valid: |
| Description of the event | string | yes |
| Example: help needed, theft, dwell_time_exceeded, queue, private message |
| Message to announce in the broadcast or as a private message | string | yes |
| Example: Help needed at Till Point 3, Theft detected at Canned Food Area |
| ID of the target broadcast | string | yes |
| Broadcast ID. Copy it from the broadcast URL in x-hoppers admin -> Broadcasts -> click Edit, see the picture below:
|
| User extension number to get private messages | string | yes |
| Example: 100, 2503, 5784 |
| Frequency (in seconds) for repeating the request | integer | optional | 10 | Valid range: 5–30 |
| Time (in seconds) to wait for confirmation | integer | optional | 30 | Valid range: 0–600 |
| Time (in seconds) the queued request waits before processing | integer | optional | 60 | Valid range: 5–600 |
| Source of the request | string | optional | NULL | Example: QR, AIVA, Tablet, Task management SW, CallButtons, x-hoppers app |
| Priority of notification (FIFO by default) | integer | optional | 0 | Valid: positive integers |
| Custom request ID passed to the data engine | string | optional |
| Example: UUID |
Default settings for timeouts, TTL and repeat frequency can be customized with the following environment variables added to /etc/systemd/system/pbx-data-engine.service.d/override.conf file:
XHOP_SMART_NOTIFICATION_CONFIRMATION_TIMEOUT: timeout period for a confirmationXHOP_SMART_NOTIFICATION_QUEUE_TIMEOUT: timeout for queued requestsXHOP_SMART_NOTIFICATION_PLAY_FREQUENCY: frequency for repeating the notification playback[Service] Environment='XHOP_SMART_NOTIFICATION_CONFIRMATION_TIMEOUT=65' Environment='XHOP_SMART_QUEUE_TIMEOUT=65' Environment='XHOP_SMART_PLAY_FREQUENCYT=65' ExecStart= ExecStart=/usr/sbin/pbx_data_engine.py --daemon
Configure Dialplan
To configure smart notifications for playback on x-hoppers headsets, proceed with the following steps:
Download the provided procedure
Access x-hoppers admin and navigate to Dialplan menu, Dialplan rules tab
Click Import, select the procedure and click Apply to finish
The imported procedure contains the following called numbers:
announce - plays an initial or repeated notification to available store associates
call_announce - plays notification about a Call group call to available store associates
cancelled / call_cancelled - triggered when a request/ call is cancelled
confirmed/ call_confirmed - triggered when an associate accepts a request/ call
expired / call_expired - called when TTL (Time to live) of a queued request/ call expires
join_conference - connects to a broadcast to announce a request
playback_finished - triggered after the announcement playback is complete. This handler marks the playback as finished and is used to finalize the process for the current notification
timedout/ call_timedout - activated when a request/ call times out without an associate’s response
You can customize confirmed, call_confirmed, expired, call_expired, timedout, and call_timedout numbers by modifying the confirmation or timeout message, setting an external API etc. To further customize the notification process, use the following channel variables:
Variable | Description |
|---|---|
conf_id | Broadcast ID associated with the request |
message | Base64-encoded message to be announced in a broadcast |
request_id | Unique identifier (UUID4 format) for each request |
extension | Extension of the associate who accepts the request |
name | LDAP name of the associate who accepts the request |
received | Timestamp of when the request is received |
started | Timestamp of when the request starts processing |
finished | Timestamp of when the request is confirmed, timed out or expired |
from | Base64-encoded "from" parameter of the request origin |
notification_type | Base64-encoded type of notification for the request |
event | Base64-encoded event type associated with the request |
origin | Base64-encoded origin data of the request |
custom_rid | Custom ID parameter from the request |
cancel_reason | Base64-encoded reason of request cancellation |
cg_id | ID of the Call group the notification came from (only for notifications generated by Call groups) |
cg_name | Base64-encoded name of the Call group the notification came from (only for notifications generated by Call groups) |
caller_num | Base64-encoded caller number (only for notifications generated by Call groups) |
caller_name | Base64-encoded caller name. Used only if caller name was found in the system (only for notifications generated by Call groups) |
cg_agent | Base64-encoded name of the agent who answered the call. Used only if the call was answered by a regular Call group agent, not by broadcast user via the smart notification (only for notifications generated by Call groups) |
Configure Call Group Notifications
Starting from WMS 7.01.20250506.2, it is possible to deliver Call group calls to x-hoppers broadcast.
Note: Only Call groups with call group strategies Call All 10 / Call All 32 are supported.
Access x-hoppers admin and navigate to Dialplan menu, Call Groups tab
Choose the necessary Call group and click Edit strategy
Navigate to the Broadcast field and choose the required broadcast:
In the Broadcast Priority field, you can set priority for the Call group call notifications. E.g. if the Broadcast Priority is 0, the call group call is added to the queue and played after the rest of the notifications that are already in the queue; in case you set Broadcast Priority to 1, the call group call notification is played immediately after the current notification ends, if any
Click Save to apply the changes